Agent Action Evidence Ledger

An append-only, hash-linked evidence ledger for autonomous agent actions, with a verifier that needs nothing but the exported file.

MIT licensed · zero runtime dependencies · MCP stdio server · TypeScript

The security problem

When an autonomous agent acts on production systems, the record of what it did usually lives in the same place as the agent: its own logs, its own database, its own operator's storage. That record is exactly what an attacker — or an embarrassed operator — edits first. A reviewer asking what did this agent actually do, in what order, and was the record changed afterwards? has no way to answer without trusting the party under review.

Related MCP server: ledger

What this product does

It records every agent proposal, execution, redaction and annotation as an entry in an append-only chain. Each entry's SHA-256 digest binds to its predecessor over a canonical form, so mutating, reordering, inserting or truncating any entry is detectable. An export is self-contained: verify_ledger is a pure function of the export document's own bytes and performs no other I/O, so a third party can check the history without trusting the agent runtime, the operator's storage, or this package's live process.

It never prevents, approves or executes an action. It observes and attests.

Major capabilities

• Append-only history. No operation updates or deletes an entry. Correction is a new redaction entry naming the superseded sequence number.

• Chain integrity over a canonical form. SHA-256 only; no short or non-cryptographic hash anywhere.

• Redaction totality. Attribute values under non-allowlisted keys are replaced with a { "$digest": ... } wrapper at admission — never canonicalized into the chain, returned, or logged in clear.

• Independent verification. The verifier is pure and offline, and needs no other package.

• Never fails open. A rejected durable append leaves the chain head unchanged and consumes no sequence number.

• Anchor point for external notarisation. headDigest is reported separately from chain validity, so anchoring status is never confused with cryptographic integrity.

Install and run

Prerequisites: Bun 1.1+ (or Node 22+ with a TypeScript loader). No install step is required beyond the clone, because there are no runtime dependencies.

git clone https://github.com/SweetKenneth/shpbl-action-ledger.git
cd shpbl-action-ledger
bun install                    # dev types only
bun test                       # conformance suite
bun run scripts/symbol-scan.ts # build-failing forbidden-symbol scan
bun src/mcp-server.ts          # MCP server: newline-delimited JSON-RPC 2.0 on stdin/stdout

MCP configuration

{
  "mcpServers": {
    "action-ledger": {
      "command": "bun",
      "args": ["/absolute/path/to/shpbl-action-ledger/src/mcp-server.ts"]
    }
  }
}

Tool surface

Worked example

examples/worked-example.ts records a proposal, its execution, a redaction of a mistaken entry, exports the range, tampers with one byte, and shows the verifier rejecting the tampered export while accepting the original.

bun examples/worked-example.ts

Verification results

60 conformance tests, 158 assertions: specification properties P1–P12, every §7 failure mode, canonicalization test vectors, and the MCP JSON-RPC surface. The forbidden-symbol scan covers 8 source files and fails the build on any network, filesystem-write or process-execution symbol. Strict typecheck is clean. Runtime dependencies: zero.

Security boundaries

• No network access, no ambient filesystem writes, no process execution.

• Durable persistence happens only through a sink the caller supplies.

• Errors are structured and value-free: a fixed code, a fixed phrase from this package's own vocabulary, and a JSON pointer — never a caller-supplied value.

• This is an evidence tool for the operator's own agent systems. It does not gate, approve or prevent any action.

See SECURITY.md for the full threat model.

Known limitations

• An attacker with write access to the durable sink and the ability to recompute the chain from genesis can forge a self-consistent history. The mitigation is periodic external anchoring of headDigest to a store the attacker cannot rewrite. This package defines the anchor point and format; it does not ship an anchoring service.

• The ledger cannot attest that a recorded action was actually performed — only that the runtime asserted it, at that point in the chain, and has not edited the assertion since.

Provenance

Discovered with SHPBL. This product originated through cross-capability composition in the SHPBL capability library. Its public implementation was independently built from a published behavioural specification. SHPBL's proprietary capability library, discovery system, harvested implementation bodies, and private provenance machinery are not included.

• Public behavioural specification: https://github.com/SweetKenneth/shpbl-spec-action-ledger (a copy ships here as SPEC-agent-action-evidence-ledger.md)

• SHPBL: https://shpbl.com

• Details: PROVENANCE.md

Tenable status

Submitted to the Tenable CyberAgents Exchange for review on September 11, 2026. Submission does not imply review, approval, certification, validation, endorsement, or acceptance by Tenable.

SHPBL Agent Evidence series

Independently installable, interoperable at the evidence-record boundary:

• shpbl-action-ledger — agent action evidence ledger

• shpbl-handoff-attestor — cross-agent handoff attestation

• shpbl-drift-sentinel — agent behaviour drift detection

• shpbl-retrieval-auditor — retrieval context provenance

• shpbl-canary-chain — synthetic canary evidence chain

Licence

MIT — Copyright (c) 2026 Kenneth E. Sweet Jr. See LICENSE.