All posts
Concept ~5 min read

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 and inet_aton resolve these to 127.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.1 when 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 a 302 to http://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_global returns True, and .is_private returns False.

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.x reached from an IPv6-only workload.
  • The well-known prefix 64:ff9b::/96 is 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:1 does 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:

Python
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 through

A 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:

Python
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.