SSRF filters and the IPv6 transition-address bypass
Why IP allow/deny lists keep failing, the common SSRF bypass encodings, and a transition-address class that most SSRF guards still miss.
Start here: what SSRF actually is
Server-Side Request Forgery is the bug where your server makes an HTTP request to an address the attacker chose. The classic payoff is the cloud metadata endpoint (http://169.254.169.254/…), which on AWS, GCP and Azure hands back short-lived IAM credentials to anyone who can make the box ask for them. If an attacker can reach it, a feature that fetches a URL turns into access to your cloud account.
Most developers who have heard of SSRF will tell you the fix: block the internal ranges. Deny 127.0.0.0/8, 10.0.0.0/8, 169.254.0.0/16, ::1, and you’re done.
That is not enough. An SSRF filter is only as good as the IP parser behind it, and that parser is where most of this bug class lives.
The misconception
The mental model that fails is: “I have a list of forbidden IPs; I check the host against the list.” The problem is that one internal IP has many spellings. The attacker picks a spelling your parser doesn’t recognise, and the kernel or network stack still routes it to the forbidden destination.
A non-exhaustive list of “same address, different spelling”:
- Alternate IPv4 encodings:
2130706433(decimal),0x7f000001(hex),017700000001(octal),127.1(short form). Many URL parsers andinet_atonresolve these to127.0.0.1. - IPv4-mapped IPv6:
::ffff:169.254.169.254, the same v4 address written as v6. - The 0.0.0.0 trick, enclosed-alphanumeric hosts, and uppercase or trailing-dot hostnames.
- DNS rebinding: the hostname resolves to a public IP when you validate, then to
127.0.0.1when you connect (the two resolutions are different). This defeats filters that check the name instead of pinning the connected IP. - Redirects: you validate
https://safe.example/, it returns a302tohttp://169.254.169.254/, and the follow-up request is never re-checked.
Defenders eventually learn most of these. The one that is still widely missed, and the focus of this post, is IPv6 transition addresses that embed an IPv4 address.
The variant most guards miss: IPv4-in-IPv6 transition forms
IPv6 has several formats that carry an IPv4 address inside a v6 address so that v6-only networks can still reach v4 destinations:
| Form | Prefix | Example that embeds 169.254.169.254 |
|---|---|---|
| IPv4-mapped | ::ffff:0:0/96 |
::ffff:169.254.169.254 |
| NAT64 (well-known) | 64:ff9b::/96 (RFC 6052) |
64:ff9b::a9fe:a9fe |
| NAT64 (local-use) | 64:ff9b:1::/48 (RFC 8215) |
64:ff9b:1:a9fe:a9:fe00:: (/48 layout; the offset depends on the deployed prefix length) |
| 6to4 | 2002::/16 (RFC 3056) |
2002:a9fe:a9fe::1 |
| Teredo | 2001::/32 (RFC 4380) |
2001:0:0:0:0:0:5601:5601 |
| IPv4-compatible (deprecated) | ::/96 |
::a9fe:a9fe |
This is where the bug comes from. Almost every SSRF guard that handles IPv6 at all decodes exactly one of these forms, IPv4-mapped, because the standard library makes it a one-liner (ip.ipv4_mapped). It then runs the private/metadata check. The other forms are left as raw IPv6 addresses, and:
ipaddress.ip_address("64:ff9b::a9fe:a9fe").is_globalreturnsTrue, and.is_privatereturnsFalse.
Python does not know that 64:ff9b::a9fe:a9fe stands for 169.254.169.254. It is not in anyone’s BLOCKED_NETWORKS. It is not loopback, not link-local, not private. So the guard says allowed and the server connects. The same is true of 6to4 (2002::/16) and IPv4-compatible (::/96) addresses on Python 3.11. Teredo is the exception: 2001::/32 already reports is_global == False, so a guard that rejects non-global addresses catches it, while a guard built on an explicit blocklist does not. (These results are from Python 3.11. Newer releases (3.12.4+, 3.13) updated the special-purpose address tables, so 6to4 and the local-use NAT64 prefix 64:ff9b:1::/48 may already be reported as non-global there. The well-known NAT64 prefix 64:ff9b::/96 is globally routable per IANA and stays is_global == True on every version, so the core bypass holds regardless. Test on the Python you actually ship.)
The filter approves the address because it cannot see the internal IP inside it.
When does the connection actually arrive?
The filter gap is unconditional. Whether the packet reaches the embedded IPv4 depends on the network:
- NAT64 with a local-use or network-specific prefix (RFC 8215, or any operator-chosen prefix) translates to whatever IPv4 the operator routes, including RFC 1918 ranges. This is the realistic case: an internal service on
10.xreached from an IPv6-only workload. - The well-known prefix
64:ff9b::/96is not supposed to carry non-global IPv4 addresses (RFC 6052 §3.1). A compliant translator drops them; a permissive one does not. - Loopback and link-local targets (
127.0.0.1,169.254.169.254) are delivered from the translator’s point of view, not the server’s.64:ff9b::7f00:1does not reach the vulnerable host’s own loopback, and whether the metadata address is reachable depends on where the translator sits. - 6to4 and Teredo need a relay or tunnel interface on the path.
So treat this as a filter bypass whose impact depends on egress. Confirm the translation path in the target environment before claiming metadata access.
What this looks like in real code
The vulnerable shape is small and repeats across codebases:
def _normalize(ip):
if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
return ip.ipv4_mapped # <-- only ::ffff:a.b.c.d is decoded
return ip
def is_blocked(ip):
ip = _normalize(ip)
return ip.is_private or ip in BLOCKED_NETWORKS # 64:ff9b::… sails straight throughA public example: mcp-atlassian, an MCP server that bridges AI clients to Jira and Confluence, had this guard. It unwrapped ipv4_mapped, checked is_global, and let NAT64 addresses through. It was fixed in 0.24.1 (GHSA-85p8-f4j5-j5jp); I am credited on that advisory together with another reporter. The mistake is the same wherever it appears: one transition form decoded, the rest trusted.
The fix
Decode the embedded IPv4 from every transition form before the block check, in one shared helper, then run the private/metadata test on the extracted IPv4:
if ip.ipv4_mapped is not None: ip = ip.ipv4_mapped
elif ip.sixtofour is not None: ip = ip.sixtofour
elif ip.teredo is not None: ip = ip.teredo[1] # client address; also check ip.teredo[0] (server)
elif ip in NAT64_WELL_KNOWN: ip = IPv4Address(ip.packed[12:16])
# NAT64 local-use 64:ff9b:1::/48: decode all RFC 6052 §2.2 candidate offsets (/48,/56,/64,/96),
# ignoring the u-octet and suffix bits, because real translators (e.g. Jool) do.As defense in depth, reject any IPv6 for which not ip.is_global. That check alone is not sufficient, because is_global reports NAT64, 6to4 and IPv4-compatible addresses as global. You still have to extract and check the embedded IPv4.
Testing for it
If you write SSRF protection, test your guard with the table above, not just 127.0.0.1 and 169.254.169.254. Your IP parser probably has a blind spot.
If you hunt bugs, grep for ipv4_mapped next to is_private / is_global in any outbound-fetch guard. Where NAT64, 6to4 and Teredo handling is absent, you probably have a filter bypass. Then check the egress path: NAT64 is common in IPv6-only cloud networking, and whether the bypass reaches an internal target depends on how that translator is configured.
Takeaway
Your SSRF blocklist is only as good as the IP parser in front of it.
Decode the IPv4 embedded in every transition form (NAT64, 6to4, Teredo, IPv4-compatible) before the block check, and test with those spellings.