Signed Audit Trails

Signed Audit Trails for Agent Tool Calls

A cookbook-style walkthrough of cryptographically signed receipts on every agent tool call. This is the teaching skill -- it explains and demonstrates the pattern so you can evaluate it before wiring up runtime hooks in production.

What the Pattern Gives You

Every tool call (Bash, Edit, Write, WebFetch) is:

1. Evaluated against a Cedar policy before execution. If the policy denies the call, the tool does not run.
2. Signed as an Ed25519 receipt after execution. Receipts are canonicalized, hash-chained, and verifiable offline by anyone holding the public key -- no network call, no vendor lookup, no trust in the operator.

When the Pattern Fits

• Regulated environments (finance, healthcare, critical infrastructure) needing tamper-evident evidence of agent behavior
• CI/CD pipelines where you must prove a policy gate held for every automated step
• Multi-party collaboration where a counterparty verifies your agent's behavior without trusting your tooling
• Compliance contexts (e.g. EU AI Act Article 12, SLSA provenance) where standard logging is insufficient

Step 1: Policy Gate Before Execution

A pre-tool hook evaluates each call against a Cedar policy. Typical rules:

• Read-oriented tools (Read, Glob, Grep, WebSearch) always allowed
• Bash allowed only for a safe command allow-list (git, npm, pnpm, node, etc.)
• Destructive Bash commands (rm -rf, dd, mkfs, shred) explicitly forbidden
• Writes allowed only within the project directory

Cedar forbid rules take precedence over permit, so destructive commands cannot be re-enabled by a later permissive rule.

Step 2: Sign a Receipt After Execution

A post-tool hook signs a receipt. The first run generates an Ed25519 private key if one does not exist. Commit the public key fingerprint; never commit the private key or the receipts directory (add both to .gitignore).

A receipt captures fields such as: receipt_id, event_time, tool_name, input_hash, decision, policy_id, policy_digest, parent_receipt_id, public_key, and signature. Every field except signature and public_key is covered by the signature -- modifying any field after signing invalidates it. A session of 20 tool calls yields 20 receipts, each hash-chained to its predecessor.

Step 3: Verify the Chain

An offline verifier walks the receipt files and returns:

Step 4: Demonstrate Tamper Detection

Flip a signed receipt's decision field from allow to deny and re-run the verifier: it exits 1 and names the failing receipt, because the signature no longer matches the canonical bytes. Restore the field and verification passes again.

How the Cryptography Works

Three invariants make receipts verifiable offline across conformant implementations:

1. JCS canonicalization (RFC 8785) before signing -- keys sorted, whitespace minimized, strings NFC-normalized, so independent implementations produce byte-identical signing payloads.
2. Ed25519 signatures (RFC 8032) over the canonical bytes -- deterministic, fixed-size, no nonce dependency.
3. Hash-chain linkage -- each receipt references the SHA-256 of its predecessor's canonical form, so insertions, deletions, and reorderings break later receipts.

CI/CD Integration

Gate merges on receipt-chain verification so no build lands with a broken evidence chain. Archive the receipts as a job artifact so the chain survives beyond the run. For agent-built software, the receipt chain can be referenced from SLSA Provenance v1 byproducts, cross-referencing two trust domains (the builder identity and the supervisor-hook identity).

Common Pitfalls

• Private key in version control -- never commit it; rotate immediately if leaked.
• Hook command quoting -- keep tool inputs quoted so values with spaces pass through intact.
• Receipts lost in CI -- upload them as an artifact or the chain ends with the job.
• Missing policy -- treat an absent policy as a hard failure in production, not a silent pass.

Output

A clear explanation or live demonstration of the signed-receipt pattern -- the policy gate, the receipt structure, offline verification, and a tamper-detection demo -- so the reader can decide whether to adopt runtime enforcement.