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+
中文版 · 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_TIMEOUTwithout 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.