---
title: Tamper-evident integrity
description: ClawMetry's hash chain over local events — what it proves, what it does not, how to verify it, and how to read could not check against check failed.
keywords: tamper evident audit log, agent event integrity, hash chain verification, agent compliance evidence
eyebrow: 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
```

| Flag | Effect |
|---|---|
| `--node-id` | Verify one node (default: all) |
| `--json` | Emit the result as JSON. Exit codes are unchanged. |

## Reading the result

| Status | Meaning |
|---|---|
| `ok` | The chain verifies end to end |
| A break at a specific event | Events were altered or removed after being written |
| `store_open_failed` | The store could not be opened — an access problem, not an integrity finding |
| `daemon_too_old` | The 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.

## The related surfaces

```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](/docs/config/security/) ·
[EU AI Act evidence](/docs/ops/plans/)

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