ssrf-prevention

SSRF Prevention

Rules (for AI agents)

ALWAYS

• Constrain the destination with an allowlist of hosts you intend to reach, not a denylist of addresses you intend to avoid. A denylist has to enumerate every spelling of every internal address — decimal and octal IPv4, IPv6 and IPv4-mapped IPv6, a hostname whose A record is private, a public wildcard resolver like nip.io that encodes any address into a name — and it only has to be wrong once.
• Know which of the two controls you built, because it decides whether re-resolution matters. An allowlist of hostnames survives DNS rebinding: the attacker controls DNS only for names they own, and those names are not on the list. An IP-range check does not: the name resolves to a public address when you validate and a private one when you connect, and the two resolutions are independent. If your control is address-based, resolve once and connect to that pinned address — a custom dialer or transport, carrying the original hostname for SNI and Host — so no second lookup can occur.
• Re-validate at every redirect hop, or disable redirect-following entirely on fetchers that take user-supplied URLs. An allowed host answering 302 to http://169.254.169.254/ is the single most common bypass, and it defeats a check performed only on the URL the user submitted.
• Restrict the scheme to http and https before anything else. file://, gopher://, dict://, ldap://, jar:// and friends turn a fetcher into a file reader or a protocol-smuggling primitive.
• Keep the user-URL fetcher and the internal fetcher as separate clients, and make mixing them fail to compile rather than fail at runtime — distinct types in Go, Rust or TypeScript. A single client used for both eventually gets called with the wrong argument.
• Treat a parser as a fetcher. XML entity resolution, SVG with external references, HTML-to-PDF renderers, Markdown image embedding, oEmbed and link-preview unfurlers, and office-document converters all issue outbound requests from URLs inside the document, using no code you wrote. deserialization-security owns disabling external entities; what belongs here is that the request those parsers make is a server-side fetch and needs the same allowlist and the same egress policy.
• Decide what the response may reveal. Returning the body, the status code, the redirect chain, the content type, or the elapsed time to the caller turns a blind SSRF into a readable one. Return a fixed error on failure and never echo the URL or the fetch error back — error-handling-security owns the shape of that response.
• Enforce IMDSv2 on EC2 (session token required, hop limit 1) so a plain GET from a compromised process cannot read instance credentials, and give the workload its own identity so the metadata service is not a credential worth reaching. Endpoints for each cloud, and the egress rules that go with them, are in references/metadata-and-egress.md.