Skip to the content

Investigate a task across the fleet

Read 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.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Open a task's timeline on the Central Lite host, read what is missing and why, export Central Lite's evidence bundle with the legal hold it places, verify it offline against the org root, compare it with the machine's own bundle, and release the hold when the case is closed.

1. Open the task's timeline

On the Central Lite host, garm-central incident timeline prints task …: N item(s) from M node(s), then one line per item, oldest first: its time, its kind, the node (or central), its sequence number and what it was. Items are the events the machines uploaded for the task, Central Lite's own admin actions naming it (its kill, the kill orders whose node reports list it, their lifts and its legal holds) and each machine's last reported chain head, flagged when its key is not one Central Lite pinned. --json prints the same as JSON. It shows metadata only: prompt bodies stay on the machines. At most 100,000 events are read.

In the console, open Incidents, enter the task id and choose “Show the timeline”: a table of When, Kind (node event, Central action or chain head), Node, Seq and What, oldest first, then the gaps. The task id comes from the machine (agentgarm status --json).

garm-central incident timeline --task TASK_ID
The console's Incidents: a task's timeline, oldest first, its gaps, and the evidence export

See also

Trace what one agent task did

Find an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last.

2. Read its gaps

What Central Lite knows it lacks is shown, never hidden: each gap is a line gap: node … class … records … to …: and its reason, such as shed by the node (a machine dropped low-priority records it could not upload) or lost in a restore (Central Lite was restored from a backup older than those records). Records a machine has not uploaded yet, or that retention already deleted, are not there either.

A gap is not proof of tampering, and no gap is not proof of completeness: Central Lite holds what the machines sent it. For the machine's own record of the task, export its bundle there.

See also

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.

3. Export Central Lite's bundle, with its hold

garm-central incident export writes the task's bundle to a new 0600 file: the stored events and their OCSF 1.9.0 projection, the timeline, each machine's chain head with the key Central Lite pinned, the gaps, and Central Lite's own chain run over its admin actions naming the task (other records as stubs) to a head signed now. The manifest is signed by the org root's evidence key; an org whose root predates that key gets it with the next garm-central root lite, and the export is refused until then.

It prints evidence bundle of task … written to … with the SHA-256 and the counts, then legal hold … placed on task … (or that one already stands), and the command that verifies it. The hold is placed and the export chained only once the file is written. --no-hold places none, and is refused while a kill order covering the task is in force.

In the console, under the timeline, “Export evidence with a passkey” does the same after a fresh passkey assertion over the task and your hold choice (“Place no legal hold” is offered), saves it as evidence-<task>.tar, and confirms its SHA-256 and the hold. The export is chained with your name. A bundle too large for the console is refused before anything is recorded: export it on the host.

garm-central incident export --task TASK_ID --out central-evidence.tar

4. Verify it offline against the org root

A Central Lite bundle is checked against the org root, not against anything in the bundle: agentgarm audit verify-bundle with --root, the org root metadata, and --root-fingerprint, the root key's fingerprint. On the Central Lite host, garm-central root export --out ROOT.json writes the installed metadata to a new file and prints both as --root ROOT.json --root-fingerprint HEX. Check the fingerprint against the one your enrolment tokens carry or your ceremony record, never against the file alone, and not against whoever hands you the bundle.

The root is judged as of the bundle's own time; its evidence key checks the manifest and its audit_head key Central Lite's chain, and each machine's chain head is checked under the key Central Lite pinned. A valid bundle proves Central Lite held exactly these records and signed them, not that a Central Lite someone broke into told the truth. Under Lite's 1-of-1 software root, whoever controls its host holds the evidence key too.

garm-central root export --out ROOT.json
agentgarm audit verify-bundle central-evidence.tar --root ROOT.json --root-fingerprint HEX

5. Compare it with the machine's own bundle

When you can reach the machine, export the task there too. Its bundle is signed by the machine's own node key and carries the chain run itself, with the task's own records in clear, so it does not depend on Central Lite. The two should agree: the events in Central Lite's bundle are the ones the machine uploaded, and the chain head it reported is the machine's. Where they differ, the machine's bundle, checked against a key read on the machine, is the stronger evidence.

See also

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.

6. Release the hold when the case closes

The export's task: hold keeps the task's records past retention, in Central Lite and on every enrolled machine, until M distinct admins release it, as the retention guide shows: garm-central legal-hold list shows the holds that stand, and garm-central legal-hold release opens a release request each admin approves with a passkey.

garm-central legal-hold list
garm-central legal-hold release HOLD_ID --reason "case closed"

Checked by the walk: this command ran as written on a Central Lite host.

See also

Set retention, legal holds and data-subject requests

Set 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.