Metadata-Version: 2.4
Name: tracegate
Version: 0.1.6
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.

TraceGate checks whether coding-agent runs stayed inside their allowed trust boundary.

## 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 diff safe.json risky.json
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.
- `diff` compares new capabilities, new inferred flows, and risk between two traces.
- `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

Facts
-----
Shell commands: 1
Filesystem reads: 2
Filesystem writes: 1
Network fetches: 1
GitHub actions: 1

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

Risk Posture
------------
HIGH

Reason
------
Shell was used 1 time, including 1 execution command.
Filesystem read access was used 2 times.
Filesystem write access was used 1 time.
Network fetch access was used 1 time.
GitHub actions were used 1 time.

Assessment
----------
This session includes external content followed by action-capable behavior.
The agent ran local execution commands.
No credential access, privilege escalation, or destructive commands were observed.

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

Config inspection:     0
Local data inspection: 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

Attack Surface
--------------
External Content:      PRESENT
Filesystem:            LOCAL READ/WRITE
Sensitive Files:       NONE
Agent Config Access:   NONE
Execution Surface:     SHELL
Privilege Escalation:  NONE
Destructive Actions:   NONE
Network Access:        PRESENT
Credential Access:     NONE

Inferred Patterns
-----------------
HIGH [HIGH confidence]: WebFetch -> Shell (1)
  External content preceded shell execution.

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 diff

```bash
PYTHONPATH=src python3 -m tracegate.cli diff safe.json risky.json
```

Example output:

```text
New Capabilities
----------------
+ External Content
+ Shell Execution

New Flows
---------
+ HIGH: WebFetch -> Shell (HIGH confidence)

Risk
----
LOW -> HIGH

Reason
------
External content can now influence privileged or write-capable actions.
```

Example output:

```text
Policy
------
FAIL

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
allow_git_actions: false
allow_sensitive_files: false

forbidden_tools:
  - shell

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

forbidden_flows:
  - ExternalContent->Shell
  - ExternalContent->FileWrite
  - ExternalContent->GitHub
```

Current checks:

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

Passing policies include a control summary:

```text
Policy
------
PASS

Assessment
----------
This run stayed inside the configured trust boundary.

Checks
------
Shell commands: 11 / 20
Network access: none
File writes: none
GitHub actions: none
Sensitive files: none
Forbidden flows: none
```

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.
