agent-policy-gateway
A policy-enforcement and information-flow-control (IFC) gateway for AI agent tool calls — a reference monitor that sits between the agent and its tools, enforces declarative YAML policies, tracks taint across calls, and writes an append-only audit log.
pip install agent-policy-gateway
Headline result. In a head-to-head measurement of defense paradigms on a
shared 90-scenario long-horizon prompt-injection family — Progent-style
stateless symbolic rules, Fides-style dual-label IFC, and this project's
session-taint, call-history, and per-value-taint policies, differing in
nothing but the policy file — every session-scoped defense trades utility
against compromise (the measured Pareto frontier), while the per-value taint
arm closes both residuals at once: 100% task utility with 0% compromise,
including the covert-exfiltration variants that are provably
indistinguishable at session scope. Full matrices, findings, and limits:
docs/benchmarks/comparison.md.
| arm | paradigm | utility | compromise |
|---|---|---|---|
no-defense |
bare runtime | 100% | 100% |
progent |
stateless symbolic rules (imported from real Progent JSON) | 80% | 60% |
fides |
dual-label IFC (integrity + confidentiality) | 60% | 40% |
apg-input-taint |
session taint label + declassify | 80% | 60% |
apg-chain |
session call history | 60% | 20% |
apg-chain-selective |
call history + argument conditions | 100% | 60% |
apg-value-taint |
per-value taint labels | 100% | 0% |
Deterministic, no API keys, no external services; every number is pinned by tests and regenerated by one command:
python -m agent_policy_gateway.comparison_benchmark
60-second demo
The classic indirect-prompt-injection exfiltration, run twice — once with a naive agent, once through the gateway:
git clone https://github.com/howardhsieh/agent-policy-gateway.git
cd agent-policy-gateway
pip install -e .
python -m examples.indirect_injection
Expected output:
naive: exfiltrated record 'launch-codes' (body='TOP-SECRET-LAUNCH-CODES-42') to attacker@evil.example
gated: refused by rule 'deny-web-to-email' — outbox empty, 3 audit record(s) written
Same agent, same injected web page, same tools — the only difference is that
the gated run's tool calls pass through the reference monitor, which sees
web-tainted content flowing toward an email sink and refuses.
Architecture
flowchart LR
Agent["LLM / agent<br/>(untrusted)"] -- "tool call" --> GW
subgraph GW["Policy Gateway — reference monitor"]
direction TB
Policy["Policy engine<br/>ordered YAML rules: tool / resource /<br/>argument, taint, per-arg value taint,<br/>call-history (chain) conditions"]
Taint["Taint tracking<br/>dual-label (integrity + confidentiality),<br/>session scope + per-value ledger,<br/>declarative declassify"]
History["Session call history<br/>(provenance for chain rules)"]
Audit["Append-only audit log<br/>(replay, diff, stats)"]
end
GW -- "allow / deny / review / redact" --> Tools["Tools<br/>MCP · OpenAI · Anthropic ·<br/>LangChain · AgentDojo"]
Tools -- "tainted output" --> GW
The gateway is outside the model's control surface: adversarial content can
reach the model through any tool output, and anything the model is asked to do
in its own defense is bypassable. Mediating the calls themselves makes the
guarantee structural rather than emergent. Details in
docs/design.md.
What it does
- Policy enforcement. Allow / deny / human-review / redact rules per
tool, resource, and argument — including regex argument conditions,
taint conditions at session and per-value scope, and chain rules over the
session's prior calls ("no
send_emailafter an unsanitizedweb_fetch"). Policies are declarative YAML, evaluated first-match, withexplain,lint, anddifftooling in theapgCLI. - Taint tracking. Tool outputs carry source labels on two dimensions (integrity and confidentiality). Labels join through subsequent calls at session scope and — since R57 — per value: a sink decision can see the label of the exact value flowing into each argument. Declassification is a vetted, operator-audited privilege, never something the LLM requests.
- Audit log. Every call, decision, and label is recorded append-only, with replay and diff tools for incident response and red-team review.
- Multi-protocol adapters. The same policy language mediates tool catalogs from MCP, OpenAI function calling, Anthropic tool use, LangChain, and the AgentDojo benchmark suite.
Prevent, detect, operate
APG is the prevention layer of an open agent-security stack. Every decision it makes lands in the audit log, and the audit log exports straight into the detection layer:
apg audit export audit.jsonl --format tracesig -o trace.jsonl
pip install tracesig
tracesig scan trace.jsonl # core + apg rule packs, chosen automatically
[CRIT] TS-EXF-001 — Untrusted web content followed by outbound email
session: denied-injection category: exfiltration
timeline:
#0 web_fetch {"url": "https://research.example/widgets"} labels=['untrusted', 'web'] verdict=allow
#2 send_email {"body": "record WID-7 contents", "subject": "requested data", "to": "attacker@e… labels=['untrusted', 'web'] verdict=deny
TraceSig's apg pack reads the gateway's own verdicts: repeated denials in a
session (an agent pushing against the policy), untrusted input reaching an
allowed sink (a policy gap), a blocked call followed by an allowed one (route
around the block), and declassifications. The pairing is pinned by a contract
test in CI (tests/test_tracesig_contract.py).
| Layer | Project |
|---|---|
| Prevent | agent-policy-gateway: policies and taint tracking in front of tool calls |
| Detect | TraceSig: Sigma-style rules over agent tool-call traces (APG exports, Claude Code sessions) |
| Operate | agent-security-skills: the agentsec-kit plugin grades a coding-agent setup A–F, audits skills before install, and guides incident response |
Threat model
The LLM is not trusted to decide what tool calls are safe. Adversarial
content reaches it via any tool output; the gateway is the trusted reference
monitor, and the model is policy-controlled, not policy-aware. Assets, trust
boundaries, adversary classes, canonical abuse scenarios mapped to shipped
mitigations, and residual risks: docs/threat-model.md.
Non-goals: not a content filter (this is about flow, not classifying text as harmful); not a sandbox for tool implementations; not a replacement for human review of high-stakes actions — it makes that review tractable.
Research & benchmarks
The whole measurement series, packaged as a self-contained
workshop-style draft with one reproducibility script per table:
docs/paper/.
The individual write-ups, in dependency order — all deterministic and
CI-reproducible, under docs/benchmarks/:
agentdojo.md— attack success rate and utility, no-defense vs APG policies, on real AgentDojo tasks and injections.stateful.md— the long-horizon stateful harness: attacker influence that persists and compounds across a session, and how a mid-session declassify launders an input-taint policy.comparison.md— the seven-arm APG / Progent / Fides comparison summarized above.model-loop.md— a driver, not a script, decides the calls: what policy refusals do to agent behavior, utility, and token spend.overhead.md— what mediation costs: the per-call ladder and scaling sweeps (~12 µs full mediation).tracesig-export.md— the versioned audit-trace export pairing APG (prevention) with the sibling TraceSig detection project:apg audit export --format tracesig, plus vendorable example traces underexamples/traces/.
What's next: ROADMAP.md.
Quick start (library API)
from agent_policy_gateway import Gateway, ToolTaintSpec, load_policy
gateway = Gateway(policies=[load_policy("policies/default.yaml")])
# A web-fetch tool — its output carries a `web` taint label.
@gateway.wrap_tool(tool_name="web_fetch", taint_spec=ToolTaintSpec.of(adds=("web",)))
def web_fetch(url: str) -> str:
...
# An email sink — policy resource matching is tied to the `to` argument.
@gateway.wrap_tool(tool_name="send_email", resource_arg="to")
def send_email(to: str, body: str) -> None:
...
# The agent calls the wrappers; the gateway enforces policy and tracks taint.
The full walkthrough (policy file, taint labels, the refusal, the audit
trail) is in docs/quickstart.md; example policies
live under policies/ and runnable demos under
examples/.
Documentation
The documentation site is built with mkdocs-material:
pip install -e ".[docs]"
mkdocs serve
Sources under docs/, configuration in mkdocs.yml;
start with docs/index.md.
Release
Releases are published to PyPI via the GitHub Actions workflow at
.github/workflows/publish.yml: pushing a
v* tag runs a test → build → publish pipeline that uploads the sdist +
wheel through PyPI's trusted-publisher OIDC flow — no long-lived API token
anywhere. The full procedure, manual fallback included, is in
docs/release.md.
Contributing
Built incrementally and in public. See ROADMAP.md for what's
next and docs/design.md for the architecture. Before
opening a PR, run the same gates CI does:
pip install -e ".[dev]"
ruff check .
mypy src/agent_policy_gateway
pytest
mypy enforces the typed-API guard over the py.typed package; its baseline
lives in the [tool.mypy] section of pyproject.toml.
License
Apache-2.0. See LICENSE.
Metadata
Release files for agent-policy-gateway 0.2.0
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_policy_gateway-0.2.0.tar.gz | 293.9 kB | With provenance | Details for agent_policy_gateway-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_policy_gateway-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for agent_policy_gateway-0.2.0-py3-none-any.whl |
Total release size: 466.6 kB
Release files / agent_policy_gateway-0.2.0.tar.gz
| Download URL | agent_policy_gateway-0.2.0.tar.gz |
|---|---|
| Size | 293.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
efa1a09f51ea018679e55df09b5e6ba08ddcd767d5e21c4da813a6e47a55bb64
|
|
BLAKE2b-256 checksum How to use checksums |
e8f0b6378d107b160b89ccd1330056cb068910de91ca551039c47aae64d121a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logRelease files / agent_policy_gateway-0.2.0-py3-none-any.whl
| Download URL | agent_policy_gateway-0.2.0-py3-none-any.whl |
|---|---|
| Size | 172.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aff1de7c7fdb7cd78608ce17360c7d2d88520565ba0d8c53bf98452b1dccdfac
|
|
BLAKE2b-256 checksum How to use checksums |
f0bb5f3ba2e3f906732c55e82a7c41c8ce1d4bc928fa8015addd89dd32eccdb3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logSecurity for agent-policy-gateway 0.2.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_policy_gateway-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.
Transparency logA 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.