CClawMetryDocs

Data & storage

Tamper-evident integrity#

Events are written into a hash chain: each event's hash covers the previous one. Altering or removing an event breaks the chain from that point forward, and the break is detectable.

Verifying#

bash
clawmetry verify-integrity
clawmetry verify-integrity --json
clawmetry verify-integrity --node-id build-runner-07
FlagEffect
--node-idVerify one node (default: all)
--jsonEmit the result as JSON. Exit codes are unchanged.

Reading the result#

StatusMeaning
okThe chain verifies end to end
A break at a specific eventEvents were altered or removed after being written
store_open_failedThe store could not be opened — an access problem, not an integrity finding
daemon_too_oldThe daemon predates the chain; there is nothing to verify yet

The last two are synthetic statuses and they exist for a specific reason: "could not check" and "check failed" are very different answers to an auditor, and conflating them would be the worst possible behaviour for a tool whose entire job here is to be believed.

A tool that reported "integrity failed" because a file permission was wrong would train people to ignore it.

bash
clawmetry verify-integrity --json | jq '{status, first_break, checked, nodes}'

What it proves#

  • That the local event log has not been edited after the fact. If someone

removed the session where an agent did something, or changed a tool argument after the fact, the chain does not verify.

  • Where the break is. The first bad event, so you know what is trustworthy

and what is not.

What it does not prove#

Being precise about this matters more than the feature does:

  • It does not prove the agent did what the events say. It proves the record

has not changed since it was written. If a runtime wrote something inaccurate, the chain faithfully preserves the inaccuracy.

  • It does not prevent tampering. It makes tampering evident. Anyone with

write access to the file can delete the whole store; what they cannot do is quietly edit one event and have it verify.

  • It is not a signature from a third party. The chain is computed locally.

For an attestation that a third party can verify independently, you want the cloud snapshot path or an external SIEM export.

In CI or a scheduled check#

bash
#!/usr/bin/env bash
set -euo pipefail
if ! clawmetry verify-integrity --json > /tmp/integrity.json; then
  echo "ClawMetry integrity check failed on $(hostname)"
  jq '{status, first_break}' /tmp/integrity.json
  exit 1
fi

Exit codes are unchanged by --json, so you can capture the detail and still branch on the result.

Turning it on and off#

bash
export CLAWMETRY_INTEGRITY=1

The chain adds a hash per event. On a busy node that is a real if small cost, and it is worth having on wherever the log might ever need to be defended.

bash
curl -s localhost:8900/api/security/integrity | jq
curl -s localhost:8900/api/audit-log | jq
curl -s localhost:8900/api/authority-violations | jq

authority-violations is the complement to integrity: integrity tells you the record is intact, and authority violations tell you whether what the record describes was within the agent's declared permissions.

→ Hardening · EU AI Act evidence

Tier#

The hash chain and verification are available in the OSS package. audit_logs, siem_export and evidence_pack are Enterprise features built on top of it.

Edit this page View as Markdown Report an issue
Cookie preferences