Skip to main content

agentlighthouse-verify

Standalone verifier for AgentLighthouse evidence.

AgentLighthouse is a security mediator for AI agents. It writes a signed receipt for every decision it takes. This package checks those receipts, and it does so without the mediator: it does not import the runtime, and its only dependency is cryptography.

That separation is the point. An auditor, a customer or a regulator can verify the evidence with a small tool they can read end to end, and does not have to trust the operator's binary.

Contents

Install

pip install agentlighthouse-verify

This installs one command, al-verify.

Verify a ledger

You need two files from the operator: the ledger and the mediator's public key.

al-verify ledger.jsonl --pubkey mediator_ed25519.pub
chain of 11 receipt(s) verified from genesis
OK

The exit code is 0 when everything verifies and non-zero when anything does not, so the command can gate a pipeline.

What can be verified

Input What it is
A receipt (.json) One mediated decision
A ledger (.jsonl, or a JSON array) The full chain of receipts, from the first one
A posture attestation A signed per-organization summary of posture and evidence over a period
A rule bundle A signed set of detection rules; the mediator refuses to load an unsigned or altered one

What verification checks

Verification is fail-closed. Any one failure fails the whole run.

  1. The record hash. The receipt is canonicalized with RFC 8785 (JCS) and hashed with SHA-256. The result must equal the record_hash the receipt carries, so a changed field is detected.
  2. The signature. sig must be a valid Ed25519 signature over that hash by the mediator key you supplied.
  3. The chain. Each receipt's prev_hash must equal the previous receipt's record_hash, and sequence numbers must be contiguous from genesis. A removed, reordered or inserted receipt is detected.

The canonicalization and the hash chain are implemented in this package from the specification, with no third-party code, so the trust surface stays small enough to audit.

Command line

al-verify [--pubkey PUBKEY] [--quiet] [--version] receipt
Argument Meaning
receipt Path to a receipt .json, a .jsonl ledger, an attestation or a rule bundle
--pubkey The mediator's public key: a file, or the key inline as hex. Default: keys/mediator_ed25519.pub
--quiet Print only the final verdict
--version Print the version

The receipt format

A receipt records exactly one decision:

{
  "v": 1,
  "seq": 42,
  "ts": "2026-07-10T12:00:00.000Z",
  "actor": "spiffe://acme/agent/claude-code",
  "action": "mcp_tool_call",
  "target": "tool:send_email",
  "verdict": "block",
  "findings": [
    { "scanner": "tool_policy", "rule_id": "policy.default_deny", "severity": "high", "owasp": "ASI03", "mitre": "T1078" }
  ],
  "block_reason": "TOOL_NOT_ALLOWED",
  "policy_hash": "sha256:...",
  "redaction": { "aws-access-key": 1 },
  "prev_hash": "sha256:...",
  "record_hash": "sha256:...",
  "sig": "ed25519:..."
}
  • actor is the identity the decision is bound to.
  • action comes from a closed vocabulary. The vocabulary grows additively, so this verifier still checks a receipt that carries a newer action.
  • redaction holds counts per class. A receipt never carries the secret or the personal data that was redacted.

The format is specified, with a JSON Schema, in receipt-v1. The specification is MIT-licensed, so third parties can produce and verify receipts without this code.

Trust model

Verification proves that the receipts were signed by the holder of the key you supplied and that the chain has not been altered since. It follows that:

  • The public key must reach you through a channel you trust. A ledger and a key handed over together by the same party prove only that they match.
  • A verified chain is complete from genesis to its last receipt. It does not show that the mediator saw every action an agent took. That depends on how the mediator is deployed: see the architecture document.
  • A posture attestation names the chain head it was cut from, so it can be tied back to a ledger you have verified.
Package What it is
agentlighthouse-core The mediator that produces the receipts. It depends on this package.
agentlighthouse-governance Organizations, role-based access, budgets and signed posture attestation.

License

MIT. See the LICENSE file shipped with this package.

Metadata

Release files for agentlighthouse-verify 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentlighthouse-verify 0.4.0
File Size Uploaded Provenance Actions
agentlighthouse_verify-0.4.0.tar.gz 10.1 kB Without provenance Details for agentlighthouse_verify-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentlighthouse-verify 0.4.0
File Interpreter ABI Platform Actions
agentlighthouse_verify-0.4.0-py3-none-any.whl Python 3 none any Details for agentlighthouse_verify-0.4.0-py3-none-any.whl

Total release size: 21.8 kB

Release files / agentlighthouse_verify-0.4.0.tar.gz

Download URL agentlighthouse_verify-0.4.0.tar.gz
Size 10.1 kB
Tags Source
SHA-256 checksum
How to use checksums
3b49b600ff219bfb7dce24eac4ba3fa5ad8226229a3a342124ac1ee0e0e6ac5b
BLAKE2b-256 checksum
How to use checksums
fa8f2c602bdf9cc9191630962d93e6e59a8662999958705177f1adaf2a5c62c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / agentlighthouse_verify-0.4.0-py3-none-any.whl

Download URL agentlighthouse_verify-0.4.0-py3-none-any.whl
Size 11.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
160feca89e5c0ae4be3309c7a3feff59134803318917ed024e845281068c932a
BLAKE2b-256 checksum
How to use checksums
bc51686e6b46659c3a5554162726cd7b8640ac3dd6a54a72ce39fa2c09c8c089
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for agentlighthouse-verify 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.4.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page