agent-airlock 0.8.80

A deny-by-default type-checker and contract layer for AI agent tool calls — in-process, Pydantic-only

Strict validation, ghost-argument stripping, and self-healing retries — one decorator, any agent or MCP server. Zero core dependencies.¹

Test suite: 4,106 tests · Coverage: 87.27% · v0.8.80
_{Coverage runs 4,094 of 4,106; the 12 excluded are 8 benchmark tests (not correctness tests) and 4 docker-marked (need a daemon).}

Get Started in 30 Seconds · Why Airlock? · All Frameworks · Benchmark · Cross-tool comparison · Least-Privilege Benchmark · Docs

⬛ Reproducible block-rate — deterministic, in-process, deny-by-default

Benchmark (one command to reproduce)	agent-airlock	Compared with
Cross-tool block-rate · 210 tool calls · re-run 2026-08-17 · python -m benchmarks.blockrate	100% blocked · 0% false-positive · p50 ~2µs/decision	Meta LlamaFirewall · Invariant Guardrails — model-in-the-loop; scope-claimed, not re-run
Least-privilege / over-privileged tool selection · ToolPrivBench, 100 scenarios, OWASP-Agentic mapped (ASI01–04, 06) · re-run 2026-08-17 · python -m benchmarks.toolprivbench	100% over-priv blocked · 100% low-priv allowed · OPUR 100% → 0% enforced (−100pp)	—
Guard-suite CVE corpus · MCP Top-10 tagged	100% detection · 0% false-positive	—
Adaptive-attacker (AgentDojo) · airlock as a defense vs the tool_knowledge attack · all 4 suites · python -m benchmarks.agentdojo.run	86.0% of injection→task target tool-calls blocked · 524/609 (deterministic upper bound on ASR reduction)	Model-in-the-loop ASR 45% → 10% — gpt-4o-mini only, one model family (OpenAI), 60-pair subset, wide 95% Wilson CI [5%, 20%] · a single-family point estimate, not a harness-level claim · AgentDojo v1.2.1 (2026-07-31) · last verified 2026-08-08 · benign FP +10pp · RESULTS.md
Native MCP gateway head-to-head · 12 malformed tool-call payloads, identical to both layers · python -m benchmarks.vs_gateway	12/12 blocked · 0% false-positive · p50 ~0.08ms/decision	Docker MCP Gateway v2.0.1 — 0/12 blocked, against a build that is now superseded: Hub's moving v2 tag was rebuilt 2026-07-23, after the image this run measured, so a newer gateway exists that has not been tested here and may behave differently. · re-measured live 2026-08-17 (docker mcp v0.42.1 / engine 29.4.3): sent each payload as a real MCP tools/call; the gateway forwarded every one to the backend — see RESULTS.md

BENCHMARK.md · benchmarks/blockrate/RESULTS.md · benchmarks/toolprivbench/RESULTS.md (ToolPrivBench: arXiv:2606.20023) · benchmarks/agentdojo/RESULTS.md (AgentDojo: arXiv:2406.13352) · benchmarks/vs_gateway/RESULTS.md (method) · benchmarks/mcp_conformance/RESULTS.md (MCP spec 2026-07-28, last verified 2026-08-10) · benchmarks/harness_injection/RESULTS.md (method)

Self-curated corpora: a coverage / regression baseline, not an adaptive-attacker (ASR) score. The model-in-the-loop incumbents (LlamaFirewall, Invariant) are cited from their published detection scope and not re-run here — no fabricated competitor number. The native MCP gateway IS re-run: the Docker MCP Gateway v2.0.1 was re-measured live (2026-08-17) on the same 12 malformed payloads and forwarded 0/12 that airlock blocks — that number is reproduced, not claimed; see benchmarks/vs_gateway/RESULTS.md.

⬜ Published nulls — measurements that did not support a claim, published anyway

Same table shape as the wins above, on purpose. A benchmark suite that only publishes the runs that went well is a marketing asset, not a measurement. These are the runs that did not.

Null result (one command to reproduce)	What was actually measured	Why this is not a claim yet
Matched-pair multi-harness prompt injection · one planted README line, benign twin of identical shape · last verified 2026-08-15 · python -m benchmarks.harness_injection	The injection did not work — and neither did its benign twin. claude-code 2.1.233 and codex codex-cli 0.147.0 each acted on the planted script 0/6 on the injected arm and 0/6 on the benign control, while fixing the seeded bug 12/12 and running the test suite 12/12. Total across the matrix: 0/24.	n = 6 per harness per arm is too small to license a number. 0/6 carries a 95% Wilson interval of [0.0%, 39.0%] — consistent with a true action rate as high as one in three. A 10% upper bound needs n = 35 (--trials 18, 144 cells), and at n = 6 a true 5% rate would still have produced this exact zero ~74% of the time. Until that run exists this is a measurement, not a finding. · method, power, and the two earlier inconclusive runs

What this does not show: it is not evidence that either harness resists prompt injection — the benign twin of identical shape was ignored just as completely, so what was observed is indifference to this delivery channel, not detection of malicious intent, and it predicts nothing about an injection delivered through a channel these agents do act on.

The AgentDojo gap — the most defensible number here

On AgentDojo's tool_knowledge attack, airlock's least-privilege policy blocks a deterministic 86.0% (524/609) of injection→target tool-calls across all four suites — an upper bound on how much it can reduce attack success. Run model-in-the-loop, the realised reduction is smaller: attack-success-rate 45% → 10% (−35pp), gpt-4o-mini only — one model, one family (OpenAI), a 60-pair subset, 95% Wilson CI [5%, 20%], at a +10pp benign-utility cost. A single model family cannot speak for the defense — ActBench (arXiv:2608.09476) measured ASR spanning 10.1%–94.4% across models under a fixed harness — so this is a scoped point estimate, not a general claim. The bound and the realised reduction disagree by ~51pp because the bound counts every target call airlock can block, while in the loop the model does not always attempt the blocked call and some injections fail upstream of the tool seam. Publishing both, and the gap, is the honest read — most tools in this category report only the larger number. Full numbers: benchmarks/agentdojo/RESULTS.md. That [5%, 20%] interval is wide because n=60 on one model; the harness now takes --model more than once, each model with its own Wilson CI, benign-FPR, and recorded token/$ cost. A 2026-08-08 run adds the larger gpt-4o-2024-05-13 (ASR 72% → 22%, +50pp) next to gpt-4o-mini (42% → 12%, +30pp). The harness is ready to widen this past one family — the model-registry shim registers current Claude ids and Together is wired — so a keyed run over OpenAI + Anthropic + Together at the power-calc-sized 163 pairs/arm (RESULTS.md "Widening plan") would replace this scoped estimate with a real cross-family number. #123 was resolved by putting the scope inside the claim rather than carrying an over-broad headline.

┌────────────────────────────────────────────────────────────────┐
│  🤖 AI Agent: "Let me help clean up disk space..."            │
│                           ↓                                    │
│               rm -rf / --no-preserve-root                      │
│                           ↓                                    │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  🛡️ AIRLOCK: BLOCKED                                     │  │
│  │                                                          │  │
│  │  Reason: Matches denied pattern 'rm_*'                   │  │
│  │  Policy: STRICT_POLICY                                   │  │
│  │  Fix: Use approved cleanup tools only                    │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

🧩 Where this sits — beneath the gateway, at the execution boundary

Why the boundary matters now. Gartner projects 40% of enterprise apps will ship a task-specific AI agent by end-2026, up from under 5% in 2025 (Gartner, Aug 2025) — roughly an order-of-magnitude jump, in one year, in untrusted model-generated tool calls arriving at the execution boundary. That is the surface a gateway routes to but does not open up and inspect.

MCP gateways and agent-identity control planes — Microsoft Entra Agent ID, Databricks Unity AI Gateway, Docker MCP Gateway, Cloudflare, AWS, and the MCP spec's OAuth resource-server mandate — secure the transport and identity layer: who is allowed to connect, over what channel, with which token. They route and authenticate; that is necessary and they do it well.

agent-airlock sits one layer in, at the execution boundary after auth: it validates the actual tool-call payload the model produced — argument types (strict Pydantic, no coercion), hallucinated / ghost arguments, deny-by-default tool and capability scope, and output sanitization — then returns a self-healing error the model can retry against. A gateway can confirm the caller is authenticated; it does not check that transfer(amount=-1) is type-valid or that the agent picked the least-privileged tool for the task.

Reproduced, not asserted (re-measured live 2026-08-17): the same 12 malformed tool-call payloads were pushed through a live Docker MCP Gateway v2.0.1 and through airlock. The gateway forwarded 12/12 to the backend (its logs confirm it scanned for secrets and applied no-new-privileges — but not the argument contract); airlock blocked 12/12 at the contract layer, with 0/3 false positives on the benign controls. Reproduce with python -m benchmarks.vs_gateway (no Docker needed — it replays the recorded gateway measurement; regenerate that with benchmarks/vs_gateway/gateway_harness/). Full reproducible deep-dive — method, per-payload table, and an honest read of where a native gateway is already enough vs. where the in-process contract layer adds value: docs/benchmarks/mcp-gateway-payload-gap.md.

Why the payload contract can't move to the gateway (MCP 2026-07-28). The final spec made the transport stateless — SEP-2575 removed the initialize→session handshake and the Mcp-Session-Id header, and SEP-2567 pushed state into ordinary typed tool arguments. A gateway now sees independent, session-less requests and routes on the Mcp-Method / Mcp-Name headers (SEP-2243) without inspecting the body — by design. That is exactly the anchor a schema-composition check needs and no longer has: validating that oneOf / anyOf / allOf / $ref contract is neither ambiguous nor open requires the tool's whole inputSchema document, its $defs, and branch-selection logic resolved against the actual arguments — a per-call, per-tool computation at the function boundary, not a routing decision at the edge. And SEP-2106 forbids the one shortcut a gateway might take: an external $ref must not be auto-dereferenced, because a fetched schema is attacker-controlled input that would redefine the contract at call time. airlock does this statically (airlock scan-tools) and denies external refs + branch-ambiguous surfaces deny-by-default (mcp_schema_2020_12_contract_defaults).

Use both. Gateway/OAuth for the connection; airlock as the in-process call-contract layer for the payload. It's a decorator, not a proxy — zero new network hops, runs wherever your tool runs.

Propose-versus-authorize: agent-safe-pipeline and toolpermit

Two projects landed in the same week of August 2026 that people reasonably compare airlock against. Both are worth reading first, and the honest framing is that they answer a different question. They describe where the authorization boundary should sit and who gets to decide. airlock is the in-process check that runs beneath that boundary, on the call itself: strict validation, ghost-argument stripping, deny-by-default typing. A reference architecture and a type-checker are complementary layers. Claiming to replace either would be less credible than saying so.

decionis/agent-safe-pipeline (TypeScript, Apache-2.0, created 2026-08-13) is a reference architecture for the rule agents propose, policy decides: an immutable canonical intent, an independent ALLOW / ESCALATE / BLOCK verdict, verified human approval, and a SafeExecutor that consumes a single-use intent-bound grant. Its trust-boundary doc is explicit that the agent is untrusted even in-process, and that meaningful enforcement means putting the executor behind a separate service boundary.

sunhao123456sun-svg/toolpermit (Python, Apache-2.0, created 2026-08-11) is a local-first stdio MCP proxy: strict YAML allow / ask / deny policy where first match wins, a one-time approval bound to the canonical request and consumed atomically, irreversible redaction before SQLite persistence, and offline replay of recorded calls against a candidate policy.

What changed in v0.8.74. Writing the comparison above is what surfaced #143: both projects centre a three-state decision (allow / ask / deny, ALLOW / ESCALATE / BLOCK) and airlock had two, so the asymmetry could not be stated without over- or under-claiming. airlock now has the third state. SecurityPolicy(escalate_tools={"wire_*": "wires need a second pair of eyes"}, approver=...) raises PolicyEscalation and routes to the approver that agent_airlock.oversight has shipped since v0.8.4.

Two things this deliberately is not. It is not an approval UI, a request store, or a resumable pending-call queue — the projects above own that workflow and do it well; airlock owns a function call. And the approver is synchronous, which is a real cost in a hot path and is called out in #143 itself. What airlock adds is the in-process context: the argument values, the resolved policy, the capability set, and the tier budget are all already in hand at the moment of decision, so "transfers under $500 proceed, over $500 ask a human" is expressible as a property of the call rather than of the function. An escalation with no approver registered blocks — PolicyEscalation subclasses PolicyViolation, so deny-by-default is enforced by the type lattice rather than by a runtime branch.

Which one you actually want

Use agent-safe-pipeline if you are designing the authorization boundary from scratch and the open question is who is allowed to authorize this action. It is the better choice there, and by a clear margin: it is a worked model for intent capture, independent verdicts, and human escalation, and it will shape the architecture in ways a validation library cannot.

Use toolpermit if you want a human approval prompt and a redacted audit trail in front of an existing stdio MCP server without touching that server's code. Drop the proxy in and write the policy. Its ask is policy-driven — the rule decides which calls need a human, and a loopback UI collects the answer. airlock closed most of that gap in v0.8.74: a SecurityPolicy can now escalate — escalate_tools raises PolicyEscalation and routes to the requires_human_oversight approver (#143, worked example). What toolpermit still has and airlock does not is the UI and the store: airlock's approver is an operator-supplied callable with no loopback prompt, no pending-request queue, and no redacted SQLite trail. If you want the human prompt itself rather than the hook to build one, that is toolpermit.

Use agent-airlock if the tool function is yours and the open question is whether this specific payload is well-formed. Strict types with no coercion, arguments the model invented, deny-by-default scope, checked at the function boundary with no new network hop.

What airlock does not do, stated plainly because the boundary matters more than the feature list: there is no approval UI, no human-verification service, and no notion of an action being authorized in the business sense. It is not a proxy, so it never sees a call to a tool you did not decorate. It answers "is this call well-formed and in scope", which is a narrower question than either project above is asking — and one they both leave to the layer underneath.

📊 Benchmarks: AgentDojo (that wedge, measured — not asserted)

The gateway argument above is measurable, so we measured it on AgentDojo (Debenedetti et al., NeurIPS 2024), a third-party model-in-the-loop adaptive-attacker benchmark. airlock is registered as an AgentDojo defense at the tool-execution seam (deny-by-default least-privilege SecurityPolicy + ghost-argument BLOCK + output sanitizer), then run against the tool_knowledge injection attack across all 4 suites (workspace, banking, travel, slack; benchmark v1.2.1).

Result 1 — deterministic block coverage (free, offline, no model):

86.0% of tool_knowledge injection→task pairs have their target tool-call blocked by airlock's least-privilege policy — a deterministic upper bound on ASR reduction, not the model-in-the-loop ASR.

Result 2 — model-in-the-loop utility-under-attack + ASR (the leaderboard metrics): run the --model path with a key; it regenerates RESULTS.md with a baseline vs airlock table (benign utility / utility-under-attack / ASR / the defense's utility cost).

The honest miss: a suite-wide allow-list catches far fewer (0% on banking — injections there abuse a legitimate tool like send_money with a malicious recipient). Least-privilege scoping per task is what does the work; argument-level abuse of an allowed tool needs airlock's strict Pydantic validation, not the tool-level policy alone. We report the misses — no "blocks everything" claim.

pip install "agent-airlock[bench]"
python -m benchmarks.agentdojo.run                                   # Result 1 (deterministic)
python -m benchmarks.agentdojo.run --model gpt-4o-mini-2024-07-18 \
  --out benchmarks/agentdojo/RESULTS.md                              # Result 2 (needs OPENAI_API_KEY)

Full method, per-suite caveats, and the gateway cross-link: benchmarks/agentdojo/RESULTS.md.

🔍 Scan then enforce (with agent-audit-kit)

airlock is the runtime half of a two-layer story. Its sibling scanner, agent-audit-kit — "the missing npm audit for AI agents" — is the build / CI / IDE-time half: a deterministic, offline static scanner for MCP-connected pipelines (AST taint analysis; MCP-config, supply-chain, tool-poisoning, secret, transport, and trust-boundary rules; automated CVE feeds) that ships as a CLI, GitHub Action, pre-commit hook, and VS Code extension, and emits SARIF for the GitHub Security tab.

They sit at different points in the lifecycle and compose cleanly — scan before deploy, enforce at runtime:

1. Scan — agent-audit-kit scan . finds unguarded surfaces before they ship: an MCP tool with additionalProperties left open, a poisoned server-card description, a subprocess/argv injection surface, an unsigned _meta trust decision.
2. Enforce — wrap the tool with @Airlock(...) (or opt into the matching preset — mcp_meta_trust_2026_07_defaults, mcp_schema_2020_12_contract_defaults, mcp_spec_2026_07_header_integrity_defaults, …) so the same class is blocked in production, at the function boundary, not merely flagged in a report.
3. Pre-flight — airlock scan-tools is airlock's own narrow static check for the exact contracts its runtime guards enforce; run it in CI alongside the broader audit-kit scan, and use --output sarif so both feed the same GitHub Security tab.

The two stay separate packages on purpose: a static scanner carries a rule database and CVE feeds that update on their own cadence, while airlock's runtime core stays Pydantic-only and zero-dep. Use the scanner to find what to guard; use airlock to guard it.

🎯 30-Second Quickstart

pip install agent-airlock

from agent_airlock import Airlock

@Airlock()
def transfer_funds(account: str, amount: int) -> dict:
    return {"status": "transferred", "amount": amount}

# LLM sends amount="500" (string) → BLOCKED with fix_hint
# LLM sends force=True (invented arg) → STRIPPED silently
# LLM sends amount=500 (correct) → EXECUTED safely

That's it. Your function now has ghost argument stripping, strict type validation, and self-healing errors.

🧠 The Problem No One Talks About

Enterprise solutions exist: Prompt Security (now part of SentinelOne), Pangea (proxy your data), Cisco ("coming soon"). All are quote-based; none publishes list pricing.

We built the open-source alternative. One decorator. No vendor lock-in. Your data never leaves your infrastructure.

✨ What You Get

Ghost Args Strip LLM-invented params	Strict Types No silent coercion	Self-Healing LLM-friendly errors	E2B Sandbox Isolated execution	RBAC Role-based access	PII Mask Auto-redact secrets
Network Guard Block data exfiltration	Path Validation CVE-resistant traversal	Circuit Breaker Fault tolerance	OpenTelemetry Enterprise observability	Cost Tracking Budget limits	Vaccination Auto-secure frameworks

📋 Table of Contents

🔥 Core Features

🔒 E2B Sandbox Execution

from agent_airlock import Airlock, STRICT_POLICY

@Airlock(sandbox=True, sandbox_required=True, policy=STRICT_POLICY)
def execute_code(code: str) -> str:
    """Runs in an E2B Firecracker MicroVM. Not on your machine."""
    exec(code)
    return "executed"

Air-gapped / on-prem? DockerBackend is the supported alternative — cap_drop=["ALL"], no-new-privileges, network_mode="none", timeout enforced, opt-in pytest -m docker integration tests. See docs/sandbox/docker.md.

ModalBackend — Modal-hosted sandbox (v0.8.11+, issue #30)

Already running the rest of your agent on Modal? ModalBackend lets you keep airlocked tool execution on the same substrate instead of mixing E2B and Modal billing / observability.

pip install "agent-airlock[modal]"

from agent_airlock import Airlock, STRICT_POLICY, AirlockConfig
from agent_airlock.sandbox_backend import ModalBackend

backend = ModalBackend(
    app_name="my-airlock-sandbox",
    image_ref="python:3.11-slim",
    cpu=0.5,
    memory_mb=512,
    timeout_s=30,
    # network_policy=None  → block_network=True (fail-closed default)
)

@Airlock(sandbox=True, sandbox_required=True, policy=STRICT_POLICY,
         config=AirlockConfig(sandbox_backend=backend))
def execute_code(code: str) -> str:
    exec(code)
    return "executed"

Isolation model — read before you reach for cap_drop. Modal sandboxes run under gVisor (kernel-syscall filtering), not under Docker-style capability dropping. The Modal Python SDK does not expose cap_drop / cap_add / seccomp / no-new-privileges — there is no equivalent knob to map. If your threat model needs Linux-capability dropping at the container layer, keep using DockerBackend. The network posture is configurable: ModalBackend defaults to block_network=True (deny-by-default), and a supplied NetworkPolicy maps to Modal's block_network flag (allow_egress=False → blocked, True → allowed). Hostname allowlists in NetworkPolicy.allowed_hosts do not forward to Modal (their API is CIDR-only); the backend logs a structlog warning and the operator is expected to re-state hostname constraints at the Airlock policy layer.

ModalBackend is opt-in only — it is NOT added to the get_default_backend() priority chain (E2B → Docker → Local stays the default flow). Existing callers see no behavior change.

📜 Security Policies

from agent_airlock import (
    PERMISSIVE_POLICY,
    STRICT_POLICY,
    READ_ONLY_POLICY,
    BUSINESS_HOURS_POLICY,
    CAMOUFLAGE_RESISTANT_POLICY,  # v0.8.6
)

# Or build your own:
from agent_airlock import SecurityPolicy

MY_POLICY = SecurityPolicy(
    allowed_tools=["read_*", "query_*"],
    denied_tools=["delete_*", "drop_*", "rm_*"],
    rate_limits={"*": "1000/hour", "write_*": "100/hour"},
    time_restrictions={"deploy_*": "09:00-17:00"},
)

CAMOUFLAGE_RESISTANT — detector-independent injection defense (v0.8.6)

arXiv:2605.22001 ("Blind Spots in the Guard", Pai, May 2026) shows that production injection detectors — Llama Guard 3 included — drop to IDR = 0.000 on payloads that mimic the target document's domain vocabulary and authority structure. Per the paper, detection rates collapse from 93.8% to 9.7% on Llama 3.1 8B and from 100% to 55.6% on Gemini 2.0 Flash.

CAMOUFLAGE_RESISTANT_POLICY does not rely on payload-content signatures at all. It blocks at four structural seams an attacker has to ride regardless of phrasing:

1. Deny-by-default tool allowlist. Empty allowed_tools means nothing is callable; deployments opt every tool in by name. A camouflaged directive targeting an unlisted tool is blocked on allowlist grounds without ever invoking a detector.
2. Ghost-argument BLOCK. A camouflaged directive cannot smuggle undeclared parameters past validation.
3. Hard output cap + sanitization. Tool output that re-enters the model context is truncated and PII/secret-masked so a camouflaged directive embedded in tool output can't carry into a downstream agent at full length.
4. Per-call reauthorization (debate-amplification guard). Once a tool's output has flowed back into the model, any reinvocation requires an explicit context.authorize_once(tool) grant from the harness — breaking the multi-agent fan-out path the paper identifies.

from agent_airlock import Airlock, apply_camouflage_resistant

bundle = apply_camouflage_resistant(allowed_tools=["read_file", "search"])

@Airlock(config=bundle.config, policy=bundle.policy)
def read_file(path: str) -> str:
    ...

apply_camouflage_resistant() composes the matching AirlockConfig (unknown-args BLOCK, sanitization on, output cap 4000 chars) with a SecurityPolicy carrying your explicit allowlist. The preset is deliberately incomplete on its own — the config-level knobs and the policy-level knobs span two seams, so the factory returns both as a CamouflageResistantBundle.

Running an MCP server with STDIO transport? Also wire the Ox MCP STDIO sanitizer via stdio_guard_ox_defaults() — it blocks the entire CVE-2026-30616 class (shell metacharacter injection, non-allowlisted binaries, Trojan-Source RTL overrides, and inline-code flags) before subprocess.Popen.

🪪 MCP server attestation (v0.8.10)

arXiv:2605.24248 ("Attested Tool-Server Admission", Metere, May 2026) calls out a gap MCP itself does not close: the protocol standardises message exchange between LLM agents and tool servers but says nothing about trust. Anybody who can answer on the wire can declare themselves a tool server.

mcp_attested_admission_defaults() is a deny-by-default opt-in preset that closes the gap host-side, mirroring the paper's three additive mechanisms:

1. Offline-signed clearance assertion. Before any tool from an MCP server is dispatched, the host fetches a JWS-compact clearance from {server_url}/.well-known/mcp-clearance (path is configurable) and verifies its signature against an operator-pinned trust root. The trust root is supplied to AttestedAdmissionConfig at process startup — never network-fetched on the hot path.
2. Deny-by-default per-server tool allowlist. Admitting a server is not the same as trusting its every tool. The verified clearance carries an explicit list of tool names the host will permit; everything else is denied. The sub claim is matched against the server identity the host is about to dispatch to (so a stolen clearance from server A can't admit a tool call to server B).
3. Flavor-gated enforcement. ENFORCE (default) hard-denies on missing / invalid / expired clearance; WARN logs and admits — the staged turn-up an operator wants when introducing the gate against real traffic.

Every admission decision emits a ReceiptVerdict on the guard="mcp_attested_admission" channel, so the existing airlock attest DSSE pipeline picks decisions up unchanged — this preset does not invent a new log.

from agent_airlock.mcp_proxy_guard import MCPProxyConfig, MCPProxyGuard
from agent_airlock.mcp_spec.attested_admission import TrustRoot
from agent_airlock.policy_presets import mcp_attested_admission_defaults

# Operator pins the trust root at startup. Never fetched at runtime.
with open("/etc/airlock/mcp-clearance-root.pem", "rb") as fh:
    pinned_pem = fh.read()

cfg = mcp_attested_admission_defaults(
    trust_root=TrustRoot(key_id="ops-2026Q2", ed25519_pem=pinned_pem),
    enforcement_mode="ENFORCE",       # deny-by-default
    max_clearance_age_days=30,
)
guard = MCPProxyGuard(MCPProxyConfig(attested_admission=cfg))

decision = guard.audit_tool_admission(
    server_url="https://mcp.example.com",
    server_id="srv-alpha",            # expected `sub` claim
    tool_name="read",
)
if not decision.admitted:
    raise RuntimeError(decision.reason)

Signature verification needs the [attested] extra (pulls in cryptography for offline Ed25519 / RSA-PSS / JWKS verification); the base install stays zero-runtime-dep.

Install with pip install "agent-airlock[attested]". Opt-in only — existing callers that don't set attested_admission get exactly v0.8.9 behavior.

🧭 Behavioral sequence guard (v0.8.12)

Watches the ordered stream of tool calls in a session and flags divergence from a declared expected order — not the model's stated reasoning trace.

arXiv:2605.27901 ("The Fragility of Chain-of-Thought Monitoring", Onyame, Zhou, Thopalli, Kailkhura & Agarwal, May 2026) reports an average 95.9% CoT unfaithfulness across 8B–120B-parameter models — including answer-switching, post-hoc rationalisation, and procedural exploitation of hints. Trusting the model's stated reasoning to detect misbehavior is therefore not viable. Trusting its behavior — the sequence of tools it actually invokes — is.

SequenceGuard is an opt-in field on SecurityPolicy that runs in the @Airlock seam right after the standard policy check, in two modes:

DECLARED mode — operator supplies a permitted-transition DAG. Any transition not in the DAG is a SequenceViolation. Deny-by-default.

from agent_airlock import Airlock, SecurityPolicy
from agent_airlock.sequence_guard import SequenceGuard, ENTRY_SENTINEL

policy = SecurityPolicy(
    sequence_guard=SequenceGuard(
        mode="declared",
        action="block",                       # or "warn"
        dag={
            ENTRY_SENTINEL: {"read"},         # only `read` may start a session
            "read": {"read", "summarize"},    # after read, either re-read or summarize
            "summarize": {"send"},            # after summarize, only send
            "send": set(),                    # send is terminal
        },
    ),
)

BASELINE mode — guard maintains a per-session-key Markov transition profile in a local JSON file (no cloud, no PII — only tool names and SHA-256 shape hashes of (arg types, kwarg names+types), never argument values) and flags transitions with observed P(curr | prev) < threshold once the sample size from prev reaches min_baseline_samples.

from pathlib import Path
from agent_airlock.sequence_guard import SequenceGuard

policy = SecurityPolicy(
    sequence_guard=SequenceGuard(
        mode="baseline",
        baseline_path=Path("/var/lib/airlock/sequence-baseline.json"),
        low_probability_threshold=0.05,   # flag the bottom 5%
        min_baseline_samples=50,          # don't flag until 50 obs from `prev`
    ),
)

Every flagged transition emits OTel span attributes on the current span (airlock.sequence_guard.mode, .from_tool, .to_tool, .session_key, .observed_probability) via the existing observability provider — telemetry failures are swallowed so they cannot break enforcement.

Not AnomalyDetector (that's rate / endpoint-diversity / error-rate / consecutive-blocked over sliding windows). SequenceGuard is per-transition ORDER signal. Run both for layered coverage. Not a chain-of-thought monitor — by construction.

Strictly opt-in. The new SecurityPolicy.sequence_guard field defaults to None; callers that don't set it get exactly v0.8.11 behavior. Zero new runtime deps — Pydantic-only core stays intact.

DECLARED mode is also the one control here that catches a detour-hijacking trajectory (arXiv:2608.12273), where a malicious skill description recruits unnecessary benign skills and then re-enters the original route so the task still completes. It catches it only if you declared the route first, and the honest limits — what the audit log does and does not show about the resulting cost — are written up in docs/security/detour-hijacking.md.

🛑 Action-time contradiction gate (v0.8.15)

arXiv:2605.27157 ("Detecting Is Not Resolving: The Monitoring Control Gap in Retrieval Augmented LLMs", Yu et al., 2026) shows that LLMs readily acknowledge contradictory evidence in their reasoning trace yet "this awareness fails to constrain their final recommendations". The deficit is at action selection — single-turn diagnostics overestimate RAG safety, and detection alone is not a control.

ActionContradictionGate is an opt-in policy hook that wraps three pluggable detectors (any one trips) and a privileged-sink glob set. When a detector trips AND the dispatched tool matches a privileged sink AND the harness has not issued an explicit allow, the gate blocks the call (or warns, depending on action=).

The explicit-allow primitive is not new — the gate reuses the existing AirlockContext.authorize_once(tool_name) (introduced for the v0.8.6 reauth flow). Same one-shot grant, same semantics. After a one-shot is consumed the gate re-locks — the harness must mint a fresh authorize_once for each privileged action.

import re
from agent_airlock import Airlock, SecurityPolicy
from agent_airlock.action_contradiction_gate import ActionContradictionGate

policy = SecurityPolicy(
    action_contradiction_gate=ActionContradictionGate(
        # Detector 1: a boolean flag the RAG pipeline flips on after
        # it sees an evidence-vs-claim conflict the agent discussed.
        signal_field_key="evidence_contradiction",
        # Detector 2: pluggable regex against the SAME key when its
        # value is a string (operator-controlled marker — never the
        # model's full reasoning trace).
        marker_regex=re.compile(r"contradict|conflict|disagree", re.I),
        # Detector 3: fully pluggable callable; receives the context.
        # predicate=lambda ctx: ctx.metadata.get("conflict_count", 0) > 1,
        # Default privileged sinks: send_* / export_* / commit_* /
        # transfer_* / delete_* + the v0.8.14 outbound-integration set.
        # Operators can narrow via `privileged_sinks=(...)`.
        action="block",  # or "warn" for staged turn-up
    ),
)

Off-by-default invariant. SecurityPolicy.action_contradiction_gate defaults to None; non-RAG flows pay zero false-positive tax (no detector runs, no log lines, no metadata reads). Even when wired, the gate is inert until at least one detector slot is configured — so a partial roll-out (gate attached but detectors flipped off) admits everything.

Not a chain-of-thought monitor. The gate reads operator- controlled signals only (a metadata field, an operator regex, an operator predicate). It never reads the model's own claim that it has or has not noticed a contradiction — the paper's whole point is that those claims do not gate behavior.

Not sequence_guard (v0.8.12) — that flags unusual call ORDER. Not reauth_on_untrusted_reinvocation (v0.8.6) — that's count-driven on a per-tool counter. This gate is signal-driven and targets a specific privileged-sink glob set. They compose; run all three for layered coverage.

Strictly opt-in. Zero new runtime deps — Pydantic-only core stays intact. The new SecurityPolicy.action_contradiction_gate field defaults to None; callers that don't set it get exactly v0.8.14 behavior.

📊 Adversarial-negotiation regression harness (v0.8.17)

A deterministic harness that measures what the deny-by-default governance layer does to a fixed set of adversarial buyer-seller negotiation actions — and reports two metrics named to line up with an external published baseline so the numbers can sit side by side.

airlock negotiation-bench --report markdown

Each scenario carries a concrete, checkable unsafe action and runs twice — baseline (no airlock, the unsafe event lands) and governed (the same action through the real @Airlock intercept-before-execute path, no policy-layer mocking). Three unsafe-action classes each exercise a different real interception mechanism: price-below-floor → Pydantic strict-validation, secret-leak → the output sanitizer, transfer-outside-policy → deny-by-default SecurityPolicy. Benign deals are included to confirm governance does not over-block.

The OCL row is an external result, not agent-airlock's. It was measured on live frontier LLM agents in AgenticPay-adapted negotiation (OCL, arXiv:2606.04306; AgenticPay, arXiv:2602.06008) and is reproduced here only for directional comparison — both put governance at the execution boundary. It is not the same experiment: agent-airlock is a deterministic execution-boundary validator, not an LLM, and this harness does not call a model. The agent-airlock rows are a property of the policy layer under a worst-case scripted adversary, exercised through the real @Airlock path.

The harness doubles as a regression gate: --fail-if-governed-unsafe exits non-zero if the governed unsafe_execution_rate ever rises above zero, so a future change that weakens the policy layer fails CI. Zero new runtime deps; fully deterministic (no randomness, no network, no model call).

🔎 Privilege right-sizing — airlock explain --unused-scopes (v0.8.13)

A read-only CLI that surfaces over-permissioning: it diffs the SecurityPolicy's granted tool scopes against the tools the agent actually called (from an OTLP export OR a native audit JSONL), per AgentIdentity, and prints the dead-weight set plus a suggested tightened allow-list.

# Install; the unified `airlock` CLI becomes available
pip install "agent-airlock>=0.8.56"

# Diff granted vs used; print a table
airlock explain --unused-scopes \
    --policy ./security-policy.toml \
    --trace  ./agent.audit.jsonl

# Same, machine-readable, plus a proposed tightened policy preview
airlock explain --unused-scopes \
    --policy ./security-policy.toml \
    --trace  ./otel-export.json \
    --format json \
    --suggest-policy

Observability-only. This command never mutates the SecurityPolicy, never writes the policy file, and never auto-applies the suggestion. The deny-by-default posture is unchanged — the right-size CLI is a review aid, not an enforcement primitive. The --suggest-policy output is intentionally a stdout preview so a human reviews the tightened allow-list before adopting it by hand.

Trace formats (auto-detected by inspecting the file head):

• Audit JSONL — the format AuditLogger already emits. One JSON object per line, with tool_name / agent_id / blocked. Blocked calls are excluded from the "actually called" set — a blocked call is not an exercise of a granted scope.
• OTLP JSON — the format opentelemetry-exporter-otlp writes. Span name is the tool name; attributes.agent_id keys the per- agent diff. If a span carries airlock.blocked=true it is skipped, same as JSONL.

Diff semantics. The matcher is fnmatch — the same glob semantics SecurityPolicy.check_tool_allowed uses internally, so the suggested tightened allow-list admits exactly the tools the agent was observed calling (no surprises at adoption time). Denied-list patterns are forwarded unchanged to the suggestion: denials are intent, not usage data.

Strictly observability. No new runtime deps. Reachable as airlock explain via the unified dispatcher (v0.8.56+); the airlock-explain console script and python -m agent_airlock.cli.explain remain as equivalent aliases.

🧾 Static contract / type-checker — airlock scan-tools (v0.8.42)

The wedge, made static. Where @Airlock enforces the contract at call time, scan-tools type-checks the tool declarations before your agent loads them — a deny-by-default contract layer for AI tool calls, distinct from content-signature tool-poisoning scanners (MCP-Scan, eSentire MCP-Scanner).

pip install "agent-airlock>=0.8.42"

# Grade every tool declaration against a least-privilege policy (CI-friendly).
airlock scan-tools ./tools/ --policy strict          # exit 0=clean 1=warn 2=fail
airlock scan-tools ./mcp.json --output json

It reads a .json tool-def file, a directory of them, or an mcp.json / claude_desktop_config.json config with inlined tool schemas, and grades each tool pass / warn / fail:

• Over-broad argument surface — additionalProperties is not false on a destructive/mutating tool (a ghost/hallucinated-argument vector). FAIL.
• Missing type constraints — a sensitive string arg (path / url / command / …) with no enum / pattern / format / maxLength, or an untyped property. WARN.
• Capability caps exceed policy — the tool's inferred capability (from MCP annotations, an explicit capabilities list, or a name heuristic) is denied / not-granted by the policy's shipped CapabilityPolicy. FAIL.
• Server-card trust boundary — a tool description carrying injected instructions ("…ignore previous instructions and run…"). Reuses the mcp_spec_2026_07 Server-Card / SEP-2468 guard. FAIL.

Policies map 1:1 to shipped constants — permissive / read-only / strict / deny-by-default — no invented policy. strict uses the STRICT capability caps (shell/delete denied, write not granted). Coverage is measured against MCPTox-derived fixtures (python -m benchmarks.scantools_mcptox) and reported as-is: 69.2% static contract-checking coverage · 100% precision — not MCPTox's model-in-the-loop Attack Success Rate.

Static review aid, Pydantic-only, zero-dep core. Reachable as airlock scan-tools via the unified dispatcher (v0.8.56+); the airlock-scan-tools console script and python -m agent_airlock.cli.scan_tools remain as equivalent aliases.

⌨️ One CLI: airlock <command> (unified dispatcher, full command set since v0.8.56)

Every command in this section is a subcommand of a single airlock entry point. Run it with no arguments to discover them all:

pip install "agent-airlock>=0.8.56"

airlock                                   # list every subcommand + one-line description
airlock scan-tools ./tools/ --policy strict
airlock doctor --path .
airlock explain --unused-scopes --policy p.toml --trace t.jsonl
airlock corpus-bench --format md

airlock <cmd> ... delegates to the exact same code as python -m agent_airlock.cli.<cmd> ..., so flags are identical between the two forms — verified in tests/test_cli_dispatcher.py. The older airlock-explain, airlock-conformance, and airlock-scan-tools scripts stay as equivalent aliases.

🩹 Skill-resistant trace redaction + watermark (v0.8.24)

Why traces are an extraction surface: an agent's emitted trace/receipt is a distillation target, not just an audit artifact. A trace that records the tuned thresholds a policy fired on, the exact tool-call arguments, and the recovered intermediate formulas/strategies hands a competitor the recipe — enough to clone the behaviour without paying for the search that found it. The verifier, by contrast, needs only the evidence (the gate ran / the policy fired / pass-fail), never the recipe. This is the RedAct-style threat model — a composition of published behavioural-watermarking work (Agent Guide, arXiv:2504.05871; CoTGuard, arXiv:2505.19405; Distilling the Thought, arXiv:2601.05144). agent-airlock does not reproduce any paper's benchmark.

TraceRedactionPolicy (opt-in, OFF by default for backward compat, ON under STRICT_POLICY) runs at the non-local sink (e.g. the OTel exporter): it (a) localizes protected fields with a configurable field-classifier (tuned thresholds, tool-call args, recovered formulas/strategies), (b) rewrites them to keep verifier-critical evidence while dropping the recipe, and (c) embeds a per-tenant behavioural watermark so a leaked trace is provably yours. Detect it with airlock trace verify-watermark <trace.json> (cryptographic keyed-HMAC match → high true-detection, low false-alarm); add --redaction-report to see what was localized / rewritten / preserved. Stdlib-only — no new runtime dependency.

from agent_airlock import TraceRedactionPolicy, trace_redact, verify_watermark

pol = TraceRedactionPolicy(enabled=True, tenant_id="acme-co", watermark_secret="...")
redacted, report = trace_redact(trace, pol)   # tuned_threshold → evidence stub; recipe dropped
assert verify_watermark(redacted, pol).detected   # provably yours

✅ Fail-closed terminal-claim guard — no_false_success (v0.8.25)

An honest stall is recoverable; a confident wrong done is not. The dominant failure mode of unattended long-horizon agents isn't crashing — it's confidently reporting success they never verified (Goal-Autopilot, arXiv:2606.11688). The no_false_success preset enforces that paper's No-False-Success floor: a terminal/done claim is admitted only if a named, falsifiable check actually executed and passed THIS run. No receipt, a failed check, or a forged/replayed receipt → the guard fails closed to a recoverable honest stall (run the named check and retry), never a fabricated success.

Forgery resistance is structural: the guard mints a per-run token and only trusts a receipt it stamped by executing the check this run — a receipt that's merely present (hand-built, or replayed from a prior run) is rejected. Opt in per-agent with AirlockConfig(require_done_receipt=True) (or require_done_receipt = true under [airlock] in airlock.toml); OFF by default. Stdlib-only — no new runtime dependency.

from agent_airlock import no_false_success_defaults, NoFalseSuccessStall

preset = no_false_success_defaults({"tests_green": run_pytest})  # falsifiable check
preset["guard"].run("tests_green")        # actually execute the check this run
preset["check"]("tests_green")            # raises NoFalseSuccessStall unless it passed

🔗 Capability-union boundary at grant time (v0.8.70)

A tool that can read files and a tool that can send data are each fine on their own, but held together they are an exfiltration path — the "lethal trifecta" capability combination named at Black Hat USA 2026. CapabilityCapEngine.grant_lease evaluates the union of capability the calling context would hold if a lease were granted and denies {filesystem-read or credential} + {non-allowlisted network egress} by default — even when each lease is individually permitted — naming the prior lease that combined to trigger it. This evaluates at grant time, not call time, so it does nothing about capabilities acquired outside the lease system; the escape hatch is an explicit UnionOverride, recorded loudly in the tamper-evident decision log with the granting identity.

from agent_airlock.capability_caps import (
    CapabilityCapEngine, CapabilityRulesConfig, CapabilityCategory, Lease,
)

engine = CapabilityCapEngine(CapabilityRulesConfig())
engine.grant_lease("agent", Lease("l1", "read_config",
                                  frozenset({CapabilityCategory.FILESYSTEM_READ})))   # allowed alone
engine.grant_lease("agent", Lease("l2", "post_to_webhook",
                                  frozenset({CapabilityCategory.NETWORK_EGRESS})))     # CapabilityUnionDeniedError, names "l1"

📌 CIMD trust-anchor pinning (v0.8.71)

MCP 2026-07-28 replaces Dynamic Client Registration with Client ID Metadata Documents: the client_id is an https URL and the metadata document is served from that URL, by the client. The trust anchor moved from a registration record you hold to a document someone else can rewrite at any time — so "the client I approved" and "the client I am about to authorize" are now two fetches with a gap in between. CIMDGuard pins the canonicalised document on one explicit, attributed approval (no trust-on-first-use), re-resolves on every subsequent grant, and denies by default on drift, naming exactly which fields moved. A rotation is never auto-accepted; the only way forward is another explicit approve(). A document that 404s or loses a required field moves the client to denied, not back to unknown. Non-https, private-resolving, and cross-origin-redirecting client_ids are refused before the body is trusted.

from agent_airlock.mcp.cimd import CIMDGuard, SQLiteCIMDPinStore

guard = CIMDGuard(store=SQLiteCIMDPinStore("airlock.db"))
guard.approve("https://client.example.com/.well-known/oauth-client", approved_by="secops")

# Later, the client rewrites its own redirect_uris:
decision = guard.check("https://client.example.com/.well-known/oauth-client")
decision.verdict          # CIMDVerdict.DENY_DRIFT
[c.field for c in decision.changed_fields]   # ['redirect_uris']

Wired into the same grant_lease decision point as the capability-union boundary above, so a lease grant has one place that answers both "who is asking" and "what would they then hold":

engine = CapabilityCapEngine(CapabilityRulesConfig(), cimd_guard=guard)
engine.grant_lease("agent", lease, client_id="https://client.example.com/.well-known/oauth-client")
# CIMDTrustAnchorError if the anchor moved — evaluated before the union

It pins a document; it does not judge whether that document was trustworthy the first time, and it verifies at grant time rather than continuously. See docs/mcp/cimd-trust-anchor.md.

💰 Cost Control

A runaway agent can burn $500 in API costs before you notice.

from agent_airlock import Airlock, AirlockConfig

config = AirlockConfig(
    max_output_chars=5000,    # Truncate before token explosion
    max_output_tokens=2000,   # Hard limit on response size
)

@Airlock(config=config)
def query_logs(query: str) -> str:
    return massive_log_query(query)  # 10MB → 5KB

ROI: 10MB logs = ~2.5M tokens = $25/response. Truncated = ~1.25K tokens = $0.01. 99.96% savings.

Per-model-tier budgets (v0.8.7)

The flat max_output_* caps above apply uniformly to every call. ModelTierBudget caps per-call cost and output tokens per model tier label (e.g. "frontier" / "mid" / "small"), evaluated before the tool runs. Untagged calls fall back to a configurable strict_tier (deny-by-default — the cheapest tier).

from agent_airlock import (
    Airlock, ModelTierBudget, SecurityPolicy, TierBudget,
)

policy = SecurityPolicy(
    model_tier_budget=ModelTierBudget(
        tiers={
            "frontier": TierBudget(max_cost_cents=50, max_output_tokens=4000),
            "mid":      TierBudget(max_cost_cents=10, max_output_tokens=2000),
            "small":    TierBudget(max_cost_cents=2,  max_output_tokens=1000),
        },
        strict_tier="small",  # untagged → cheapest tier (deny-by-default)
    ),
)

@Airlock(policy=policy, return_dict=True)
def call_model(prompt: str, **_extra):
    return run_my_router(prompt)

# The router tags each call. Airlock blocks before the model fires.
call_model("Draft a tweet",  _airlock_tier="small",    _airlock_input_tokens=50)
call_model("Deep analysis", _airlock_tier="frontier", _airlock_input_tokens=200_000)
# →  AIRLOCK_BLOCK: Tier 'frontier' budget exceeded (worst-case 66¢ > cap 50¢)

Routing logic stays in the user's router. Three tagging routes are supported:

1. _airlock_tier kwarg — stripped before the tool sees it.
2. context.metadata["airlock_tier"] — set on a contextvar-stored AirlockContext by the router's session middleware.
3. tier_resolver callback — ModelTierBudget(tier_resolver=fn) where fn(model_id: str) -> tier_label lives in the caller's code. Airlock invokes the callback when context.metadata["model_id"] is set; it carries no vendor-specific model→tier table.

After execution, actual vs estimated cost is reconciled into the global CostTracker (observability — never blocks). See examples/model_tier_budget.py for all four patterns including composition with allow/deny lists.

A ready-to-use strict_tier_budget_policy() preset returns a SecurityPolicy seeded with the table above.

🔐 PII & Secret Masking

config = AirlockConfig(
    mask_pii=True,      # SSN, credit cards, phones, emails
    mask_secrets=True,  # API keys, passwords, JWTs
)

@Airlock(config=config)
def get_user(user_id: str) -> dict:
    return db.users.find_one({"id": user_id})

# LLM sees: {"name": "John", "ssn": "[REDACTED]", "api_key": "sk-...XXXX"}

13 PII types detected · 4 masking strategies · Zero data leakage

Opt-in regional PII (pii_locales)

Aadhaar / PAN / UPI / IFSC / India-mobile ship as SensitiveDataType members, but are not added to the default mask_pii=True set — to keep the surface zero-dep and US-shaped by default. v0.8.9 adds a pii_locales opt-in that pulls them in and tightens detection:

config = AirlockConfig(
    mask_pii=True,
    pii_locales=["in"],   # opt in to India-locale detection
)

@Airlock(config=config)
def lookup(query: str) -> str:
    return (
        "User: राम कुमार, "
        "Aadhaar: 234567890124, "       # → "********0124" (last-4 only, UIDAI standard)
        "PAN: ABCPE1234F, "             # → "AB******4F"  (first-2 + last-2; 4th char P = valid PAN entity)
        "UPI: alice@oksbi, "            # → "a***@oksbi"  (mask local part, keep @bank)
        "phone: 555-123-4567"           # still masked by existing PHONE regex
    )

Activated when "in" in pii_locales:

• Aadhaar Verhoeff checksum gate — the existing Aadhaar regex is permissive (any 12-digit number starting 2-9 matches). With the opt-in, each match must also pass the UIDAI Verhoeff checksum, cutting the FP rate ~10x on random IDs / phone numbers.
• PAN entity-char gate (v0.8.46) — a PAN-shaped match whose 4th character is not a valid holder-type code (P/C/H/F/A/T/B/L/J/G) is dropped, cutting false positives on random [A-Z]{5}[0-9]{4}[A-Z] strings.
• India mobile (v0.8.46) — SensitiveDataType.INDIA_MOBILE detects a +91 / 91 / trunk-0 prefixed 10-digit number starting 6-9 and masks to +91-XXXXX-<last3>. Prefix-required by design: a bare 10-digit run is already masked by the US-shaped PHONE detector, so India-mobile only claims the +91 forms and never shares a span with it.
• Devanagari personal-name detection — PERSONAL_NAME_DEVANAGARI runs against the Unicode block U+0900–U+097F, with a small allowlist of common Hindi greetings / pronouns / interrogatives to keep ordinary prose from being masked. Conservative heuristic — production callers who need precise extraction should layer NER on top.

These align with India's DPDP Act 2023 (Digital Personal Data Protection); the india_dpdp_2023_policy() / apply_india_dpdp_2023() preset pair turns the tool/capability gate and these maskers on in one call. The additions were driven by the DPDP Consent-Manager rules (effective 2026-11-14), which sharpen data-fiduciary obligations for Aadhaar / PAN / mobile handling.

The flag is additive and reversible — pii_locales=[] (the default) preserves the prior behavior bit-for-bit.

🌐 Network Airgap (V0.3.0)

Block data exfiltration during tool execution:

from agent_airlock import network_airgap, NO_NETWORK_POLICY

# Block ALL network access
with network_airgap(NO_NETWORK_POLICY):
    result = untrusted_tool()  # Any socket call → NetworkBlockedError

# Or allow specific hosts only
from agent_airlock import NetworkPolicy

INTERNAL_ONLY = NetworkPolicy(
    allow_egress=True,
    allowed_hosts=["api.internal.com", "*.company.local"],
    allowed_ports=[443],
)

💉 Framework Vaccination (V0.3.0)

Secure existing code without changing a single line:

from agent_airlock import vaccinate, STRICT_POLICY

# Before: Your existing LangChain tools are unprotected
vaccinate("langchain", policy=STRICT_POLICY)

# After: ALL @tool decorators now include Airlock security
# No code changes required!

Supported: LangChain, OpenAI Agents SDK, PydanticAI, CrewAI

⚡ Circuit Breaker (V0.4.0)

Prevent cascading failures with fault tolerance:

from agent_airlock import CircuitBreaker, AGGRESSIVE_BREAKER

breaker = CircuitBreaker("external_api", config=AGGRESSIVE_BREAKER)

@breaker
def call_external_api(query: str) -> dict:
    return external_service.query(query)

# After 5 failures → circuit OPENS → fast-fails for 30s
# Then HALF_OPEN → allows 1 test request → recovers or reopens

📈 OpenTelemetry Observability (V0.4.0)

Enterprise-grade monitoring:

from agent_airlock import configure_observability, observe

configure_observability(
    service_name="my-agent",
    otlp_endpoint="http://otel-collector:4317",
)

@observe(name="critical_operation")
def process_data(data: dict) -> dict:
    # Automatic span creation, metrics, and audit logging
    return transform(data)

▶️ Runnable examples

No API key, no network, no framework install — every one of these runs offline and deterministically against the installed package. Verified 2026-08-19.

Framework-specific examples (LangChain, CrewAI, PydanticAI, …) need their framework installed and are listed in the compatibility table below.

🔌 Framework Compatibility

The Golden Rule: @Airlock must be closest to the function definition.

@framework_decorator    # ← Framework sees secured function
@Airlock()             # ← Security layer (innermost)
def my_function():     # ← Your code

from langchain_core.tools import tool
from agent_airlock import Airlock

@tool
@Airlock()
def search(query: str) -> str:
    """Search for information."""
    return f"Results for: {query}"

from agents import function_tool
from agent_airlock import Airlock

@function_tool
@Airlock()
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Weather in {city}: 22°C"

from pydantic_ai import Agent
from agent_airlock import Airlock

@Airlock()
def get_stock(symbol: str) -> str:
    return f"Stock {symbol}: $150"

agent = Agent("openai:gpt-4o", tools=[get_stock])

from crewai.tools import tool
from agent_airlock import Airlock

@tool
@Airlock()
def search_docs(query: str) -> str:
    """Search internal docs."""
    return f"Found 5 docs for: {query}"

from llama_index.core.tools import FunctionTool
from agent_airlock import Airlock

@Airlock()
def calculate(expression: str) -> int:
    return eval(expression, {"__builtins__": {}})

calc_tool = FunctionTool.from_defaults(fn=calculate)

from autogen import ConversableAgent
from agent_airlock import Airlock

@Airlock()
def analyze_data(dataset: str) -> str:
    return f"Analysis of {dataset}: mean=42.5"

assistant = ConversableAgent(name="analyst", llm_config={"model": "gpt-4o"})
assistant.register_for_llm()(analyze_data)

from smolagents import tool
from agent_airlock import Airlock

@tool
@Airlock(sandbox=True)
def run_code(code: str) -> str:
    """Execute in E2B sandbox."""
    exec(code)
    return "Executed"

from agent_airlock import Airlock

@Airlock()
def get_weather(city: str) -> str:
    return f"Weather in {city}: 22°C"

# Use in tool handler
def handle_tool_call(name, inputs):
    if name == "get_weather":
        return get_weather(**inputs)  # Airlock validates

Adapter-shipped vs example-only (honest split)

Both paths use the same @Airlock() decorator placement. "Adapter-shipped" means there's a dedicated src/agent_airlock/integrations/<framework>.py module with framework-specific glue (signature preservation, tool registry rewrites, request-shape adapters). "Example-only" means the decorator is compatible out of the box — no extra adapter required.

Adapter-shipped (11): LangChain (integrations/langchain.py), LangGraph (integrations/langgraph_toolnode_compat.py), OpenAI Agents SDK (integrations/openai_guardrails.py), Anthropic Messages API (integrations/anthropic.py), Anthropic Claude Agent SDK (integrations/anthropic_claude_agent_sdk.py, v0.6.1+), smolagents (integrations/smolagents_wrapper.py), Gemini 3 Agent Mode (integrations/gemini3_tool_shape_adapter.py), GPT-5.5 (integrations/gpt5_5_tool_shape_adapter.py), PydanticAI (integrations/pydantic_ai.py, v0.7.1+), CrewAI (integrations/crewai.py, v0.7.2+), FastMCP (agent_airlock/mcp/).

Example-only (2): AutoGen, LlamaIndex — decorator-compatible without an adapter; see examples/.

Complete Examples

⚡ FastMCP Integration

from fastmcp import FastMCP
from agent_airlock.mcp import secure_tool, STRICT_POLICY

mcp = FastMCP("production-server")

@secure_tool(mcp, policy=STRICT_POLICY)
def delete_user(user_id: str) -> dict:
    """One decorator: MCP registration + Airlock protection."""
    return db.users.delete(user_id)

🏆 Why Not Enterprise Vendors?

On the competitor columns. They are read off each vendor's public materials, not from testing their products, and the two vendor columns are the weakest rows on this page — treat them as a sketch of the category, not as a measurement. A previous version of this table asserted "$50K+/year" for Prompt Security with no source. Neither vendor publishes list pricing (Prompt Security is now part of SentinelOne and is quote-only), so that figure has been removed rather than re-sourced: it was not something this repo could stand behind if asked.

We're not anti-enterprise. We're anti-gatekeeping. Security for AI agents shouldn't require a procurement process.

📦 Installation

# Core (validation + policies + sanitization)
pip install agent-airlock

# With E2B sandbox support
pip install agent-airlock[sandbox]

# With FastMCP integration
pip install agent-airlock[mcp]

# Everything
pip install agent-airlock[all]

# E2B key for sandbox execution
export E2B_API_KEY="your-key-here"

🛡️ OWASP Compliance

Agent-Airlock maps to the OWASP Top 10 for Agentic Applications (2026) — the agentic-era successor to the old LLM Top 10. Coverage is reported honestly: Full means the primitive ships and blocks the class in tests; Partial means agent-airlock covers the runtime leg but something upstream (client UI, IAM, training data) is out of scope; Monitor-only means we surface the signal but do not actually prevent the risk.

Where the boundary sits. agent-airlock validates the payload of a tool call the agent is about to make — an in-process contract layer at the execution seam. A supply-chain compromise that lands before any tool call exists (a poisoned package, config file, or IDE task on disk) is a different layer: covered build / CI / IDE-time by the sibling scanner agent-audit-kit, not at airlock's runtime seam. The ASI04 row spells out which half is which.

MCP-specific mapping

The OWASP MCP Top 10 (2026 beta) maps to agent-airlock as follows. The OWASP_MCP_TOP_10_2026 policy preset is the policy layer — it supplies the deny-by-default controls for MCP02–MCP05 and part of MCP07; the other categories are covered by the named modules and presets alongside it, so this is not end-to-end coverage from one preset. The Status column is this repo's own assessment: Full = a dedicated control ships and is tested; Partial = a meaningful control ships but full mitigation still needs operator configuration or server-side auth that Airlock cannot supply in-process.

On the 2026-07-28-tagged guards below: MCP 2026-07-28 is the current ratified revision — /specification/latest 307-redirects to /specification/2026-07-28 and the release is prerelease: false (verified 2026-08-01). airlock accepts both 2026-07-28 (current) and 2025-11-25 (legacy) on the wire. These guards are validators and forward-compatible hardening. The first conformance run against 2026-07-28 is now published at benchmarks/mcp_conformance/RESULTS.md: airlock's transport surface passes 18/18 normative-contract cases, with three divergence probes listed as-is. It is not a full MCP server/client conformance pass, because airlock is a request validator, not a server, so the official suite's server/client scenarios have no endpoint to drive.

Use it directly:

from agent_airlock import Airlock
from agent_airlock.policy_presets import owasp_mcp_top_10_2026_policy

@Airlock(policy=owasp_mcp_top_10_2026_policy())
def my_mcp_tool(...):
    ...

Ox Security STDIO advisory (2026-04-16, CVE-2026-30616): see docs/cves/index.md#cve-2026-30616 and the stdio_guard_ox_defaults() preset above. agent-airlock blocks 3 of 4 Ox attack classes at the runtime seam.

🔗 Related work by the same author

Neither of these uses agent-airlock, and this section is not an adoption claim. They are listed because one of them will come up if you search, and because a previous version of this README wrongly listed both under a "Used By" heading. There are no known production users to name; when there are, they will be named here with a link to the integration.

• FerrumDeck — a Rust enforcement plane for AI agents. It contains a module also called Airlock (fd_policy::airlock, a runtime RASP inspection layer in rust/crates/fd-policy/). It shares the name and no code with this project — different language, different repository, no dependency in either direction. If you grepped FerrumDeck for "airlock" and found 117 files, that is what you found; a grep for agent_airlock or agent-airlock there returns nothing.
• Mnemo — an MCP-native memory database. It does not reference this library at all. The mnemo.checkpoint string that appears in the HandleField examples elsewhere in these docs is an illustrative MCP tool name, not an integration.

📊 Performance

Test count and coverage are published by the TEST-BADGE block at the top of this file, regenerated from pytest on every release via python scripts/update_test_badge.py. That block is the source of truth; this table tracks latency and surface area only.

Every latency figure below states what it measures, because the three that were previously in this table did not and disagreed by four orders of magnitude. A <50ms "validation overhead" row sat next to a benchmark table claiming p50 ~2µs; nothing in the repo measured the 50ms, so it has been deleted rather than explained.

The two decision-path numbers differ by ~50× because they measure different things and now say so: 1.5µs is the verdict, 80µs is the verdict plus everything the decorator does around it. The sandbox row is an order-of-magnitude larger than both and belongs to a different component entirely — reach for sandbox=True when isolation is worth ~125ms, not for validation.

The former "Sandbox warm pool <200ms" row is gone too. sandbox.py describes <200ms as a target, no benchmark measures it, and a warm-pool figure larger than the cold-start figure it exists to avoid is incoherent on its face.

📖 Documentation

Full docs — guides, API reference, the CVE catalog, and the OWASP coverage matrix — are hosted at sattyamjjain.github.io/agent-airlock (built from docs/ on every push to main).

Regulatory engagement

• Public comment draft — NIST AI RMF v2.0 Agentic-AI Security — drafted, never submitted (window 2026-04-18 → ~2026-06-06 closed without submission)

👤 About

Built by Sattyam Jain — AI infrastructure engineer.

This started as an internal tool after watching an agent hallucinate its way through a production database. Now it's yours.

🤝 Contributing

We review every PR within 48 hours.

git clone https://github.com/sattyamjjain/agent-airlock
cd agent-airlock
pip install -e ".[dev]"
pytest tests/ -v

• Bug? Open an issue
• Feature idea? Start a discussion
• Want to contribute? See open issues
• Where this is going? ROADMAP.md — the Now / Next / Later list, built from the caveats this README states about itself and tracked as roadmap issues

💖 Support

If Agent-Airlock saved your production database:

• ⭐ Star this repo — Helps others discover it
• 🐛 Report bugs — Open an issue
• 📣 Spread the word — Tweet, blog, share

⭐ Star History