# Agent Egress Guard (free edition)

Page-level egress policy for AI agents. Before an agent's request leaves, Egress Guard decides whether it may be sent:
reads pass, while logins, sign-ups, password resets, cloud metadata addresses and every write the policy does not
recognise are denied.

- Runs locally, standard library only, no network calls (unless you add an API key for the page-type database).
- Hooks for `requests`, `httpx`, Playwright (sync and async) and mitmproxy, plus a command-line tool.
- Same evaluation code as the AI Agent Allowlist service: with the licensed rule files loaded it returns identical
  verdicts (checked on 726,018 real URL and method pairs).
- Apache License 2.0. Free for commercial use.

Home page and documentation: https://www.aiagentallowlist.com/egress-guard/

## Install

```
python3 -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install https://www.aiagentallowlist.com/egress-guard/agent_egress_guard-0.1.0-py3-none-any.whl
```

## Try it

```
agent-egress-guard check https://example.com/login -X POST
agent-egress-guard check https://docs.python.org/3/
agent-egress-guard replay
```

`replay` runs 24 representative requests reconstructed from public 2026 AI-agent incident disclosures and shows which ones
your policy stops. The free edition denies 15 of the 18 steps that the full policy denies; the other 3 are wiki edits
sent as plain GET requests, which only the full rule set recognises.

## Per-agent policy files (new in 0.2.0)

Give each agent its own policy: which page types it may open, which domains are always allowed or denied, whether
unclassified destinations are denied, and narrow exceptions (one page type, one domain, an end date).

```
agent-egress-guard policy init --agent vendor-research --owner procurement-lead --tier 3 > vendor-research.json
agent-egress-guard policy validate vendor-research.json
agent-egress-guard policy check vendor-research.json https://example.com/login -X POST
```

```python
from agent_egress_guard import Guard, AgentPolicy

policy = AgentPolicy.load("vendor-research.json")
v = policy.check(Guard(), "https://example.com/start-trial")
v.decision          # "allow", "deny" or "approval_required"
```

Build a policy in the browser: https://www.aiagentallowlist.com/tools/agent-policy-builder.php

## In Python

```python
from agent_egress_guard import Guard

guard = Guard()
v = guard.check("https://example.com/wp-login.php", "POST")
print(v.decision, v.layer, v.rule)      # deny rules login
```

requests (`pip install requests`):

```python
import requests
from agent_egress_guard import guard_requests, EgressDenied

session = guard_requests(requests.Session())
try:
    session.post("https://example.com/login", data={"user": "agent"})
except EgressDenied as e:
    print("blocked:", e.verdict.rule)
```

httpx (`pip install httpx`):

```python
import httpx
from agent_egress_guard import httpx_hook

client = httpx.Client(event_hooks={"request": [httpx_hook()]})
```

Playwright (browser agents; `pip install playwright` and `python -m playwright install chromium`):

```python
from playwright.sync_api import sync_playwright
from agent_egress_guard import guard_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context()
    guard_playwright(context)          # denied requests are aborted
    page = context.new_page()
    page.goto("https://example.com/")
```

mitmproxy (put any agent or container behind the policy; current mitmproxy needs Python 3.12 or newer):

```
pip install mitmproxy
mitmdump -s "$(agent-egress-guard mitm-script)"
```

## How a request is decided

1. **Host list**: hosts denied or flagged whatever the page. Free: the cloud metadata addresses (169.254.169.254 in any
   notation, metadata.google.internal).
2. **Page-type database**: the domain's verified login, sign-up, checkout, upload and read pages. Needs an API key.
3. **URL rules**: patterns that recognise risky endpoints on any domain. Free: login, sign-up, password reset.
4. **Default**: GET and HEAD pass, every other method is denied.

URLs are normalised the way servers read them before any check (percent-encoded letters, `;jsessionid` path parameters,
numeric and hexadecimal IP addresses, trailing dots), so the usual encoding tricks do not get around the rules.

## Free and full edition

| | Free | Full |
|---|---|---|
| URL rules | 3 | 40 (checkout, payment, uploads, repository writes, package publishing, wiki edits, admin panels, CI/CD...) |
| Host list | 2 | 62 (cloud consoles, package registries, paste sites, deployment APIs, webhook sinks...) |
| Page-type database | no | 40.8 million domains with verified page URLs |
| Incident replay | 15 of 18 denied | 18 of 18 denied |

URL rules alone recognise fewer than half of real login pages (many sit on paths such as `/account` or `/mon-compte`);
the page-type database identifies them per domain. Load the full edition with the same code:

```python
Guard(rules_path="page_type_rules.jsonl", hosts_path="high_value_hosts.csv", api_key="YOUR_API_KEY")
```

Details and plans: https://www.aiagentallowlist.com/egress-guard/#full

## Licence

Apache License 2.0, see `LICENSE` and `NOTICE`. Copyright 2026 Alpha Quantum.