agent-audit-gateway:基于 Python 的 AI Agent 工具调用审计网关项目

An HTTP audit gateway for AI agent tool calls: transport + bearer auth + rate limit in front of a fail-closed audit engine (MIT).

Branch1Tags2

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

Introduction

An HTTP audit gateway for AI agent tool calls: transport + bearer auth + rate limit in front of a fail-closed audit engine (MIT).

Customize your domain