Metadata-Version: 2.4
Name: tracegate
Version: 0.1.4
Summary: Inspect and policy-check AI agent runs.
Author: Tracegate
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Tracegate

Policy gates for AI agent traces.

`tracegate` is an audit and policy CLI for AI agent runs.

It does **not** try to be a new agent runtime. The first useful version is forensic: give it a trace from an existing agent system and it tells you what happened, what tools were used, what looked risky, what it cost, and whether the run violated policy.

That is the practical starting point for a "control plane for agents":

```text
Existing agent run -> normalized trace -> inspection -> policy findings -> CI exit code
```

## Why this exists

Teams are already using Claude Code, Codex, OpenAI Agents, LangGraph, CrewAI, and custom agent loops. The common questions are not just orchestration questions:

- What did the agent do?
- Which tools did it use?
- Did it read or edit sensitive files?
- Did network content influence shell or GitHub actions?
- How much did it cost?
- Can this run pass a production policy gate?

`tracegate` starts with those governance questions.

## Current commands

Run from this repository without installing:

```bash
PYTHONPATH=src python3 -m tracegate.cli inspect examples/run.json
PYTHONPATH=src python3 -m tracegate.cli describe examples/run.json
PYTHONPATH=src python3 -m tracegate.cli check examples/run.json examples/policy.yaml
PYTHONPATH=src python3 -m tracegate.cli guard examples/run.json examples/policy.yaml
PYTHONPATH=src python3 -m tracegate.cli summarize examples/run.json --json
PYTHONPATH=src python3 -m tracegate.cli summarize examples/run.json --json --include-raw
PYTHONPATH=src python3 -m tracegate.cli inspect examples/run.json --verbose
PYTHONPATH=src python3 -m tracegate.cli inspect --format codex ~/.codex/archived_sessions/session.jsonl
PYTHONPATH=src python3 -m tracegate.cli import codex ~/.codex/archived_sessions/session.jsonl --out run.json
PYTHONPATH=src python3 -m tracegate.cli inspect --format claude ~/.claude/projects/<project>/<session>.jsonl
PYTHONPATH=src python3 -m tracegate.cli import claude ~/.claude/projects/<project>/<session>.jsonl --out run.json
```

After packaging/installing, the same commands are available as:

```bash
tracegate inspect examples/run.json
tracegate guard examples/run.json examples/policy.yaml
```

Command aliases:

- `inspect`, `describe`, and `summarize` inspect a trace.
- `check`, `guard`, and `policy` evaluate a trace against policy.
- `import codex` converts a Codex session JSONL file into generic `tracegate` trace JSON.
- `import claude` converts a Claude Code project transcript JSONL file into generic `tracegate` trace JSON.

`check` / `guard` / `policy` exit with code `1` when policy violations are found, which makes them usable in CI.

## Example inspection

```bash
PYTHONPATH=src python3 -m tracegate.cli inspect examples/run.json
```

Example output:

```text
Agent: PR Reviewer
Run ID: run-123

Observed Access
---------------
Filesystem: observed (3)
GitHub: observed (1)
Shell: observed (1)
WebFetch: observed (1)

Actions
-------
2 file reads
1 file writes/edits
1 shell commands
1 network fetches
1 GitHub actions

Security
--------
LOW: Prompt injection marker observed: ignore previous instructions
MED: Network content was fetched before a shell command executed.

Risk Posture
------------
MEDIUM

Reason
------
Shell access was used 1 times.
Filesystem read access was used 2 times.
Filesystem write access was used 1 times.
Network fetch access was used 1 times.

Shell Activity
--------------
1 commands

Read-only:            0
Execution:            1
Network:              0
Privilege escalation: 0
Destructive:          0

LOW   low-risk commands: 0
MED   medium-risk commands: 1
HIGH  high-risk commands: 0

Capability Profile
------------------
Filesystem Read:    LOW
Filesystem Write:   HIGH
Shell:              LOW
Network:            HIGH
GitHub:             HIGH
MCP/Discovery:      NONE

Overall Exposure: HIGH

Trust Boundaries
----------------
User Input
  ↓
External Content (1)
  ↓
Filesystem Reads (2)
  ↓
Agent Reasoning
  ↓
Shell Commands (1)
  ↓
Filesystem Writes (1)
  ↓
GitHub Actions (1)

Cost
----
$1.12
```

## Example policy gate

```bash
PYTHONPATH=src python3 -m tracegate.cli guard examples/run.json examples/policy.yaml
```

Example output:

```text
FAILED

Violations
----------
HIGH: Run cost $1.12 exceeds policy limit $1.00.
HIGH: Tool Shell is forbidden by policy.
HIGH: Flow WebFetch -> Shell is forbidden by policy.
HIGH: Flow WebFetch -> GitHub is forbidden by policy.
```

## Input Formats

The current adapters accept generic `tracegate` JSON/JSONL traces, Codex session JSONL traces, and Claude Code project transcript JSONL traces.

### Claude Code Sessions

Claude Code support is opt-in with `--format claude`:

```bash
PYTHONPATH=src python3 -m tracegate.cli inspect --format claude ~/.claude/projects/<project>/<session>.jsonl
PYTHONPATH=src python3 -m tracegate.cli guard --format claude ~/.claude/projects/<project>/<session>.jsonl examples/policy.yaml
```

You can also convert a Claude Code transcript to normalized generic trace JSON:

```bash
PYTHONPATH=src python3 -m tracegate.cli import claude ~/.claude/projects/<project>/<session>.jsonl --out run.json
```

The Claude adapter currently maps:

- `Bash` tool uses to `Shell`
- `Read` tool uses to filesystem reads
- `Edit`, `MultiEdit`, and `Write` tool uses to filesystem edits/writes
- Playwright browser navigation MCP tool uses to network fetches
- user/assistant/system messages to message events
- other tool uses to generic tool events
- discovery/planning tools such as `ToolSearch`, `ListMcpResourcesTool`, `TaskCreate`, and `TaskUpdate` to `Tool Discovery`

### Codex Sessions

Codex support is opt-in with `--format codex`:

```bash
PYTHONPATH=src python3 -m tracegate.cli inspect --format codex ~/.codex/archived_sessions/session.jsonl
PYTHONPATH=src python3 -m tracegate.cli guard --format codex ~/.codex/archived_sessions/session.jsonl examples/policy.yaml
```

You can also convert a Codex session to normalized generic trace JSON:

```bash
PYTHONPATH=src python3 -m tracegate.cli import codex ~/.codex/archived_sessions/session.jsonl --out run.json
```

The Codex adapter currently maps:

- `exec_command` function calls to `Shell`
- `apply_patch` custom tool calls to filesystem edits
- user/agent messages to message events
- other function/custom tool calls to generic tool events

### Generic Trace Format

JSON object:

```json
{
  "id": "run-123",
  "agent": "PR Reviewer",
  "cost_usd": 1.12,
  "runtime_minutes": 7,
  "events": [
    { "type": "file_read", "path": "src/app.py" },
    { "type": "network_fetch", "url": "https://example.com" },
    { "type": "tool_call", "tool": "shell", "input": { "command": "pytest" } },
    { "type": "git_action", "tool": "github", "action": "create_pr" }
  ]
}
```

JSON array:

```json
[
  { "type": "file_read", "path": "src/app.py" },
  { "type": "tool_call", "tool": "shell", "input": { "command": "pytest" } }
]
```

JSONL:

```jsonl
{"type":"file_read","path":"src/app.py"}
{"type":"tool_call","tool":"shell","input":{"command":"pytest"}}
```

Supported event categories today:

- Filesystem: `file_read`, `file_write`, `file_edit`, `write_file`, `read_file`
- Shell: `tool: shell`, `tool: bash`, `type: shell_command`
- Web fetch: `network_fetch`, `web_fetch`, `webfetch`, `tool: WebFetch`
- GitHub: `tool: github`, `tool: gh`, `git_action`

Unknown event types are still preserved and counted.

## Policy format

Policies can be YAML or JSON. The YAML parser intentionally supports only the simple policy shape used by this project, so use JSON if you need richer syntax.

```yaml
limits:
  max_cost_usd: 5
  max_runtime_minutes: 30

max_shell_commands: 5
allow_network: false
allow_file_writes: false

forbidden_tools:
  - shell

forbidden_paths:
  - ".env*"
  - "secrets/*"

forbidden_flows:
  - WebFetch->Shell
  - WebFetch->GitHub
```

Current checks:

- `limits.max_cost_usd`
- `limits.max_runtime_minutes`
- `max_shell_commands`
- `allow_network`
- `allow_file_writes`
- `forbidden_tools`
- `forbidden_paths` using shell-style globs matched against both full path and basename
- `forbidden_flows`

If a policy sets a cost or runtime limit and the trace does not include that telemetry, `tracegate` reports a policy finding. Unknown cost or runtime should not silently pass a governance gate.

JSON output is sanitized by default. It includes normalized event metadata, but omits each event's raw payload and redacts shell command text so traces can be attached to CI logs with less risk. Use `--include-raw` only when you explicitly want a forensic export that may contain prompts, command text, URLs, or other sensitive trace data.

Human inspection output hides exact shell commands by default. Use `--verbose` when you need command-level evidence in the terminal report.

## Built-in security findings

Inspection currently flags:

- Prompt injection markers such as "ignore previous instructions"
- Web fetch followed by shell execution
- Web fetch followed by GitHub action
- Sensitive-looking file paths such as `.env`, `*.pem`, `*.key`, `*secret*`, `*credential*`, `*id_rsa*`, and `*kubeconfig*`

These are heuristics, not a full security engine. The point is to expose the risk pattern in a run report and make it enforceable through policy.

## Tests

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

## What should come next

The next valuable additions are adapters, not a scheduler:

1. OpenAI trace adapter
2. LangGraph run adapter
3. SARIF or GitHub Actions output for CI annotations
4. HTML report for humans
5. Admission-style preflight checks for proposed agent configs

The adoption path should stay simple: do not require teams to migrate runtimes before they can get audit, policy, and observability value.
