13 / 25
Audit Trails & Provenance
Core Questions
- Who did what?
- In which environment?
- With which credentials?
In regulated industries, "an agent did it" is not an acceptable audit response. You need cryptographic proof of every decision: who initiated the task, what the agent did, which credentials it used, what it produced. When things go wrong, you need to reconstruct exactly what happened.
What to capture
Every agent action should answer these questions:
Audit Record Components
Who
Which agent (identity), requested by whom (human), under what authorization (task/charter reference).
What
Action taken, inputs used, outputs produced. For code: the diff. For commands: input and output.
When
Timestamps for start, key steps, completion. Use consistent timezone (UTC).
Where
Environment ID, machine/container, git commit, branch. Full context for reproduction.
With what authority
Credentials used (not the values), permission scope, any elevated access.
Provenance chain
Provenance traces artifacts back to their origins:
Artifact provenance example
{
"artifact": "docker-image:app:v1.2.3",
"digest": "sha256:abc123...",
"created": "2025-01-15T10:30:00Z",
"provenance": {
"builder": {
"agent": "claude-builder",
"task_id": "task-xyz789"
},
"source": {
"repo": "github.com/org/repo",
"commit": "def456...",
"branch": "main"
},
"charter": "github.com/org/repo/issues/42",
"requested_by": "[email protected]",
"environment": {
"runner": "gha-runner-abc",
"nix_hash": "nixpkgs#abc123"
},
"dependencies": [
{"name": "base-image", "digest": "sha256:..."},
{"name": "node_modules", "lockfile_hash": "..."}
]
},
"signature": "base64-encoded-signature"
}With this chain, you can answer: Where did this artifact come from? Who authorized it? Can I reproduce it? Is it tampered?
Immutable audit logs
Audit logs must be tamper-evident. If someone can modify history, it's not an audit trail.
Immutability Patterns
Append-only storage
Write once, never delete. S3 with object lock, immutable database tables.
Hash chains
Each log entry includes hash of previous. Tampering breaks the chain.
External attestation
Submit log hashes to external transparency service. Third-party proof of existence at time T.
Separate storage
Audit logs stored separately from operational data. Different access controls. Harder to tamper.
Forensic reconstruction
When something goes wrong, you need to reconstruct what happened. Your logs should enable:
- Timeline view: What happened in order?
- Causal chain: What led to what?
- Blast radius: What else was affected?
- Reproduction: Can we recreate this state?
Investigation query patterns
# What did agent X do between time A and B?
SELECT * FROM audit_log
WHERE agent = 'claude-coder'
AND timestamp BETWEEN '2025-01-15T10:00:00Z'
AND '2025-01-15T11:00:00Z'
ORDER BY timestamp;
# What tasks touched file Y?
SELECT DISTINCT task_id FROM audit_log
WHERE action = 'file_modify'
AND path LIKE '%/auth/login.ts';
# Who approved the changes in commit Z?
SELECT * FROM audit_log
WHERE artifact_ref = 'commit:abc123'
AND action IN ('pr_approve', 'merge');What goes wrong
Missing context
Logs say "file modified" but not why, or by which task. Can't reconstruct decision chain.
Logs deleted or rotated
Incident happens. You go to investigate. Logs were rotated last week. Evidence is gone.
Clock skew
Different systems have different times. Timeline reconstruction is impossible. Use NTP everywhere.
Summary
- →Capture who, what, when, where, and with what authority for every action.
- →Build provenance chains tracing artifacts back to source.
- →Make audit logs immutable. Append-only, hash-chained, externally attested.
- →Design for forensic reconstruction. You will need it.
Related Guides
Stay updated
Get notified when we publish new guides or make major updates.
(We won't email you for little stuff like typos — only for new content or significant changes.)
Found this useful? Share it with your team.