Guide 37 of 61 · Investigating and recovering
Export and verify the audit log
Export AgentGarm's hash-chained audit log, check it against the node key that signs its heads, and know what a passing or broken check tells you.
Export AgentGarm's hash-chained audit log, check it against the node key that signs its heads, know what a passing check proves and what it does not, and read what a broken chain tells you.
1. Export the chain
Every decision and every security and audit event is appended to a hash chain, each record linked to the one before it. agentgarmd audit export writes one chain, the active one unless --chain names another, as OCSF events (a JSON array, or one per line with --format jsonl) into a new file with mode 0600; it never writes over an existing file.
It reads the store directly, so on a root install it needs root, and a no-root install names its own store with --user. With --out it prints a header: the chain, its authority, the --key to check it with, the result of checking it there, and the agentgarm audit verify command to run. Without --out the export goes to stdout and the header to stderr.
agentgarmd audit export --user --out audit.jsonsudo agentgarmd audit export --out audit.jsonChecked by the walk: these commands ran as written on a no-root Linux install and a root install on Linux.
See also
Set retention, legal holds and data-subject requestsSet how long Central Lite keeps each class of record, put a legal hold on the records a case needs, and answer a person's access or erasure request.
2. Get the key to check it with
agentgarmd signs the chain's head with the node key: when it starts a new chain, once 256 records are unsigned, every minute while any are, and at shutdown while any are. agentgarm status shows the key on its node key line in the form --key takes, and agentgarmd writes the same to node.pub in its state directory at start. The audit chain line says whether the chain verified at start from its last signed head.
agentgarm statusChecked by the walk: this command ran as written on a no-root Linux install.
3. Verify the export
agentgarm audit verify recomputes every record's hash and checks each link, the sequence and every signed head against the --key you give. It prints valid: chain … with the number of records and the authority, then how far the signatures reach: signed through record N; M unsigned record(s) after it. Records after the last signed head are linked but not yet attested.
It exits 0 only when the chain is intact and covered by a head your key verifies. An intact chain with no verified head exits 3, since anyone who can edit an export can recompute every hash: without a --key it says head signatures NOT checked (no --key given), and with one that signs no head of the chain, no signed head covers this chain. --allow-unsigned turns that 3 into 0 for a deliberate hash-only check, and --json prints the result as JSON.
agentgarm audit verify audit.json --key "$(cat ~/.local/state/agentgarm/node.pub)"agentgarm audit verify audit.json --key <key_id>=ed25519:<hex>Checked by the walk: this command ran as written on a no-root Linux install.
4. Know what a passing check proves
A pass shows that the records up to the last signed head are the ones the holder of that key signed, in order and unchanged. It is only as good as the key you checked it with, so read the key on the machine that signed the chain, never from whoever hands you the export. On a no-root install there is no privilege boundary: on Linux the node key is a file of yours, and any unsandboxed process of yours can edit the store and the audit chain. A root install keeps the store and the key out of your processes' reach.
A chain export is the whole chain, every task's and every user's records. To hand over one task's records, export its evidence bundle instead preview: the run of the chain that holds the task, other tasks' records reduced to stubs with no content, and a head signed for the export.
See also
Export evidence for one taskWrite one task's signed evidence bundle on its machine, verify it with the node's key, hold its records, and hand it to someone else to check.
5. Read a broken chain
A chain that fails prints INVALID: and the first problem, and exits 1. A record edited in place reads record N: hash does not match its content; one edited with its hash recomputed breaks the next record's link (broken link to the previous record); a record removed from the middle leaves a gap in the sequence (record N: expected sequence number M). With --key, records removed under a signed head read a signed head covers record N, but the chain ends at M; a forged head or one signed by another key fails as a head.
agentgarmd checks the active chain itself at start, from its last signed head, and the whole chain in the background. A chain that fails is never extended: it starts a new one, records the failure in it as an alert and keeps enforcing. agentgarm status then shows chain … FAILED its check at start with the reason and the new chain's id; export the failed one with --chain to keep it as evidence. Deleting the newest signed heads together with their records leaves an export that still verifies, so agentgarmd also checks the chain at start against a high-water mark it keeps outside the database, and reports such a chain as rolled back. Whoever owns the store (root, or you on a no-root install) can defeat that mark too.
agentgarmd audit export --user --chain <chain id> --out failed-chain.json