symbi-audit · diff
git:20260604.2d65c7c to git:20261011.4243b1c
28 added, 72 removed. Audit A to A.
---
name: symbi-audit
- description: Query and analyze the Symbiont audit log of Claude Code tool usage. Works with no runtime — reads the always-on local JSONL log at .symbiont/audit/tool-usage.jsonl — and upgrades to the runtime's cryptographic audit trail when the symbi binary is installed. Use when reviewing tool activity, investigating an incident, or preparing a usage summary.
+ description: Inspect local hook diagnostics or an actual governed run's signed journal.
allowed-tools: ["Bash", "Read"]
---
- # Audit Log Analysis
-
- The plugin records **every** tool call by default — no runtime required. Each
- PostToolUse event appends one JSON line to:
-
- ```
- .symbiont/audit/tool-usage.jsonl
- ```
-
- Line shape:
-
- ```json
- {"timestamp":"2026-06-03T14:22:01Z","tool":"Bash","source":"claude-code"}
- ```
-
- ## Source selection
-
- 1. **Local log (default, no runtime).** Read `.symbiont/audit/tool-usage.jsonl`
- in the project root. This is the source for a plain plugin install.
- 2. **Runtime cryptographic trail (when `symbi` is on PATH).** The Symbiont
- runtime keeps a tamper-evident journal with richer detail (agent identity,
- policy decisions, SchemaPin events). Prefer it when available; query it via
- the `symbi` MCP server tools.
-
- Always start by checking which sources exist:
-
- ```bash
- test -f .symbiont/audit/tool-usage.jsonl && echo "local log present"
- command -v symbi >/dev/null && echo "runtime available"
- ```
+ # Inspect execution evidence
- ## Querying the local log
+ Select the actual evidence source before drawing conclusions.
- Use `jq` when present, with plain-text fallbacks. Examples:
+ ## Local plugin diagnostics
- ```bash
- # Total recorded calls
- wc -l < .symbiont/audit/tool-usage.jsonl
+ `.symbiont/audit/tool-usage.jsonl` contains timestamp, tool, source, phase,
+ input digest and an optional tool-use ID. Decision records include allow/warn/deny;
+ Claude Code's post hook adds completion records. Cursor currently logs decisions
+ only. Raw arguments are omitted.
- # Most recent 20 calls
+ ```sh
+ # Recent recorded events, not a count of completed calls
tail -n 20 .symbiont/audit/tool-usage.jsonl
-
- # Count by tool
- jq -r '.tool' .symbiont/audit/tool-usage.jsonl | sort | uniq -c | sort -rn
- # (no jq) — coarse fallback:
- grep -oE '"tool":"[^"]*"' .symbiont/audit/tool-usage.jsonl | sort | uniq -c | sort -rn
-
- # Calls since a timestamp
- jq -r 'select(.timestamp >= "2026-06-03T00:00:00Z") | "\(.timestamp) \(.tool)"' \
- .symbiont/audit/tool-usage.jsonl
-
- # Just Bash invocations
- jq -r 'select(.tool == "Bash") | .timestamp' .symbiont/audit/tool-usage.jsonl
+ # Optional jq queries
+ jq 'select(.phase == "decision" and .decision == "deny")' .symbiont/audit/tool-usage.jsonl
+ jq 'select(.phase == "completed")' .symbiont/audit/tool-usage.jsonl
```
- The local log records tool *names* and timestamps, not arguments — it answers
- "what kinds of actions ran, and how often," not "what exact command." For
- argument-level detail, use the runtime trail.
-
- ## Querying the runtime trail (when installed)
+ An allow is not proof that a tool ran. Hooks can be disabled or skipped by the
+ harness, writes can fail, and local files can be changed. These are diagnostic
+ records, not a tamper-evident compliance ledger. Do not infer the exact command
+ from its digest or claim complete coverage.
- When `symbi` is on PATH, use the `symbi` MCP server to investigate:
+ ## Governed runtime journals
- - Recent agent activity and what each agent did
- - Policy decisions (which Cedar policies evaluated, allow/deny outcomes)
- - MCP tool usage by agent
- - Security events: failed SchemaPin verifications, policy denials, sandbox
- violations
+ A runtime installation does not create a signed record for standalone plugin
+ activity. For an actual governed run, obtain the journal path, expected run ID
+ and public audit key through a trusted channel. Use:
- ## Workflow
+ ```sh
+ symbi audit inspect /path/to/journal --public-key HEX --run-id UUID
+ ```
- 1. Detect available sources (local log, runtime).
- 2. Ask what the user wants to investigate (recent activity, a specific tool,
- a time window, anomalies).
- 3. Run the appropriate query and present findings in a clear, chronological
- summary.
- 4. Flag anything notable — bursts of destructive-command attempts, blocked
- reads, unusual tool mixes.
- 5. If patterns suggest tightening policy, point to `/symbi-protect`
- (local rules) or `/symbi-policy` (Cedar, runtime).
+ Report validation errors, incomplete or unknown outcomes as such. Do not replay
+ operations to fill gaps. No audit-query MCP tool is implied by `symbi mcp`.
- If neither source exists yet, say so: a fresh project has no log until the
- first tool call is recorded.
+ Present a concise timeline and separate decisions from execution evidence.
+ Suggest policy changes for operator review; do not alter policy controls.