--- title: "Capability: Audit chain" canonical_url: "https://tokenobserve.com/platform/audit-chain" published: 2026-09-02 last_updated: 2026-10-21 --- # Capability: Audit chain Every administrative act hash-chained, and anchored with a signature your auditor can check alone. ## What it is Audit chain is Token Observe's tamper-evidence layer: every governance-plane change is appended to a hash chain, and an edit breaks it. The digest covers the previous entry's hash plus the canonical JSON of its own content, so a deletion is located rather than merely suspected. Configure an audit MAC key and those digests become HMAC-SHA256 under a key held outside the database; leave it unset and the chain is plain SHA-256, which an operator with write access can rewrite and recompute. Every verification result names which of the two you hold. Ed25519 anchoring sits above both, off until you set a signing key: any copy of an anchor you kept off-box beats a rewrite made after you took it. ## Facts - Entry digest: SHA-256, or HMAC-SHA256 under an audit MAC key - Anchor signature: Ed25519 over a canonical statement of the head - Anchor cadence: Daily once a signing key is set, plus sign-now - Offline verifier: One Node script: no install, no database, no network ## The limit The default: Unkeyed, a rewrite that re-hashes everything verifies clean ## Why it exists: The threat model has to include your own operator. An audit log earns its place by answering who widened this policy, when, and whether anybody edited the record afterwards. So the threat model has to include the administrator who can relax a policy, run an agent against it, then delete the row that says so. A bare chain is evidence only against an attacker who cannot recompute it, and a test in the repository asserts it: the forged chain passes on a default install and fails once a key is set. Everything above it moves the target rather than removing it. ## How it works - Append, then seal: Both hash fields are excluded from the digest input, so a recomputation covers exactly what the original write covered. With an audit MAC key set, every boot also writes a checkpoint MAC over the head it reached. Entries written before the key cannot be re-MAC'd, so that checkpoint vouches for them. - Verify: A walk checks every link, recomputes every content digest and finds sequence gaps, then reports where the chain broke and whether it was keyed. - Anchor: With a signing key set, Token Observe signs a canonical statement of the head daily and on demand, and refuses to sign when the chain does not verify. - Publish, then check: Each anchor goes to a file sink, an HTTP sink or both, from a cursor that advances only once that sink acknowledges it. An auditor verifies it with a public key that arrived out of band, using a script needing no install and no network. ## What it does not do - No Merkle tree and no inclusion proofs. An anchor covers a head, so a verifiable subset cannot be handed over without the rest of the log. - No trusted timestamp. An anchor's creation time is inside the signed bytes but asserted by the signer. Only a timestamp authority proves when. - No defence against host compromise. Whoever reads the audit MAC key or the anchor key out of the host can produce a history that verifies. - Compliance exports are digest-sealed, not signed. The digest detects an edit after issue and attributes nothing; the signature is on the anchors. - The offline verifier checks anchors, not today's chain: once it has grown past its newest anchor, the live-chain check is reported as not performed. - No certifications: no SOC 2 report, no ISO 27001 certificate, no independent penetration test. This is a control that evidences clauses. - Detected corruption latches the install. A content mismatch or a sequence gap fails readiness and later governed requests with a 503 until restart, because nothing is appended onto a chain proved unsafe. - No after-the-fact redaction of an audit entry. Editing one breaks verification from that sequence onward, so it is the wrong place for anything you may later have to erase. A trace purge leaves verification passing: traces sit in another table. ## Read next - https://tokenobserve.com/platform/flight-recorder - https://tokenobserve.com/platform/human-approvals - https://tokenobserve.com/platform/policy-engine ## Questions and answers Q: Is the audit log tamper-proof? A: No, and Token Observe will not use the word. Unkeyed, which is the default, it is tamper-evident: any edit that does not also recompute every downstream hash breaks verification at a named sequence number. An operator with write access can recompute it, and the repository's own forgery test asserts the forged chain passes. Configure an audit MAC key and a rewrite needs the key too; keep an anchor off the box and any later rewrite is contradicted by it. Q: What does an auditor need in order to verify an anchor? A: Two things, and the second must arrive out of band: the anchor export, and the current Ed25519 public key plus every retired one, from a key ceremony rather than from the anchor file. A pass says those keys signed every anchor, the anchors are contiguous, and attested heads only move forward. It cannot vouch for the history beneath the first anchor. The long-form detail on this capability (the anchored sections, the worked policies and the error envelopes) is on the page itself at https://tokenobserve.com/platform/audit-chain.