Guide 38 of 61 · Investigating and recovering
Export evidence for one task
Write 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.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
Find the task, export its evidence bundle with or without personal fields, verify it with the node's key, know what a valid bundle proves and what it doesn't, hold the machine's records past retention, and hand the bundle over so a third party can check it. No Central Lite is needed.
1. Find the task
An export names one task by its full id, a UUID. While it runs, agentgarm status --json lists it under tasks with its task_id; the plain output shows only the last twelve characters. For a task that has ended, agentgarm task list --ended lists your recent ended tasks, newest first, each with its whole id, its agent and when it started and ended; a run's page in the dashboard also has an address that ends in its task id. You can export your own tasks; root can export any user's. Under the non-monitoring profile only root can export, and the bundle says the profile was in force. Every export is recorded in the audit chain.
agentgarm status --jsonagentgarm task list --endedChecked by the walk: these commands ran as written on a no-root Linux install.
See also
Undo what an agent changedPreview what rolling back an agent's task would restore and keep, then apply the rollback from the checkpoint taken before the agent started.
2. Export it
agentgarm incident export asks agentgarmd to sign a fresh chain head and writes the task's bundle to a new file with mode 0600; it never writes over an existing one (“exists: choose a new file”). It prints the bundle's SHA-256, how many chain records it holds and how many are stubs, the agentgarm audit verify-bundle command with the --key to check it with, and the command that holds the machine's records. Run it from a terminal of your own: it is refused from inside a governed task, and refused if agentgarmd cannot sign the head. In the local dashboard, a run's page has an Export evidence button that saves the same bundle (without the stored records) and shows its SHA-256 and the verify command; a bundle over 64 MiB is the command's alone.
Other tasks' and users' records appear only as stubs, with no content. This task's own records are in clear, as stored: its principal and credential ids, the paths it touched and the commands it ran. Its events and decisions are also given as OCSF 1.9.0 with principals and credentials as keyed hashes that join nothing outside this bundle. --include-personal adds the stored events and decisions themselves and prints a warning: share such a bundle only as your policy on personal data allows. The export is built on macOS and Linux; on Windows it refuses until a later release.
agentgarm incident export --task <task> --out evidence.taragentgarm incident export --task <task> --out evidence-personal.tar --include-personal3. Verify it with the node's key
agentgarm audit verify-bundle checks the bundle offline: every file against the bundle's manifest, the manifest's signature, and each chain segment, with the stubs' places proven but not their content. Trust comes only from the --key you give, never from the key inside the bundle: use the one the export printed, or read it on the machine from agentgarm status's node key line.
A good bundle prints edge bundle for task …: valid, attributed, then each check as - checked: with what it proves:, and exits 0. Without a key it says self-consistent, NOT attributed and exits 3, since anyone can build a bundle that agrees with itself. A changed, reordered or truncated bundle, or the wrong key, prints INVALID: with the reason and exits 1.
agentgarm audit verify-bundle evidence.tar --key <key_id>=ed25519:<hex>agentgarm audit verify-bundle evidence.tar --key "$(cat ~/.local/state/agentgarm/node.pub)"See also
Export and verify the audit logExport 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.
4. Read what it proves and what it doesn't
A valid, attributed bundle proves that whoever holds that node key wrote these records, in this order, unchanged since, up to the head signed for the export; records written after it are not in the bundle. It does not prove the machine was not compromised before then, and a stub proves only that a record stood in that place. It is only as good as the key you checked it with, so read the key on the machine itself.
On a root install the store and the node key are out of the user's reach. On a no-root install there is no privilege boundary: on Linux the key is a file of yours, and any unsandboxed process of yours could have changed the records before they were signed, so treat its bundle as C.
5. Keep the records
An export on the machine places no hold, so retention will still delete the task's records in time. To keep them, place a legal hold on the task, as the export's last line names: retention, shedding, checkpoint clean-up and rollback then leave what it covers alone. Each hold is recorded in the audit chain; root releases a hold placed on the machine.
sudo agentgarmd legal-hold place --scope task:<task> --reason "incident review"agentgarmd legal-hold place --scope task:<task> --reason "incident review" --userSee 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.
6. Hand it over
Give the reviewer the bundle, its SHA-256 and the node key, the key by another channel than the bundle. The bundle is a plain tar of manifest.json, manifest.sig, the chain run in ocsf.jsonl and the payload files (task.json, events.ocsf.jsonl, decisions.ocsf.jsonl, and with --include-personal events.jsonl and decisions.jsonl), so tar -tf lists it. They check it with the same agentgarm audit verify-bundle command on their own machine, with no network and no store.
tar -tf evidence.tar
shasum -a 256 evidence.tarSee also
Investigate a task across the fleetRead a task's timeline in Central Lite with its gaps, export a bundle the org root's evidence key signs, verify it offline and hold its records.