pantheon-ssrf-guard

A small, dependency-free SSRF egress guard for Python's standard-library HTTP client — one that survives DNS rebinding.

The guarantee: an outbound request cannot reach a private, loopback, link-local, cloud-metadata, or CGN address — even if the hostname resolves public at check time and rebinds to an internal IP before the socket connects.

Extracted from PANTHEON, a multi-tenant AI substrate, where it is the single canonical guard on every outbound path (link imports, uploaded-URL fetches, external MCP-server transports).

Why a pre-check isn't enough

The common "block internal hosts" approach resolves the hostname and rejects private IPs before connecting. An attacker defeats it with DNS rebinding: the name resolves to a public IP when you check it, then to 127.0.0.1 / 169.254.169.254 (cloud metadata) / an internal service by the time the socket actually opens.

pantheon-ssrf-guard uses two layers:

1. host_is_public(host) — the fast pre-check: reject if any resolved address is non-public.
2. GuardedHTTP(S)Connection — at connect time, re-check the IP the socket actually reached. This is the layer a pre-check can't provide, and it's what closes the rebind window.

The classifier's catch-all is not ip.is_global, so it also rejects everything the obvious flags miss — RFC 6598 shared/CGN space (100.64.0.0/10, used by Kubernetes/internal load balancers and the Alibaba/Tencent/Oracle metadata endpoint 100.100.100.200), plus benchmark, documentation, and NAT64 ranges.

Install

pip install pantheon-ssrf-guard   # or: copy the single ssrf_guard.py file into your project

Use

from ssrf_guard import guarded_opener, SsrfBlocked

opener = guarded_opener()          # https-capable; redirects refused by default (each hop re-checked if allowed)

try:
    with opener.open("https://example.com/data.json", timeout=10) as resp:
        body = resp.read()
except SsrfBlocked:
    ...   # the target resolved (or rebound) to a non-public address — refused before any data was sent

Lower-level pieces are exported too if you're building your own client:

from ssrf_guard import host_is_public, ip_is_public, peer_is_public
from ssrf_guard import GuardedHTTPHandler, GuardedHTTPSHandler

What it does not do

• It doesn't proxy, cache, or rate-limit — it only refuses non-public destinations.
• It guards urllib/http.client. For httpx/requests you'd apply the same idea at their transport layer (the classification functions here are reusable).
• It is not a WAF; it's the one specific control that stops server-side request forgery to internal infrastructure.
• Under DNS rebinding, a TLS handshake can reach the internal host before the peer check fires. For an ordinary private target (http://127.0.0.1, https://192.168.1.1, 169.254.169.254) nothing is attempted at all — the name check refuses before a socket exists, and the test suite asserts that no socket.create_connection occurs. But if a public name resolves to a private address after that check, connect() completes the TCP+TLS handshake and the peer check refuses immediately afterwards. No request bytes are written and no response is read, so the attacker gets a handshake with an internal service, not a request to it. Eliminating even the handshake requires resolving the name yourself and connecting to a pinned IP — a different design, and one that breaks TLS hostname validation unless done carefully.

Changelog

• 0.2.0 — scheme allowlist at the opener boundary and environment proxies off by default, after an external review reproduced two bypasses: build_opener() also installs file:/ftp:/data: handlers, so opener.open("file:///etc/passwd") read a local file without the HTTP guard ever running; and a ProxyHandler inherited from HTTP(S)_PROXY moves the connection to the proxy, so the peer check validated the proxy while the real destination went unexamined. Now only http/https are reachable (enforced per-hop, so a redirect to ftp: is refused too), the dangerous handlers are removed from the opener entirely, and ProxyHandler({}) is installed unless the caller passes trust_env_proxy=True. Also documents the DNS-rebinding handshake residue above, with tests pinning it.

• 0.1.1 — the pre-check is now wired into the opener (so "two-layer" is true, not aspirational): a GuardedHTTP(S)Connection rejects a non-public host by name BEFORE opening the socket, then re-checks the actual peer at connect time (the rebind guard). And IPv4-mapped (::ffff:…) + NAT64 (64:ff9b::/96) addresses are normalised to their embedded v4 before classifying, so an internal target smuggled inside a v6 address is blocked version-independently instead of trusting whichever is_* flags a given CPython sets.

• 0.1.0 — initial release.

License

Apache-2.0. See LICENSE.