Skip to main content

agent-audit-gateway

An HTTP audit gateway for AI agent tool calls — transport + bearer auth + rate limit in front of a fail-closed audit engine. Default OFF. Loopback by default. A gateway fault can never ALLOW.

pip install agent-audit-gateway          # zero deps, Python 3.9+

License Python Tests Deps Status

GitCode GitHub

中文版 · Research prototype / AI-assisted development.


Deploy one endpoint, POST /audit_call, and every agent tool invocation gets a verdict (allow / deny / human) with a verifiable trail — without rewriting your agent framework. The gateway never re-implements adjudication: it is transport, bearer auth and rate limiting only.

Why a gateway?

Your agent already has capabilities; what it lacks is an enforcement point between the caller and the action. agent-audit-gateway gives you:

  • transport layer only — adjudication lives in the vendored engine
  • hash-only credentials — caller registry stores sha256, never plaintext
  • timeout = deny — an adjudication over budget returns ERR_TIMEOUT without consulting the engine (fail-closed)
  • default OFF — no listening socket unless you opt in; loopback by default

Product family

Part of the Verifiable-agent family — one fail-closed design language:

Repo Role
agent-call-audit audit engine for agent tool calls
agent-memory-ledger verifiable memory layer
agent-audit-gateway the engine as an HTTP gateway (this repo)
agent-route-grid audited multi-agent routing

The engine is vendored (audit_guard/, from agent-call-audit v0.1.0, same MIT maintainers) so this package is self-contained with zero dependencies.

Install

pip install agent-audit-gateway   # once published
# dev / from source:
pip install -e .

Zero runtime dependencies. Python 3.9+.

Quick start (library)

from aag import AuditPipeline, CallerRegistry

pipeline = AuditPipeline(
    registry=CallerRegistry.from_file("rules/callers.registry.example.json"),
    timeout_ms=2000,
)
print(pipeline.adjudicate({
    "caller_id": "agent-alpha",
    "credential": "gateway-token-alpha-2026",
    "target_capability": "data.lookup",
    "action_type": "read",
    "data_class": "public",
    "request_hash": "…sha256 of optional payload…",
    "nonce": "n-1",
    "timestamp": 1700000000.0,
}))

Run the HTTP gateway (default OFF)

set AUDIT_GATEWAY_ENABLE=1
set AUDIT_GATEWAY_PORT=12787
python -m aag.server

Then call it: python examples/client.py.

Run as a Local MCP server (stdio)

Expose the adjudicator as an MCP tool so any MCP client can audit tool calls. This is the Local form: the server runs on your machine over stdio — no remote endpoint, no hosted service, credentials stay local.

python -m aag.mcp_server          # stdio MCP server (default transport)

It exposes one tool, audit_call, that wraps AuditPipeline.adjudicate:

param meaning
caller_id, credential caller identity + bearer credential (checked against the sha256 registry)
target_capability, action_type, data_class what is being requested
request_hash, nonce, timestamp request integrity + replay defence
idempotency_key, amount, payload, currency optional

Fail-closed: any missing/malformed field returns a deny decision, never an allow. Point your MCP client at the stdio command above to use it.

Proof of life

Real output from python examples/demo.py (seven scenarios):

1) allow                    -> decision=allow  FAIL_CLOSED=False
2) auth deny (bad token)    -> ERR_AUTH_FAILED
3) red-line deny            -> ERR_RED_LINE (DEMO-RL-001)
4) replay deny (same nonce) -> ERR_REPLAY
5) hash-mismatch deny       -> ERR_HASH_MISMATCH
6) least-privilege deny     -> ERR_CAPABILITY_NOT_GRANTED
7) timeout (50ms budget)    -> ERR_TIMEOUT  FAIL_CLOSED=True

Fail-closed invariants

Invariant Guarantee
Default OFF no listening socket unless AUDIT_GATEWAY_ENABLE=1; loopback by default
Transport only adjudication stays in the vendored engine; gateway never allows
Auth fail-closed Bearer token vs sha256 registry; missing/unknown/disabled -> deny
Timeout deny adjudication over timeout_ms -> ERR_TIMEOUT without the engine
Error -> deny any unexpected exception maps to ERR_INTERNAL deny
Rate limited per-IP fixed window; transport-level only
No secrets on disk registry stores sha256 hashes only

HTTP API

POST /audit_call
Authorization: Bearer <token>
{ "request": { caller_id, credential, target_capability, action_type, data_class,
               request_hash, nonce, timestamp },
  "payload": {...} | null }
→ { caller_id, decision, reason_code, risk_level, matched_rules,
    trace_id, latency_ms, fail_closed }

Architecture

audit_guard/   vendored engine from agent-call-audit v0.1.0 (verbatim, MIT)
aag/
├── auth.py       CallerRegistry: sha256 hash registry, fail-closed
├── limiter.py    fixed-window rate limiter
├── pipeline.py   AuditPipeline: timeout-guarded AuditGuard adapter
├── handler.py    HTTP handler (POST /audit_call)
└── server.py     launcher (AUDIT_GATEWAY_ENABLE-gated)
rules/           example caller registry (hashes only)
examples/        demo.py (library) + client.py (HTTP)
tests/           34 tests (incl. loopback HTTP integration)

Roadmap ideas

  • Streamable HTTP / MCP binding over the same pipeline
  • OpenTelemetry-style audit event export
  • Caller registry rotation with dual confirmation

Contributing / Security / License

  • CONTRIBUTING.md — fail-closed first, sanitized commits, green tests.
  • SECURITY.md — report privately; reference implementation.
  • LICENSE — MIT, agent-audit-gateway maintainers. Engine vendored from agent-call-audit (MIT).

Metadata

Release files for agent-audit-gateway 0.1.2

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

Source distribution (sdist)

Source distribution for agent-audit-gateway 0.1.2
File Size Uploaded Provenance Actions
agent_audit_gateway-0.1.2.tar.gz 25.4 kB Without provenance Details for agent_audit_gateway-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-audit-gateway 0.1.2
File Interpreter ABI Platform Actions
agent_audit_gateway-0.1.2-py3-none-any.whl Python 3 none any Details for agent_audit_gateway-0.1.2-py3-none-any.whl

Total release size: 49.6 kB

Release files / agent_audit_gateway-0.1.2.tar.gz

Download URL agent_audit_gateway-0.1.2.tar.gz
Size 25.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8f504c34722ac10e085cb84b5e0f9b52b859827c0425eaf0a9a00afb0266ed7e
BLAKE2b-256 checksum
How to use checksums
4e12d45c82f5c88535a74edbf5a9b8252cde778579b6eebb32f090d3d76a560b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / agent_audit_gateway-0.1.2-py3-none-any.whl

Download URL agent_audit_gateway-0.1.2-py3-none-any.whl
Size 24.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e082583462f1ceb1150a0a4719f9bfa95945d7da75e7fd3cc0aa0434a8c92472
BLAKE2b-256 checksum
How to use checksums
3c960f45a67c337d443d53547e73970f1bf726b787d7147d9787c0b6285284a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for agent-audit-gateway 0.1.2

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