AI agents are being wired into payments, trading, infrastructure, and internal tools through MCP-style tool calls. In most deployments, the only evidence that an agent stayed inside its authorization boundary is a log written by the same system being evaluated. Logs can be edited, and compliant-sounding text can coexist with violating actions. warrant is a reference toolkit for verifiable AI agent authorization: signed warrants, index-bound Merkle constraint commitments, pre-dispatch tool-call enforcement, and tamper-evident offline audit verification.
Caution
Not audited. Not production software. Do not use as the only control for agents with access to real funds, production infrastructure, or regulated workflows.
flowchart LR
I["Issuer"] -->|"Ed25519 over canonical JSON"| W["Signed warrant"]
W -->|"mandate + constraints + validity"| E["WarrantInterceptor"]
A["Agent tool call"] --> E
E -->|"allow"| T["Tool dispatcher"]
E -->|"block"| V["Violation record"]
E -->|"append decision + Merkle proof"| L["Hash-chained audit JSONL"]
L -->|"offline replay"| O["Verifier"]
S["Auction simulator"] -->|"scripted actions"| M["Collusion metrics"]
Dashed privacy claims are intentionally absent: v0.1 does not implement zero-knowledge proofs, kernel enforcement, on-chain anchoring, or model-internal deception probes.
This repository demonstrates signed authorization envelopes, deterministic warrant verification, index-bound Merkle commitments over constraint leaves, MCP-style Python tool interception, allow/block decision records, offline audit-chain verification, a Rust Merkle implementation, a Python parity implementation, and a deterministic multi-agent auction demo that flags action-level floor clustering.
It does not claim zero-knowledge constraint satisfaction. Merkle membership proofs reveal the proven constraint leaf. It does not claim kernel-level enforcement; the Python interceptor is in-process and can be bypassed by a fully compromised runtime. It does not claim live LLM collusion detection; the auction policies are scripted fixtures used to demonstrate metrics. It does not anchor audit heads on-chain, move funds, resolve external DIDs by default, or certify an agent deployment as compliant.
| Component | Status | Evidence / boundary |
|---|---|---|
| Warrant schema and signing | Implemented | Ed25519 signatures over canonical JSON; warrant issue and warrant verify exercise the path |
| Validity checks | Implemented | not_before / not_after validation in the verifier and interceptor |
| Constraint commitment | Implemented | SHA-256, domain-separated, index-bound Merkle tree in Python and Rust |
| Proof verification | Implemented | Python tests verify all committed constraints and tamper rejection |
| Tool-call interceptor | Implemented | Python wrapper checks warrant, allow-list, deny-list, and numeric rules before dispatch |
| Audit log | Implemented | Hash-chained JSONL with offline verifier and middle-record tamper localization test |
| Auction collusion demo | Implemented as scripted simulation | Reports coalition advantage and floor clustering for deterministic policies, not live LLM behavior |
| Falco rules | Documented add-on | YAML shape is linted; kernel enforcement is not run in CI |
| Moltrust resolver | Optional adapter scaffold | Lazy import behind optional extra; local did:key resolver is the tested default |
| zk proofs / on-chain anchoring / PyO3 bindings | Planned | Tracked in ROADMAP.md and seeded GitHub issues |
Clone the repository, install Python 3.11 or newer, and run this block from the repository root:
python -m pip install -e ".[dev]"
warrant issue --output warrant.json
warrant verify warrant.json
warrant demo enforce --audit-out demo_out.jsonl
warrant audit verify demo_out.jsonl
warrant demo collusion --seed 7Expected output shape:
issued warrant.json
valid warrant: signature, validity window, and commitment root verified
allow quote price=92 notional=150
block execute_command: tool execute_command is not allowed
block quote: price violates min_price_floor
ok: verified 3 records
ok: verified 3 records
metric value
----------------------------- --------
competitive_baseline_margin 96.0
cartel_realized_margin 123.0
coalition_advantage 27.0
floor_clustering_share 1.0
The initial release test suite reports 90.17% Python line coverage, reproduced by:
pytest --cov=agent_warrant --cov-fail-under=90Rust verification is separate:
cargo test
cargo clippy -- -D warnings
cargo fmt --checkA warrant is a signed JSON document with four operational surfaces:
| Block | Purpose |
|---|---|
mandate |
Declares the goal and the tools the agent may call |
constraints |
Declares rule leaves such as max_order_notional, min_price_floor, and tools_denied |
validity |
Declares the time window and session key metadata |
commitment_root |
Commits to the constraint set with index-bound Merkle leaves |
The signature covers the document without the signature block. Constraint leaves are hashed as canonical JSON plus a 16-byte salt plus the big-endian leaf index, with domain separation for leaves, internal nodes, and odd-node padding.
warrant keygen
warrant issue --output warrant.json
warrant verify warrant.json
warrant prove warrant.json --constraint-id 1
warrant check-proof --root <hex> --proof proof.json
warrant demo enforce --audit-out demo_out.jsonl
warrant demo collusion --seed 7
warrant audit verify demo_out.jsonl
warrant export --format json
warrant lint-falco integrations/falco/warrant_rules.yaml
warrant makes authorization evidence verifiable; it does not make an agent process impossible to bypass. The interceptor runs in process. If an attacker controls the runtime, they can skip the interceptor and call tools directly. The audit guarantee is that missing, reordered, or edited records are detectable by offline replay, not that bypass is impossible. See docs/design.md and LIMITATIONS.md.
Falco rules in integrations/falco/warrant_rules.yaml are provided as a documented starting point for runtime policy. CI validates their YAML shape only. A real deployment needs container isolation, kernel telemetry, key custody, log retention, and independent operational controls outside this repository.
| Approach | Verification boundary | Trade-off |
|---|---|---|
| Plain agent logs | Human-readable trace | Editable by the same system being reviewed |
| Signed warrant plus audit chain | Offline verifier can check signature, root, proof, and record chain | In-process enforcement can still be bypassed by a compromised runtime |
| Kernel policy monitor | Observes syscall boundary below the process | Requires platform-specific deployment and operational tuning |
| zk constraint proof | Can hide more witness material | Not implemented in v0.1; circuit cost and scope need design work |
| On-chain audit-head anchoring | External timestamp and publication point | Not implemented in v0.1; local JSONL is the current audit surface |
src/agent_warrant: Python package for schema, signing, Merkle proofs, interception, audit logs, commit-reveal, resolver interfaces, and CLI.src/agent_warrant/auction: deterministic scripted auction simulator and metrics.crates/warrant-core: Rust Merkle commitment and proof implementation.fixtures: warrant, vector, and auction fixture material.integrations/falco: documented Falco rule scaffold.integrations/mcp: minimal example of wrapping a tool dispatcher with the interceptor.tests: pytest coverage for signing, Merkle proofs, interception, audit tamper detection, demos, and Falco lint.docs: design notes, demo boundary, and references.
python -m pip install -e ".[dev]"
pytest --cov=agent_warrant --cov-fail-under=90
ruff check .
black --check .
mypy src
cargo test
cargo clippy -- -D warnings
cargo fmt --checkCI runs the Python matrix on Ubuntu and Windows with Python 3.11 and 3.12, plus Rust stable on Ubuntu and Windows. The v0.1.0 tag and main branch passed the full matrix on commit bb9e7bf.
The release plan is in ROADMAP.md. The current backlog includes PyO3 bindings, zk membership proof research, MCP middleware packaging, DID resolver adapters, audit-head anchoring, and containerized Falco tests. Start with CONTRIBUTING.md, and read SECURITY.md before reporting a vulnerability.
Use CITATION.cff or GitHub's Cite this repository button. The citation describes a reference toolkit and does not imply audit assurance, production readiness, or deployment certification.
- Model Context Protocol documentation - tool-call context for MCP-style agent integrations.
- RFC 8785 JSON Canonicalization Scheme - canonical JSON signing reference.
- RFC 8032: Ed25519 - signature primitive reference.
- Falco documentation - runtime security rule context for the optional integration scaffold.
- W3C Decentralized Identifiers - DID terminology behind the local resolver interface.
Vishnu Govind - GitHub | Medium | LinkedIn
MIT licensed.