[botzrDev]

Summary

Third roadmap item after local mode (botzrDev/mcp-guard#5) and argument-level policy (botzrDev/mcp-guard#6): evidence. The audit log says a tool was called. The flight recorder keeps what was asked, what came back, and what the guard blocked, in order, in a form that can be proven unedited.

What it records

Every mcp-guard serve session becomes one JSONL file: each client request, each response the guard returns, upstream notifications, and every guard decision (policy_deny, pin_deny, policy_would_deny, tool_hidden_policy, tool_hidden_pin). session_start carries the upstream command, config path, policy mode and guard version; session_end says why the session ended.

Tamper evidence

Each record carries prev (the previous record's hash) and hash (over its own contents prefixed by prev). Editing, deleting, inserting or reordering a record breaks the chain at a known point. With [recorder] signing_key_env set, hashes are HMAC-SHA256 under a shared key, so a forger who can edit the file but lacks the key cannot rechain it. The docs are explicit about what plain hashes do and do not protect against.

Redaction

Payloads are redacted before hashing: built-in patterns for private key blocks, AWS, GitHub, Slack, OpenAI, Anthropic, Google, Stripe and mcp-guard keys, JWTs, bearer tokens and user:password@ URLs, plus the user's [audit] redaction_rules. Oversized payloads are truncated to a preview. payload_sha256 is the hash of the original, so a payload you still hold can be matched to a record without the recording containing the secret.

New commands

• mcp-guard replay [--list] [--session latest|<id>|<file>] [--denied] [--tool X] [--json] renders a session as a timeline and reports chain status.
• mcp-guard verify [--session latest|all|...] [--json] recomputes the chain, names the first bad record, exits 1 on tampering, and checks HMAC signatures when the key is present (marks OK* when it is not).

mcp-guard wrap enables recording for every wrapped server under <config dir>/recordings/<client>-<server>/. doctor reports RECORDER_DISABLED. Recorder failures are logged and never block the agent; nothing is ever written to stdout.

Docs

New docs/flight-recorder.md (format, field table, redaction, the tamper-evidence model and its limits, operations). Updated docs/local-mode.md, docs/configuration.md, docs/cli.md, the config template, CHANGELOG, README and CLAUDE.md.

Verification

Check	Result
cargo fmt --all -- --check	pass
cargo clippy --all-features -- -D warnings (CI command)	pass
RUSTDOCFLAGS=-D warnings cargo doc --no-deps --all-features	pass
cargo test --all-features	all suites pass
cargo test --workspace	all suites pass

New tests:

• Unit: chain construction and verification; tamper detection for edit, removal, reorder and a garbage line; signed chains with the right key, wrong key and no key; redaction of built-in and user patterns with the original hash preserved; truncation; include_results = false keeping errors; session listing and selection.
• Proxy: the exact record sequence for an allowed call and a denied call.
• End to end: a live serve session recorded, then replay --list, replay, replay --denied, verify --session all, tampering the file and seeing verify fail with the record number and replay report CHAIN BROKEN; a signed session verified with, without and with the wrong key; clear messages when there are no recordings.

The e2e helper gained a graceful close() that drops stdin and waits, matching how real clients exit, so session_end is exercised.

Next

Recording in gateway mode keyed by identity, retention, and a self-contained HTML session report, then the 2026-07-28 protocol shim.

---

Generated by Claude Code