Audit Trail
Every action taken by every agent is recorded in an append-only, tamper-evident audit log. The audit trail is the definitive record of what happened in the system.
Properties
- Append-only - entries are never deleted or modified
- Hash-chained - each entry includes the SHA-256 hash of the previous entry, making tampering detectable
- Ring buffer - the daemon stores the most recent N entries in memory; older entries are written to disk
- Queryable - filter by agent ID, time range, or action type
Entry Structure
Each audit entry contains:
{
"id": "<uuid>",
"timestamp": "2026-02-22T12:34:56.789Z",
"agent_id": "<uuid>",
"agent_name": "my-agent",
"action": "tool_invoked",
"detail": "echo({\"message\": \"hello\"})",
"outcome": "success",
"prev_hash": "<sha256-hex>",
"hash": "<sha256-hex>"
}
The hash field is SHA-256(prev_hash + timestamp + agent_id + action + detail + outcome). Verifying the chain means checking that each entry's hash matches its declared inputs and that each prev_hash matches the previous entry's hash.
Querying the Audit Log
# Last 20 entries (all agents)
ash audit
# Filter by agent
ash audit --agent <uuid>
# Show more entries
ash audit --limit 100
What Gets Audited
Every IPC request handled by agentd that results in an action produces an audit entry. This includes:
| Action | Audit Entry |
|---|---|
| Agent spawned | agent_spawned |
| Lifecycle transition | state_transition |
| Tool invoked (success) | tool_invoked |
| Tool denied (capability) | access_denied |
| Tool queued for approval | approval_requested |
| Tool approved/denied | approval_resolved |
| Memory read/write | memory_access |
| Observation appended | observation_appended |
| Workspace snapshot | workspace_snapshot |
| Secret used | secret_used |
| Anomaly detected | anomaly_detected |
| Capability grant issued | capability_granted |
| Capability grant revoked | capability_revoked |
| Plan declared | plan_declared |
| Plan revised | plan_revised |
| Agent terminated | agent_terminated |
Anomaly Detection
The audit trail feeds the behavioral anomaly detector (agentd/src/anomaly.rs). The detector runs four rules:
- Volume spike: unusually high number of tool invocations in a short window
- Scope creep: repeated access denials suggesting capability probing
- Repeated kernel denials: seccomp/AppArmor denials indicating containment pressure
- Secret probe / canary leak: attempts to access undeclared secrets, or canary token appearing in a tool result
When an anomaly is detected, an anomaly_detected audit entry is written and an escalation message is sent up the agent hierarchy.
Tamper Detection
To verify the audit chain:
# (planned: ash audit verify)
# For now, query entries and verify hashes manually
ash audit --limit 1000
If any entry's hash does not match SHA-256(prev_hash + fields), the chain has been tampered with.