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.

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

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.1
File Size Uploaded Provenance Actions
agent_audit_gateway-0.1.1.tar.gz 23.6 kB Without provenance Details for agent_audit_gateway-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 45.9 kB

Release files / agent_audit_gateway-0.1.1.tar.gz

Download URL agent_audit_gateway-0.1.1.tar.gz
Size 23.6 kB
Tags Source
SHA-256 checksum
How to use checksums
b8c49cc0b15fdad2d4cb1513d5ef5dee4bf4b0cabe46b0b1f848d8eaee9a7bf9
BLAKE2b-256 checksum
How to use checksums
5cc8e2ca403f8d3e92f6965b3fc529845c0f9c53efe373f7edf478f48fe79559
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.1-py3-none-any.whl

Download URL agent_audit_gateway-0.1.1-py3-none-any.whl
Size 22.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9e3bcdac2cd540e95844533b89e5fe73f536f1b62a07e47706f677031fc6b9bc
BLAKE2b-256 checksum
How to use checksums
8cef79dad112266f04d2db77f917ea08e42e502516a5f4ff3a2aadbfb1a91fbf
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.1

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