fix(proxy): judge NAT64 upstream addresses by their embedded IPv4

On a DNS64 network an IPv4-only host also resolves to a synthesized
64:ff9b::<ipv4> address. `ipaddress` flags the whole 64:ff9b::/96 prefix
as reserved (it sits in ::/8), so _is_internal_address rejected it before
the NAT64 branch added in #3195 could look at the embedded IPv4. That
branch was unreachable, and every IPv4-only client-supplied upstream was
judged unsafe there. The OpenAI handler then ignored x-headroom-base-url
and sent the request, with the gateway's key, to the configured upstream.

Unwrap the well-known prefix before the category checks and judge the
embedded IPv4 by the same rules, so 64:ff9b::7f00:1 stays blocked and
64:ff9b::808:808 is allowed. The local-use prefix (64:ff9b:1::/48) is
left rejected as non-global, as it already was in practice: where its
IPv4 bits sit depends on the operator's prefix length.
This commit is contained in:
Ayushraj06-bit
2026-10-13 18:48:07 +05:30
parent 0126fba63f
commit 7decb0670e
2 changed files with 58 additions and 15 deletions
+16 -14
View File
@@ -256,19 +256,21 @@ def destination_listed(
return (scheme, host.lower(), port) in origins
# RFC 6052 / RFC 8215: these IPv6 prefixes embed an IPv4 address in their low
# 32 bits, and `ipaddress` reports the well-known one as globally routable. On a
# NAT64 network `64:ff9b::7f00:1` reaches 127.0.0.1, so the embedded address is
# what has to be judged. 6to4, Teredo and IPv4-mapped forms are already caught
# by the `is_global` test below.
_NAT64_PREFIXES = (
ipaddress.IPv6Network("64:ff9b::/96"),
ipaddress.IPv6Network("64:ff9b:1::/48"),
)
# RFC 6052 well-known prefix. A DNS64 resolver answers a host that has only an
# A record with `64:ff9b::<its IPv4>`, and the NAT64 translator delivers that to
# the IPv4 address in the low 32 bits, so the embedded address is what has to
# be judged: `64:ff9b::7f00:1` reaches 127.0.0.1. It has to be judged *before*
# the category checks, because `ipaddress` calls the whole prefix reserved (it
# sits in ::/8) -- judging the IPv6 form rejected every IPv4-only upstream on a
# DNS64 network. The local-use prefix (RFC 8215, 64:ff9b:1::/48) is not
# unwrapped: where its IPv4 bits sit depends on the operator's prefix length,
# so it stays rejected as non-global. 6to4, Teredo and IPv4-mapped forms are
# already caught by the `is_global` test below.
_NAT64_WELL_KNOWN_PREFIX = ipaddress.IPv6Network("64:ff9b::/96")
def _nat64_embedded_ipv4(addr: ipaddress.IPv6Address) -> ipaddress.IPv4Address | None:
if not any(addr in prefix for prefix in _NAT64_PREFIXES):
if addr not in _NAT64_WELL_KNOWN_PREFIX:
return None
try:
return ipaddress.IPv4Address(int(addr) & 0xFFFFFFFF)
@@ -281,6 +283,10 @@ def _is_internal_address(ip: str) -> bool:
addr = ipaddress.ip_address(ip)
except ValueError:
return True # unparseable (e.g. scoped link-local) -> treat as unsafe
if isinstance(addr, ipaddress.IPv6Address):
embedded = _nat64_embedded_ipv4(addr)
if embedded is not None:
return _is_internal_address(str(embedded))
if (
addr.is_private
or addr.is_loopback
@@ -298,10 +304,6 @@ def _is_internal_address(ip: str) -> bool:
# learns about.
if not addr.is_global:
return True
if isinstance(addr, ipaddress.IPv6Address):
embedded = _nat64_embedded_ipv4(addr)
if embedded is not None and _is_internal_address(str(embedded)):
return True
return False
+42 -1
View File
@@ -42,7 +42,16 @@ def test_blocks_internal_and_invalid(url: str) -> None:
assert is_safe_upstream_url(url) is False
@pytest.mark.parametrize("url", ["https://8.8.8.8/v1", "https://1.1.1.1/", "wss://9.9.9.9/rt"])
@pytest.mark.parametrize(
"url",
[
"https://8.8.8.8/v1",
"https://1.1.1.1/",
"wss://9.9.9.9/rt",
# NAT64 well-known prefix embedding 8.8.8.8: the translator delivers it there.
"https://[64:ff9b::808:808]/v1",
],
)
def test_allows_public(url: str) -> None:
assert is_safe_upstream_url(url) is True
@@ -63,7 +72,12 @@ def test_allows_public(url: str) -> None:
("6to4 embedding loopback", "http://[2002:7f00:1::]/"),
("6to4 embedding RFC1918", "http://[2002:a00:1::]/"),
("NAT64 embedding loopback", "http://[64:ff9b::7f00:1]/"),
("NAT64 embedding RFC1918", "http://[64:ff9b::a00:1]/"),
("NAT64 embedding metadata", "http://[64:ff9b::a9fe:a9fe]/"),
("NAT64 local-use prefix", "http://[64:ff9b:1::7f00:1]/"),
# Local-use embedding depends on the operator's prefix length, so the
# low 32 bits are not reliably the destination: never unwrapped.
("NAT64 local-use prefix embedding a public IPv4", "http://[64:ff9b:1::808:808]/"),
("teredo", "http://[2001:0::7f00:1]/"),
("IPv4-mapped metadata", "http://[::ffff:169.254.169.254]/"),
("IPv4-mapped loopback", "http://[::ffff:127.0.0.1]/"),
@@ -582,6 +596,33 @@ def test_a_check_pins_every_address_it_accepted(monkeypatch: pytest.MonkeyPatch)
assert upstream_guard.validated_addresses("multi.homed.example") == ("8.8.8.8", "1.1.1.1")
def test_a_dns64_answer_for_a_public_host_is_accepted_and_pinned(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""On a DNS64 network an IPv4-only host also gets a synthesized `64:ff9b::` AAAA.
Judging that AAAA as reserved rejected every IPv4-only upstream there, and
the OpenAI handler then sent the request -- key included -- to the
configured upstream instead.
"""
from headroom.proxy import upstream_guard
def dns64_answer(*args: object, **kwargs: object) -> list[object]:
return [
(None, None, None, None, ("8.8.8.8", 443)),
(None, None, None, None, ("64:ff9b::808:808", 443, 0, 0)),
]
monkeypatch.setattr(socket, "getaddrinfo", dns64_answer)
upstream_guard.clear_validated_addresses()
assert is_safe_upstream_url("https://ipv4-only.example/v1") is True
assert upstream_guard.validated_addresses("ipv4-only.example") == (
"8.8.8.8",
"64:ff9b::808:808",
)
def test_a_rejected_or_allowlisted_destination_pins_nothing(
monkeypatch: pytest.MonkeyPatch,
) -> None: