Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

security: block IPv6 transition prefixes in SSRF defense (#3932)

LearningCircuit00745f7a47ee
diff --git a/SECURITY.md b/SECURITY.md
index d952c1b654..a8ee23ba89 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -150,8 +150,29 @@ Both `ssrf_validator.validate_url` and `NotificationURLValidator.validate_servic
| `169.254.0.23` | Tencent Cloud |
| `100.100.100.200` | AlibabaCloud |
+The block also catches IPv6-wrapped forms of these metadata IPs. When an IPv6 destination falls in a NAT64 prefix (`64:ff9b::/96` RFC 6052 well-known or `64:ff9b:1::/48` RFC 8215 local-use), the validator extracts the embedded IPv4 from the low 32 bits and matches it against this set — so `[64:ff9b::a9fe:a9fe]` cannot reach `169.254.169.254` even on a host with NAT64 routes configured. The check fires before any opt-in carve-out, so the operator switch described below cannot license IMDS exposure.
+
+Both `ssrf_validator.is_ip_blocked` and `NotificationURLValidator.validate_service_url` enforce this absolutely, including under `allow_private_ips=True`. The latter flag is an operator opt-in for self-hosted webhooks on internal networks (RFC1918, CGNAT, loopback, link-local, IPv6 ULA); it does NOT extend to metadata IPs or NAT64-wrapped metadata. Both validators delegate to the same `is_ip_blocked` helper to keep the absolute-block invariant in lockstep.
+
Future contributors must not remove entries from this set. Adding a new cloud provider's metadata IP is encouraged when a new public-cloud target appears.
+### IPv6 Transition Prefix Block List
+
+`PRIVATE_IP_RANGES` blocks four IPv6 prefixes that can wrap private-IPv4 destinations on hosts with kernel transition routes configured:
+
+| Prefix | Purpose | RFC |
+| --- | --- | --- |
+| `2002::/16` | 6to4 | RFC 3056 (deprecated by RFC 7526) |
+| `64:ff9b::/96` | NAT64 well-known prefix | RFC 6052 |
+| `64:ff9b:1::/48` | NAT64 local-use prefix | RFC 8215 |
+| `2001::/32` | Teredo | RFC 4380 |
+| `100::/64` | IPv6 discard prefix | RFC 6666 |
+| `::/96` | IPv4-Compatible IPv6 (deprecated) | RFC 4291 §2.5.5.1 |
+
+Default Linux has no `sit0` / NAT64 routes so this is defensive-only on the typical deployment, but blocking these prefixes closes the IPv6-wrapped SSRF bypass class on hosts where transition tunnels are enabled.
+
+Operators on IPv6-only deployments using DNS64+NAT64 (AWS / GKE / Azure IPv6-only nodes) reach IPv4 services through `64:ff9b::/96`. They can opt back into NAT64 reachability via the env-only setting `security.allow_nat64` (`LDR_SECURITY_ALLOW_NAT64=true`). The opt-in is scoped strictly to the two NAT64 prefixes — 6to4, Teredo, and discard remain unconditionally blocked because they have no live legitimate use, and the IMDS embedded-IPv4 check above still applies so cloud metadata stays unreachable through any NAT64 wrap.
+
URL rejection log lines route through `ssrf_validator.redact_url_for_log` to drop userinfo (RFC 3986 §3.2.1 allows credentials in the URL), path, and query — operators see `scheme://host:port` only. Operators with grep/regex tooling on the rejection log lines will see authority-only strings instead of full URLs.
## Supported Versions
diff --git a/changelog.d/+ipv6-transition-prefixes.security.md b/changelog.d/+ipv6-transition-prefixes.security.md
new file mode 100644
index 0000000000..4222a19145
--- /dev/null
+++ b/changelog.d/+ipv6-transition-prefixes.security.md
@@ -0,0 +1,25 @@
+SSRF defense-in-depth: block IPv6 transition prefixes that can wrap
+private IPv4 destinations on hosts with kernel sit0/NAT64 routes.
+
+- `2002::/16` (6to4, RFC 3056 — deprecated by RFC 7526)
+- `64:ff9b::/96` (NAT64 well-known, RFC 6052)
+- `64:ff9b:1::/48` (NAT64 local-use, RFC 8215 — same SSRF threat class
+ as the WKP; missing it earned a HackerOne bounty against
+ ssrf_filter)
+- `2001::/32` (Teredo, RFC 4380)
+- `100::/64` (IPv6 discard, RFC 6666)
+- `::/96` (IPv4-Compatible IPv6, RFC 4291 §2.5.5.1 — DEPRECATED 2006;
+ same SSRF threat class as the transition prefixes)
+
+The metadata-IP block is hardened against IPv6-wrapped IMDS access:
+when an IPv6 destination falls in a NAT64 prefix, the embedded IPv4 is
+extracted and matched against `ALWAYS_BLOCKED_METADATA_IPS`, so
+`[64:ff9b::a9fe:a9fe]` cannot reach 169.254.169.254 even on a NAT64
+host.
+
+Operators on IPv6-only deployments using DNS64+NAT64 (where outbound
+IPv4 traffic is synthesized through `64:ff9b::/96`) can opt back in via
+the env-only setting `security.allow_nat64`
+(`LDR_SECURITY_ALLOW_NAT64=true`). The opt-in is scoped strictly to
+the two NAT64 prefixes — 6to4, Teredo, and discard remain blocked
+unconditionally, and the IMDS embedded-IPv4 carve-out still applies.
diff --git a/src/local_deep_research/security/ip_ranges.py b/src/local_deep_research/security/ip_ranges.py
index eb0c8adc14..d9a44114b2 100644
--- a/src/local_deep_research/security/ip_ranges.py
+++ b/src/local_deep_research/security/ip_ranges.py
@@ -25,4 +25,36 @@ PRIVATE_IP_RANGES = [
ipaddress.ip_network(
"::/128"
), # IPv6 unspecified — Linux routes connections to local host
+ # IPv6 transition prefixes that can wrap private IPv4 destinations.
+ # On Linux hosts with kernel sit0 / NAT64 routes configured, these
+ # prefixes are forwarded to the embedded IPv4 (e.g. 2002:7f00:1::
+ # → 127.0.0.1 via 6to4). Default Linux has no such routes so they
+ # are not exploitable in the typical deployment, but blocking them
+ # closes the gap for operators who do enable transition tunnels.
+ ipaddress.ip_network("2002::/16"), # 6to4 (RFC 3056, deprecated RFC 7526)
+ ipaddress.ip_network("64:ff9b::/96"), # NAT64 well-known prefix (RFC 6052)
+ ipaddress.ip_network(
+ "64:ff9b:1::/48"
+ ), # NAT64 local-use prefix (RFC 8215) — same SSRF threat class as the WKP
+ ipaddress.ip_network("2001::/32"), # Teredo (RFC 4380)
+ ipaddress.ip_network("100::/64"), # IPv6 discard prefix (RFC 6666)
+ # IPv4-Compatible IPv6 — DEPRECATED by RFC 4291 §2.5.5.1 in 2006 but
+ # still parseable by ipaddress and routable on hosts with ::/96 routes
+ # configured (rare but real). Embeds the IPv4 in the low 32 bits so
+ # [::169.254.169.254] would otherwise reach IMDS, identically to the
+ # 6to4/NAT64 wraps. Has zero legitimate live use; blocking it is the
+ # same defense-in-depth move as the transition prefixes above.
+ ipaddress.ip_network("::/96"),
+]
+
+# NAT64 prefixes — operators on IPv6-only hosts using DNS64+NAT64 reach
+# IPv4 services through these. Blocking by default protects the typical
+# deployment shape (laptops / dual-stack) from the IPv6-wrapped IMDS /
+# RFC1918 SSRF bypass class. Operators who actually need NAT64 reachable
+# can opt in via the env-only setting ``security.allow_nat64``
+# (LDR_SECURITY_ALLOW_NAT64=true). 6to4, Teredo, and discard remain
+# unconditionally blocked — they have no legitimate live use.
+NAT64_PREFIXES = [
+ ipaddress.ip_network("64:ff9b::/96"),
+ ipaddress.ip_network("64:ff9b:1::/48"),
]
diff --git a/src/local_deep_research/security/notification_validator.py b/src/local_deep_research/security/notification_validator.py
index 08a4f83fe2..f5a7dc1101 100644
--- a/src/local_deep_research/security/notification_validator.py
+++ b/src/local_deep_research/security/notification_validator.py
@@ -64,18 +64,47 @@ class NotificationURLValidator:
PRIVATE_IP_RANGES = _PRIVATE_IP_RANGES
@staticmethod
- def _is_private_ip(hostname: str) -> bool:
+ def _ip_matches_blocked_range(ip, allow_private_ips: bool = False) -> bool:
+ """Block-decision for a parsed IP, delegating to
+ ``ssrf_validator.is_ip_blocked`` so the two validators share a
+ single source of truth.
+
+ Honors:
+ - ALWAYS_BLOCKED_METADATA_IPS (cloud metadata, absolute)
+ - is_nat64_wrapped_metadata_ip (NAT64-wrapped IMDS, absolute)
+ - security.allow_nat64 env carve-out for the two NAT64 prefixes
+ - allow_private_ips: when True, RFC1918 / CGNAT / loopback /
+ link-local / IPv6 ULA are allowed BUT the two absolute checks
+ above still fire. This closes the historical bypass where
+ ``allow_private_ips=True`` skipped the host check entirely
+ and let metadata IPs through the notification path.
+ """
+ from .ssrf_validator import is_ip_blocked
+
+ return is_ip_blocked(str(ip), allow_private_ips=allow_private_ips)
+
+ @staticmethod
+ def _is_private_ip(hostname: str, allow_private_ips: bool = False) -> bool:
"""
Check if hostname resolves to a private IP address.
Args:
hostname: Hostname to check
+ allow_private_ips: When True, RFC1918 / CGNAT / loopback /
+ link-local / IPv6 ULA are NOT considered private. Cloud
+ metadata IPs and NAT64-wrapped metadata IPs are blocked
+ regardless — the operator opt-in cannot license IMDS
+ exposure.
Returns:
- True if hostname is a private IP or localhost
+ True if hostname is a private IP or localhost (subject to
+ allow_private_ips), or wraps a metadata IP unconditionally
"""
- # Check for localhost variations
- if hostname.lower() in (
+ # Localhost-string shortcuts only apply when the operator hasn't
+ # opted into private-IP reachability. With allow_private_ips=True
+ # we let the IP path (DNS-resolved or literal) make the decision
+ # so metadata-IP literals like "169.254.169.254" still block.
+ if not allow_private_ips and hostname.lower() in (
"localhost",
"127.0.0.1",
"::1",
@@ -87,9 +116,8 @@ class NotificationURLValidator:
# Try to parse as IP address
try:
ip = ipaddress.ip_address(hostname)
- return any(
- ip in network
- for network in NotificationURLValidator.PRIVATE_IP_RANGES
+ return NotificationURLValidator._ip_matches_blocked_range(
+ ip, allow_private_ips=allow_private_ips
)
except ValueError:
# Hostname - resolve to IP and check.
@@ -131,9 +159,8 @@ class NotificationURLValidator:
executor.shutdown(wait=False, cancel_futures=True)
for _family, _, _, _, sockaddr in resolved_ips:
ip = ipaddress.ip_address(sockaddr[0])
- if any(
- ip in network
- for network in NotificationURLValidator.PRIVATE_IP_RANGES
+ if NotificationURLValidator._ip_matches_blocked_range(
+ ip, allow_private_ips=allow_private_ips
):
return True
except (socket.gaierror, OSError, TimeoutError):
@@ -233,7 +260,14 @@ class NotificationURLValidator:
# (GHSA-g23j-2vwm-5c25). For non-HTTP schemes (Apprise transports
# like discord://, slack://, mailto://) Apprise handles the URL
# itself and the parser-differential doesn't apply.
- if scheme in ("http", "https") and not allow_private_ips:
+ #
+ # The host check runs even when ``allow_private_ips=True`` —
+ # ``_is_private_ip`` propagates that flag, so RFC1918 / loopback
+ # are allowed through, but cloud-metadata IPs and NAT64-wrapped
+ # metadata still block. ``allow_private_ips=True`` is an
+ # operator opt-in for self-hosted webhooks on internal networks,
+ # not for IMDS exfiltration.
+ if scheme in ("http", "https"):
try:
u3 = parse_url(url)
except LocationParseError:
@@ -255,7 +289,9 @@ class NotificationURLValidator:
hostname = hostname[1:-1]
if hostname:
hostname = hostname.rstrip(".")
- if hostname and NotificationURLValidator._is_private_ip(hostname):
+ if hostname and NotificationURLValidator._is_private_ip(
+ hostname, allow_private_ips=allow_private_ips
+ ):
logger.warning(
f"Blocked private/internal IP in notification URL: "
f"{hostname}"
diff --git a/src/local_deep_research/security/ssrf_validator.py b/src/local_deep_research/security/ssrf_validator.py
index 5c041c9c72..54ccfbd1ca 100644
--- a/src/local_deep_research/security/ssrf_validator.py
+++ b/src/local_deep_research/security/ssrf_validator.py
@@ -15,6 +15,7 @@ from urllib3.exceptions import LocationParseError
from urllib3.util import parse_url
from .ip_ranges import PRIVATE_IP_RANGES as BLOCKED_IP_RANGES
+from .ip_ranges import NAT64_PREFIXES
# Cloud-provider metadata endpoints — always blocked, even with
# allow_localhost=True or allow_private_ips=True. These IPs expose IAM /
@@ -33,6 +34,26 @@ ALWAYS_BLOCKED_METADATA_IPS = frozenset(
# Allowed URL schemes
ALLOWED_SCHEMES = {"http", "https"}
+
+def is_nat64_wrapped_metadata_ip(ip: ipaddress._BaseAddress) -> bool:
+ """True iff ``ip`` is an IPv6 address inside a NAT64 prefix whose
+ embedded IPv4 (low 32 bits) is in ``ALWAYS_BLOCKED_METADATA_IPS``.
+
+ Both ``is_ip_blocked`` and ``NotificationURLValidator._ip_matches_blocked_range``
+ consult this before honoring the ``security.allow_nat64`` operator
+ opt-in, so cloud-metadata access cannot be re-opened through an
+ IPv6-wrapped destination on a NAT64-equipped host. Keeping the
+ extraction in one place prevents the two validators from drifting.
+ """
+ if not isinstance(ip, ipaddress.IPv6Address):
+ return False
+ for nat64_prefix in NAT64_PREFIXES:
+ if ip in nat64_prefix:
+ embedded_v4 = ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
+ return str(embedded_v4) in ALWAYS_BLOCKED_METADATA_IPS
+ return False
+
+
# RFC 3986 forbids these characters in URLs; their presence in a URL signals
# a parser-differential attempt (GHSA-g23j-2vwm-5c25). \s covers space, \t,
# \n, \r, \v, \f. Backslash is the load-bearing payload — Python's urlparse
@@ -104,9 +125,31 @@ def is_ip_blocked(
if str(ip) in ALWAYS_BLOCKED_METADATA_IPS:
return True
+ # Also block metadata IPs reached via NAT64 wrap. NAT64 prefixes
+ # embed the IPv4 destination in the low 32 bits; even when the
+ # operator has set LDR_SECURITY_ALLOW_NAT64=true the metadata
+ # block is "always" — an opt-in for IPv4 reachability does NOT
+ # license IMDS exposure.
+ if is_nat64_wrapped_metadata_ip(ip):
+ return True
+
+ # Operator escape hatch for IPv6-only deployments using DNS64+NAT64.
+ # Read lazily (not at import) so test monkeypatching works and so the
+ # value is not cached across env mutations. Cloud-metadata IPs are
+ # ALWAYS blocked above, so this carve-out cannot reopen IMDS via
+ # the IPv6-wrapped form.
+ from ..settings.env_registry import get_env_setting
+
+ nat64_allowed = bool(get_env_setting("security.allow_nat64", False))
+
# Check if IP is in any blocked range
for blocked_range in BLOCKED_IP_RANGES:
if ip in blocked_range:
+ # NAT64 carve-out: when the operator has opted in, the two
+ # NAT64 prefixes don't block. 6to4 / Teredo / discard remain
+ # blocked unconditionally.
+ if nat64_allowed and blocked_range in NAT64_PREFIXES:
+ continue
# If allow_private_ips is True, skip blocking for private + loopback
if allow_private_ips:
is_loopback = any(ip in lr for lr in LOOPBACK_RANGES)
diff --git a/src/local_deep_research/settings/env_definitions/security.py b/src/local_deep_research/settings/env_definitions/security.py
index 45ddde6be8..a2f2a7c296 100644
--- a/src/local_deep_research/settings/env_definitions/security.py
+++ b/src/local_deep_research/settings/env_definitions/security.py
@@ -43,6 +43,25 @@ SECURITY_SETTINGS = [
),
default=False,
),
+ BooleanSetting(
+ key="security.allow_nat64",
+ description=(
+ "Allow outbound traffic to NAT64 prefixes (64:ff9b::/96 RFC 6052 "
+ "well-known and 64:ff9b:1::/48 RFC 8215 local-use). Disabled by "
+ "default to close the IPv6-wrapped SSRF bypass class — on hosts "
+ "configured with NAT64 routes, attacker-supplied URLs can wrap "
+ "cloud-metadata or RFC1918 destinations through these prefixes. "
+ "Enable only on IPv6-only deployments (DNS64+NAT64) where "
+ "outbound IPv4 traffic is synthesized through this prefix and "
+ "the operator has accepted the residual SSRF risk. 6to4 "
+ "(2002::/16), Teredo (2001::/32), and the discard prefix "
+ "(100::/64) remain unconditionally blocked because they have no "
+ "live legitimate use in 2026. The cloud-metadata block "
+ "(ALWAYS_BLOCKED_METADATA_IPS) still applies via embedded-IPv4 "
+ "extraction — see SECURITY.md."
+ ),
+ default=False,
+ ),
BooleanSetting(
key="notifications.allow_outbound",
description=(
diff --git a/tests/security/test_ip_ranges.py b/tests/security/test_ip_ranges.py
index 88001470f3..49cd41df0c 100644
--- a/tests/security/test_ip_ranges.py
+++ b/tests/security/test_ip_ranges.py
@@ -10,6 +10,17 @@ Tests cover:
import ipaddress
+def _ip_is_private(ip_str: str) -> bool:
+ """Module-level helper used across the IPv6-transition-prefix test
+ classes. (TestPrivateIPDetection has its own copy that returns
+ False for invalid IPs; this one is for callers that pass only
+ well-formed addresses.)"""
+ from local_deep_research.security.ip_ranges import PRIVATE_IP_RANGES
+
+ ip = ipaddress.ip_address(ip_str)
+ return any(ip in network for network in PRIVATE_IP_RANGES)
+
+
class TestPrivateIPRanges:
"""Tests for PRIVATE_IP_RANGES constant."""
@@ -114,6 +125,65 @@ class TestPrivateIPRanges:
unspecified_v6 = ipaddress.ip_network("::/128")
assert unspecified_v6 in PRIVATE_IP_RANGES
+ def test_contains_6to4_prefix(self):
+ """Should contain 2002::/16 (6to4 transition prefix). Wraps
+ private IPv4 destinations on hosts with sit0 routes."""
+ from local_deep_research.security.ip_ranges import PRIVATE_IP_RANGES
+
+ sixto4 = ipaddress.ip_network("2002::/16")
+ assert sixto4 in PRIVATE_IP_RANGES
+
+ def test_contains_nat64_prefix(self):
+ """Should contain 64:ff9b::/96 (NAT64 well-known prefix)."""
+ from local_deep_research.security.ip_ranges import PRIVATE_IP_RANGES
+
+ nat64 = ipaddress.ip_network("64:ff9b::/96")
+ assert nat64 in PRIVATE_IP_RANGES
+
+ def test_contains_nat64_local_use_prefix(self):
+ """Should contain 64:ff9b:1::/48 (RFC 8215 NAT64 local-use prefix)
+ — same SSRF threat class as the well-known prefix; missing it is
+ the exact bypass paid out as a HackerOne bounty against
+ ssrf_filter."""
+ from local_deep_research.security.ip_ranges import PRIVATE_IP_RANGES
+
+ nat64_local = ipaddress.ip_network("64:ff9b:1::/48")
+ assert nat64_local in PRIVATE_IP_RANGES
+
+ def test_nat64_prefixes_constant_exposes_both(self):
+ """NAT64_PREFIXES must contain exactly the two NAT64 prefixes —
+ used by validators to identify which deny entries the
+ security.allow_nat64 env carve-out should skip."""
+ from local_deep_research.security.ip_ranges import NAT64_PREFIXES
+
+ assert ipaddress.ip_network("64:ff9b::/96") in NAT64_PREFIXES
+ assert ipaddress.ip_network("64:ff9b:1::/48") in NAT64_PREFIXES
+ assert len(NAT64_PREFIXES) == 2
+
+ def test_contains_teredo_prefix(self):
+ """Should contain 2001::/32 (Teredo)."""
+ from local_deep_research.security.ip_ranges import PRIVATE_IP_RANGES
+
+ teredo = ipaddress.ip_network("2001::/32")
+ assert teredo in PRIVATE_IP_RANGES
+
+ def test_contains_ipv6_discard_prefix(self):
+ """Should contain 100::/64 (RFC 6666 discard)."""
+ from local_deep_research.security.ip_ranges import PRIVATE_IP_RANGES
+
+ discard = ipaddress.ip_network("100::/64")
+ assert discard in PRIVATE_IP_RANGES
+
+ def test_contains_ipv4_compatible_ipv6_prefix(self):
+ """Should contain ::/96 (RFC 4291 IPv4-Compatible IPv6 — DEPRECATED).
+ Same SSRF threat class as the transition prefixes: embeds an IPv4
+ address in the low 32 bits and is routable on hosts with ::/96
+ routes configured. [::169.254.169.254] would otherwise reach IMDS."""
+ from local_deep_research.security.ip_ranges import PRIVATE_IP_RANGES
+
+ ipv4_compat = ipaddress.ip_network("::/96")
+ assert ipv4_compat in PRIVATE_IP_RANGES
+
class TestPrivateIPDetection:
"""Tests for using PRIVATE_IP_RANGES to detect private IPs."""
@@ -175,6 +245,123 @@ class TestPrivateIPDetection:
assert self._is_private("2001:4860:4860::8888") is False # Google DNS
+class TestIPv6TransitionPrefixesAntiCollision:
+ """Anti-regression: confirm the new IPv6 transition-prefix entries
+ do NOT swallow legitimate global IPv6 allocations at their boundaries.
+
+ Each prefix is precisely scoped at the bit level:
+ - 2001::/32 fixes the second hextet to 0x0000 (Teredo only).
+ - 2002::/16 fixes the first hextet to 0x2002 (6to4 only).
+ - 64:ff9b::/96 fixes the first 96 bits (the well-known NAT64 prefix
+ only; RFC 8215 local-use 64:ff9b:1::/48 must NOT match).
+ - 100::/64 fixes the first 64 bits (RFC 6666 discard only; the rest
+ of 100::/8 is unallocated, not discard).
+ """
+
+ _is_private = staticmethod(_ip_is_private)
+
+ def test_google_dns_v6_not_blocked(self):
+ """2001:4860:4860::8888 — second hextet 0x4860, outside 2001::/32."""
+ assert self._is_private("2001:4860:4860::8888") is False
+
+ def test_cloudflare_dns_v6_not_blocked(self):
+ """2606:4700:4700::1111 — first hextet 0x2606, far from 2001/2002."""
+ assert self._is_private("2606:4700:4700::1111") is False
+
+ def test_documentation_prefix_v6_not_blocked(self):
+ """2001:db8::/32 (RFC 3849) — second hextet 0x0db8, outside Teredo."""
+ assert self._is_private("2001:db8::1") is False
+
+ def test_root_server_v6_not_blocked(self):
+ """2001:500::/30 (root-server allocation) — second hextet 0x0500."""
+ assert self._is_private("2001:500:88::1") is False
+
+ def test_he_tunnelbroker_v6_not_blocked(self):
+ """2001:470::/32 (Hurricane Electric) — second hextet 0x0470."""
+ assert self._is_private("2001:470:1f04::1") is False
+
+ def test_neighbor_above_6to4_not_blocked(self):
+ """2003::/16 (Deutsche Telekom) sits adjacent to 2002::/16."""
+ assert self._is_private("2003::1") is False
+
+ def test_neighbor_below_6to4_not_blocked(self):
+ """2001:ffff::1 — last address of 2001:: space, not in 2002::/16."""
+ assert self._is_private("2001:ffff::1") is False
+
+ # NOTE: RFC 8215's 64:ff9b:1::/48 (NAT64 local-use) IS now blocked —
+ # see TestPrivateIPRanges::test_contains_nat64_local_use_prefix. It
+ # is the same SSRF threat class as the well-known /96 and missing
+ # it has been paid out as a HackerOne bounty against ssrf_filter.
+
+ def test_ipv6_discard_prefix_neighbor_not_blocked(self):
+ """100:1::/64 — second hextet 0x0001, outside the /64 discard
+ block. The surrounding 100::/8 is reserved-unallocated, not
+ discard, so we must not over-block it."""
+ assert self._is_private("100:1::1") is False
+
+
+class TestIPv6TransitionPrefixesPositiveDetection:
+ """Confirm the new transition prefixes detect their full address space,
+ including embedded private-IPv4 wraps relevant to SSRF."""
+
+ _is_private = staticmethod(_ip_is_private)
+
+ def test_6to4_wraps_loopback(self):
+ """[2002:7f00:1::] — 6to4 wrap of 127.0.0.1."""
+ assert self._is_private("2002:7f00:1::") is True
+
+ def test_6to4_wraps_rfc1918_class_a(self):
+ """[2002:0a00:1::] — 6to4 wrap of 10.0.0.1."""
+ assert self._is_private("2002:0a00:1::") is True
+
+ def test_6to4_wraps_rfc1918_class_b(self):
+ """[2002:ac10:1::] — 6to4 wrap of 172.16.0.1."""
+ assert self._is_private("2002:ac10:1::") is True
+
+ def test_6to4_wraps_rfc1918_class_c(self):
+ """[2002:c0a8:101::] — 6to4 wrap of 192.168.1.1."""
+ assert self._is_private("2002:c0a8:101::") is True
+
+ def test_6to4_wraps_aws_metadata(self):
+ """[2002:a9fe:a9fe::] — 6to4 wrap of 169.254.169.254 (AWS IMDS).
+ High-value SSRF target; must be caught by the prefix block."""
+ assert self._is_private("2002:a9fe:a9fe::") is True
+
+ def test_6to4_upper_boundary(self):
+ """Last address in 2002::/16."""
+ assert (
+ self._is_private("2002:ffff:ffff:ffff:ffff:ffff:ffff:ffff") is True
+ )
+
+ def test_nat64_wraps_loopback(self):
+ """[64:ff9b::7f00:1] — NAT64 wrap of 127.0.0.1."""
+ assert self._is_private("64:ff9b::7f00:1") is True
+
+ def test_nat64_wraps_rfc1918_class_a(self):
+ """[64:ff9b::a00:1] — NAT64 wrap of 10.0.0.1."""
+ assert self._is_private("64:ff9b::a00:1") is True
+
+ def test_nat64_wraps_rfc1918_class_b(self):
+ """[64:ff9b::ac10:1] — NAT64 wrap of 172.16.0.1."""
+ assert self._is_private("64:ff9b::ac10:1") is True
+
+ def test_nat64_wraps_aws_metadata(self):
+ """[64:ff9b::a9fe:a9fe] — NAT64 wrap of 169.254.169.254 (AWS IMDS)."""
+ assert self._is_private("64:ff9b::a9fe:a9fe") is True
+
+ def test_teredo_lower_boundary(self):
+ """2001:0:0:0:0:0:0:0 — first address in 2001::/32."""
+ assert self._is_private("2001::") is True
+
+ def test_teredo_upper_boundary(self):
+ """2001:0:ffff:ffff:ffff:ffff:ffff:ffff — last address in 2001::/32."""
+ assert self._is_private("2001:0:ffff:ffff:ffff:ffff:ffff:ffff") is True
+
+ def test_discard_prefix_upper_boundary(self):
+ """Last address in 100::/64."""
+ assert self._is_private("100::ffff:ffff:ffff:ffff") is True
+
+
class TestIPRangesUsedByValidators:
"""Tests to verify PRIVATE_IP_RANGES is correctly imported by validators."""
diff --git a/tests/security/test_notification_validator.py b/tests/security/test_notification_validator.py
index 01dc05dfc8..fc703544d0 100644
--- a/tests/security/test_notification_validator.py
+++ b/tests/security/test_notification_validator.py
@@ -524,3 +524,208 @@ class TestClassConstants:
assert "127.0.0.0/8" in range_strings
assert "10.0.0.0/8" in range_strings
assert "192.168.0.0/16" in range_strings
+
+
+class TestNat64EnvOptOutInNotificationValidator:
+ """Mirror of ssrf_validator's TestNat64EnvOptOut for the notification
+ path. The notification validator must honor the same operator
+ opt-in semantics AND keep the cloud-metadata block absolute."""
+
+ def test_nat64_wkp_blocked_when_env_unset(self, monkeypatch):
+ monkeypatch.delenv("LDR_SECURITY_ALLOW_NAT64", raising=False)
+ # 64:ff9b::a00:1 is the NAT64 wrap of 10.0.0.1.
+ assert NotificationURLValidator._is_private_ip("64:ff9b::a00:1") is True
+
+ def test_nat64_wkp_allowed_when_env_true(self, monkeypatch):
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ # NAT64 wrap of 8.8.8.8 — canonical IPv6-only-deployment use case.
+ assert (
+ NotificationURLValidator._is_private_ip("64:ff9b::808:808") is False
+ )
+
+ def test_nat64_local_use_allowed_when_env_true(self, monkeypatch):
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert (
+ NotificationURLValidator._is_private_ip("64:ff9b:1::808:808")
+ is False
+ )
+
+ def test_imds_via_nat64_wkp_wrap_blocked_under_env_true(self, monkeypatch):
+ """[64:ff9b::a9fe:a9fe] — NAT64 WKP wrap of 169.254.169.254.
+ Must remain blocked even with the operator opt-in. Mirrors the
+ ssrf_validator embedded-IPv4 IMDS check."""
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert (
+ NotificationURLValidator._is_private_ip("64:ff9b::a9fe:a9fe")
+ is True
+ )
+
+ def test_imds_via_nat64_local_use_wrap_blocked_under_env_true(
+ self, monkeypatch
+ ):
+ """Same lock-in for the RFC 8215 local-use prefix wrap."""
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert (
+ NotificationURLValidator._is_private_ip("64:ff9b:1::a9fe:a9fe")
+ is True
+ )
+
+ def test_ecs_metadata_via_nat64_wrap_blocked_under_env_true(
+ self, monkeypatch
+ ):
+ """169.254.170.2 = 0xa9feaa02 — AWS ECS task metadata v3."""
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert (
+ NotificationURLValidator._is_private_ip("64:ff9b::a9fe:aa02")
+ is True
+ )
+
+ def test_alibaba_metadata_via_nat64_wrap_blocked_under_env_true(
+ self, monkeypatch
+ ):
+ """100.100.100.200 = 0x646464c8 — AlibabaCloud metadata."""
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert (
+ NotificationURLValidator._is_private_ip("64:ff9b::6464:64c8")
+ is True
+ )
+
+ def test_env_does_not_unblock_6to4_in_notification_path(self, monkeypatch):
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert (
+ NotificationURLValidator._is_private_ip("2002:c0a8:101::") is True
+ )
+
+ def test_env_does_not_unblock_teredo_in_notification_path(
+ self, monkeypatch
+ ):
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert NotificationURLValidator._is_private_ip("2001::1") is True
+
+ def test_imds_via_nat64_wrap_blocked_when_env_unset(self, monkeypatch):
+ """Sanity: the IMDS embedded-IPv4 check fires regardless of env
+ state — when env is unset, the NAT64 prefix entry already blocks
+ directly, but the embedded-IPv4 path is still well-formed."""
+ monkeypatch.delenv("LDR_SECURITY_ALLOW_NAT64", raising=False)
+ assert (
+ NotificationURLValidator._is_private_ip("64:ff9b::a9fe:a9fe")
+ is True
+ )
+
+ def test_ipv4_mapped_imds_blocked(self, monkeypatch):
+ """Cross-validator parity: ssrf_validator unwraps IPv4-mapped
+ IPv6 (``::ffff:169.254.169.254``) before the IMDS literal check.
+ notification_validator must do the same — otherwise an attacker
+ who can configure a webhook URL can reach IMDS via the IPv4-
+ mapped form. Pre-PR this was a real gap; locked in here so it
+ cannot regress."""
+ monkeypatch.delenv("LDR_SECURITY_ALLOW_NAT64", raising=False)
+ assert (
+ NotificationURLValidator._is_private_ip("::ffff:169.254.169.254")
+ is True
+ )
+
+ def test_ipv4_mapped_loopback_blocked(self, monkeypatch):
+ """Same parity check for the loopback IPv4-mapped form."""
+ monkeypatch.delenv("LDR_SECURITY_ALLOW_NAT64", raising=False)
+ assert (
+ NotificationURLValidator._is_private_ip("::ffff:127.0.0.1") is True
+ )
+
+ def test_ipv4_mapped_public_ip_passes(self, monkeypatch):
+ """Anti-collision: the unwrap must not over-block public IPv4."""
+ monkeypatch.delenv("LDR_SECURITY_ALLOW_NAT64", raising=False)
+ assert (
+ NotificationURLValidator._is_private_ip("::ffff:8.8.8.8") is False
+ )
+
+ def test_validate_service_url_imds_blocked_under_allow_private_ips(self):
+ """Round-3 audit regression: validate_service_url with
+ allow_private_ips=True previously short-circuited the entire
+ host check, allowing http://169.254.169.254/ through. The opt-in
+ is for self-hosted webhooks on internal networks, not for IMDS
+ exfiltration. ALWAYS_BLOCKED_METADATA_IPS must remain absolute."""
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ "http://169.254.169.254/latest/meta-data/",
+ allow_private_ips=True,
+ )
+ assert is_valid is False
+ assert error is not None
+
+ def test_validate_service_url_imds_v6_mapped_blocked_under_allow_private_ips(
+ self,
+ ):
+ is_valid, _ = NotificationURLValidator.validate_service_url(
+ "http://[::ffff:169.254.169.254]/", allow_private_ips=True
+ )
+ assert is_valid is False
+
+ def test_validate_service_url_imds_via_nat64_wkp_blocked_under_allow_private_ips(
+ self,
+ ):
+ is_valid, _ = NotificationURLValidator.validate_service_url(
+ "http://[64:ff9b::a9fe:a9fe]/", allow_private_ips=True
+ )
+ assert is_valid is False
+
+ def test_validate_service_url_imds_via_nat64_local_use_blocked_under_allow_private_ips(
+ self,
+ ):
+ is_valid, _ = NotificationURLValidator.validate_service_url(
+ "http://[64:ff9b:1::a9fe:a9fe]/", allow_private_ips=True
+ )
+ assert is_valid is False
+
+ def test_validate_service_url_alibaba_metadata_blocked_under_allow_private_ips(
+ self,
+ ):
+ """100.100.100.200 is in ALWAYS_BLOCKED_METADATA_IPS and ALSO in
+ the CGNAT range (100.64.0.0/10) — pre-fix the carve-out for
+ CGNAT under allow_private_ips=True would have leaked it."""
+ is_valid, _ = NotificationURLValidator.validate_service_url(
+ "http://100.100.100.200/", allow_private_ips=True
+ )
+ assert is_valid is False
+
+ def test_validate_service_url_rfc1918_allowed_under_allow_private_ips(self):
+ """Anti-collision: the fix must not over-block legitimate
+ self-hosted webhook destinations. allow_private_ips=True is
+ designed for exactly this case."""
+ is_valid, _ = NotificationURLValidator.validate_service_url(
+ "http://192.168.1.100/webhook", allow_private_ips=True
+ )
+ assert is_valid is True
+
+ def test_validate_service_url_localhost_allowed_under_allow_private_ips(
+ self,
+ ):
+ is_valid, _ = NotificationURLValidator.validate_service_url(
+ "http://localhost:5000/webhook", allow_private_ips=True
+ )
+ assert is_valid is True
+
+ def test_dns_resolved_imds_via_nat64_blocked_under_env_true(
+ self, monkeypatch
+ ):
+ """Hostname-resolution branch: a hostname that resolves to a
+ NAT64-wrapped IMDS IPv4 must still be blocked under env opt-in.
+ This exercises the second call site of _ip_matches_blocked_range."""
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ # AF_INET6 result tuple: (family, type, proto, canonname, sockaddr)
+ # sockaddr for IPv6 is (host, port, flowinfo, scopeid)
+ with patch(
+ "socket.getaddrinfo",
+ return_value=[
+ (
+ socket.AF_INET6,
+ socket.SOCK_STREAM,
+ 6,
+ "",
+ ("64:ff9b::a9fe:a9fe", 0, 0, 0),
+ )
+ ],
+ ):
+ assert (
+ NotificationURLValidator._is_private_ip("imds.attacker.example")
+ is True
+ )
diff --git a/tests/security/test_ssrf_validator.py b/tests/security/test_ssrf_validator.py
index f51d33a1ad..d7347dee09 100644
--- a/tests/security/test_ssrf_validator.py
+++ b/tests/security/test_ssrf_validator.py
@@ -1176,37 +1176,518 @@ class TestNeverRaises:
assert isinstance(result, bool)
-class TestOutOfScopeBehaviorLockedIn:
+class TestIPv6TransitionPrefixesBlocked:
+ """IPv6 transition prefixes (6to4, NAT64, Teredo, discard) are now
+ blocked. On Linux hosts with kernel sit0/NAT64 routes configured,
+ these prefixes wrap private IPv4 destinations. Default Linux has no
+ such routes (so this isn't exploitable in the typical deployment),
+ but blocking them closes the gap for operators who do enable
+ transition tunnels."""
+
+ def test_6to4_wrapped_loopback_blocked(self):
+ """``[2002:7f00:1::]`` — 6to4 wrap of 127.0.0.1."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2002:7f00:1::]/") is False
+
+ def test_6to4_wrapped_rfc1918_blocked(self):
+ """``[2002:c0a8:101::]`` — 6to4 wrap of 192.168.1.1."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2002:c0a8:101::]/") is False
+
+ def test_nat64_wrapped_loopback_blocked(self):
+ """``[64:ff9b::7f00:1]`` — NAT64 wrap of 127.0.0.1."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[64:ff9b::7f00:1]/") is False
+
+ def test_teredo_prefix_blocked(self):
+ """Teredo (2001::/32) tunnels IPv6-over-UDP/IPv4."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2001::1]/") is False
+
+ def test_ipv6_discard_prefix_blocked(self):
+ """RFC 6666 discard prefix (100::/64) is reserved for sinkholes."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[100::1]/") is False
+
+ def test_6to4_wraps_aws_metadata_blocked(self):
+ """[2002:a9fe:a9fe::] — 6to4 wrap of 169.254.169.254 (AWS IMDS).
+ Cloud metadata is the highest-value SSRF target; the 2002::/16
+ block is what catches this case (the IMDS hardcoded literal
+ check is on the IPv4 form only)."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2002:a9fe:a9fe::]/") is False
+
+ def test_nat64_wraps_aws_metadata_blocked(self):
+ """[64:ff9b::a9fe:a9fe] — NAT64 wrap of 169.254.169.254 (AWS IMDS)."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[64:ff9b::a9fe:a9fe]/") is False
+
+ def test_6to4_wraps_rfc1918_class_a_blocked(self):
+ """[2002:0a00:1::] — 6to4 wrap of 10.0.0.1."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2002:0a00:1::]/") is False
+
+ def test_6to4_wraps_rfc1918_class_b_blocked(self):
+ """[2002:ac10:1::] — 6to4 wrap of 172.16.0.1."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2002:ac10:1::]/") is False
+
+ def test_nat64_wraps_rfc1918_class_a_blocked(self):
+ """[64:ff9b::a00:1] — NAT64 wrap of 10.0.0.1."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[64:ff9b::a00:1]/") is False
+
+ def test_nat64_local_use_prefix_blocked(self):
+ """RFC 8215's 64:ff9b:1::/48 (NAT64 local-use) is the same SSRF
+ threat class as the well-known /96. On hosts configured to route
+ the local-use prefix, [64:ff9b:1::a9fe:a9fe] reaches AWS IMDS
+ identically to the WKP form. Missing this prefix earned a
+ HackerOne bounty against the Ruby ssrf_filter library."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[64:ff9b:1::1]/") is False
+
+ def test_nat64_local_use_wraps_aws_metadata_blocked(self):
+ """[64:ff9b:1::a9fe:a9fe] — local-use NAT64 wrap of 169.254.169.254."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[64:ff9b:1::a9fe:a9fe]/") is False
+
+ def test_ipv4_compatible_imds_blocked(self):
+ """[::169.254.169.254] — RFC 4291 IPv4-Compatible IPv6 form
+ (DEPRECATED 2006). On hosts with ::/96 routes this reaches IMDS
+ identically to the IPv4-mapped and NAT64-wrapped forms. Same
+ defense-in-depth class as the transition prefixes."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[::169.254.169.254]/") is False
+
+ def test_ipv4_compatible_imds_hex_form_blocked(self):
+ """Same address, hex form: [::a9fe:a9fe]."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[::a9fe:a9fe]/") is False
+
+ def test_ipv4_compatible_rfc1918_blocked(self):
+ """[::192.168.1.1] — IPv4-Compatible wrap of RFC1918."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[::192.168.1.1]/") is False
+
+
+class TestIPv6TransitionPrefixesAllowFlagMatrix:
+ """Lock in the design decision: ``allow_private_ips=True`` does NOT
+ bypass the IPv6 transition prefixes (2002::/16, 64:ff9b::/96,
+ 2001::/32, 100::/64). The override carve-out only covers the local
+ LOOPBACK_RANGES + PRIVATE_RANGES lists in ssrf_validator.py; the
+ transition prefixes are intentionally excluded so that an attacker
+ cannot reach a private IPv4 destination by tunneling through 6to4
+ or NAT64 even when the operator has set ``allow_private_ips=True``
+ for a self-hosted service like Ollama.
+
+ If you ever need a self-hosted service reachable via 6to4 or
+ NAT64, that's a deliberate config decision and the design here
+ forces it to be made explicitly.
"""
- Behaviours documented as out-of-scope (filed as separate hardening
- issues, not a bypass of GHSA-g23j-2vwm-5c25). Tests here lock in the
- *current* behaviour so the gap is visible — if we later harden these,
- these tests should flip and be moved into the bypass class.
+
+ def test_6to4_blocked_under_allow_localhost(self):
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ assert is_ip_blocked("2002:7f00:1::", allow_localhost=True) is True
+
+ def test_6to4_blocked_under_allow_private_ips(self):
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ assert is_ip_blocked("2002:c0a8:101::", allow_private_ips=True) is True
+
+ def test_nat64_blocked_under_allow_localhost(self):
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ assert is_ip_blocked("64:ff9b::7f00:1", allow_localhost=True) is True
+
+ def test_nat64_blocked_under_allow_private_ips(self):
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ assert is_ip_blocked("64:ff9b::a00:1", allow_private_ips=True) is True
+
+ def test_teredo_blocked_under_allow_private_ips(self):
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ assert is_ip_blocked("2001::1", allow_private_ips=True) is True
+
+ def test_discard_blocked_under_allow_private_ips(self):
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ assert is_ip_blocked("100::1", allow_private_ips=True) is True
+
+ def test_6to4_aws_metadata_blocked_under_allow_private_ips(self):
+ """High-value: even with the most permissive flag, the 6to4 wrap
+ of AWS IMDS must remain blocked."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert (
+ validate_url("http://[2002:a9fe:a9fe::]/", allow_private_ips=True)
+ is False
+ )
+
+ def test_nat64_aws_metadata_blocked_under_allow_private_ips(self):
+ """Same locking-in for NAT64 wrap of IMDS."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert (
+ validate_url("http://[64:ff9b::a9fe:a9fe]/", allow_private_ips=True)
+ is False
+ )
+
+
+class TestIPv6TransitionPrefixesAntiCollision:
+ """Anti-regression: legitimate IPv6 destinations adjacent to the new
+ transition prefixes must still pass validation. These tests guard
+ against accidental over-blocking if anyone widens a prefix later."""
+
+ def test_google_dns_v6_passes(self):
+ """2001:4860:4860::8888 — Google Public DNS. Second hextet 0x4860
+ is outside the 2001::/32 Teredo block."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2001:4860:4860::8888]/") is True
+
+ def test_cloudflare_dns_v6_passes(self):
+ """2606:4700:4700::1111 — Cloudflare Public DNS, far from any
+ transition prefix."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2606:4700:4700::1111]/") is True
+
+ def test_root_server_v6_passes(self):
+ """2001:500::/30 root-server allocation — second hextet 0x0500
+ is outside Teredo."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2001:500:88::1]/") is True
+
+ def test_he_tunnelbroker_v6_passes(self):
+ """2001:470::/32 Hurricane Electric — second hextet 0x0470."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2001:470:1f04::1]/") is True
+
+ def test_neighbor_above_6to4_passes(self):
+ """2003::/16 sits adjacent to 2002::/16 but is not in it."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[2003::1]/") is True
+
+ def test_discard_prefix_neighbor_passes(self):
+ """100:1::/16 sits outside the 100::/64 discard prefix
+ (second hextet 0x0001)."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ assert validate_url("http://[100:1::1]/") is True
+
+
+class TestNat64EnvOptOut:
+ """Operator escape hatch: ``LDR_SECURITY_ALLOW_NAT64=true`` opens the
+ two NAT64 prefixes for IPv6-only deployments using DNS64+NAT64.
+
+ Critical invariants:
+ - The carve-out is ONLY for the two NAT64 prefixes (well-known and
+ RFC 8215 local-use). 6to4, Teredo, discard remain blocked.
+ - The carve-out does NOT reopen the IPv4-form cloud-metadata block
+ (169.254.169.254 stays blocked).
+ - Reading the env var lazily (per-call, not at import) means
+ monkeypatching works in tests.
"""
- def test_6to4_wrapped_loopback_currently_passes(self):
- """
- ``[2002:7f00:1::]`` is the 6to4 wrap of ``127.0.0.1``. On hosts
- with kernel sit0/6to4 routes configured, this routes to ``127.0.0.1``.
- Default Linux has no such route, so this is not exploitable in
- the default configuration — but the validator does not catch it.
- Filed separately.
- """
+ def test_nat64_wkp_blocked_when_env_unset(self, monkeypatch):
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ monkeypatch.delenv("LDR_SECURITY_ALLOW_NAT64", raising=False)
+ assert validate_url("http://[64:ff9b::a00:1]/") is False
+
+ def test_nat64_wkp_allowed_when_env_true(self, monkeypatch):
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ # 64:ff9b::8.8.8.8 — NAT64 wrap of Google DNS, the canonical
+ # IPv6-only-deployment use case.
+ assert validate_url("http://[64:ff9b::808:808]/") is True
+
+ def test_nat64_local_use_allowed_when_env_true(self, monkeypatch):
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert validate_url("http://[64:ff9b:1::808:808]/") is True
+
+ def test_env_does_not_unblock_6to4(self, monkeypatch):
+ """6to4 has no live legitimate use; the operator switch must
+ not extend to it."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert validate_url("http://[2002:c0a8:101::]/") is False
+
+ def test_env_does_not_unblock_teredo(self, monkeypatch):
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert validate_url("http://[2001::1]/") is False
+
+ def test_env_does_not_unblock_discard(self, monkeypatch):
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert validate_url("http://[100::1]/") is False
+
+ def test_env_does_not_unblock_imds_v4_literal(self, monkeypatch):
+ """The IPv4-form metadata literal is in ALWAYS_BLOCKED_METADATA_IPS
+ and is checked BEFORE the prefix loop. The NAT64 carve-out
+ cannot reach it."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert validate_url("http://169.254.169.254/") is False
+
+ def test_env_does_not_unblock_imds_via_nat64_wkp_wrap(self, monkeypatch):
+ """The IMDS embedded-IPv4 check fires before the NAT64 carve-out:
+ even with operator opt-in, [64:ff9b::a9fe:a9fe] (NAT64 WKP wrap
+ of 169.254.169.254) stays blocked. ALWAYS_BLOCKED_METADATA_IPS
+ is absolute by design."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert validate_url("http://[64:ff9b::a9fe:a9fe]/") is False
+
+ def test_env_does_not_unblock_imds_via_nat64_local_use_wrap(
+ self, monkeypatch
+ ):
+ """Same lock-in for the RFC 8215 local-use prefix wrap."""
from src.local_deep_research.security.ssrf_validator import (
validate_url,
)
- # Document current behaviour: passes. If we ever add the IPv6
- # transition prefixes to BLOCKED_IP_RANGES, flip this assertion.
- assert validate_url("http://[2002:7f00:1::]/") is True
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert validate_url("http://[64:ff9b:1::a9fe:a9fe]/") is False
- def test_nat64_wrapped_loopback_currently_passes(self):
- """``[64:ff9b::7f00:1]`` is the NAT64 wrap of ``127.0.0.1``."""
+ def test_env_does_not_unblock_ecs_metadata_via_nat64_wrap(
+ self, monkeypatch
+ ):
+ """169.254.170.2 (AWS ECS task metadata v3) is also in the
+ always-blocked set; NAT64 wrap stays blocked under opt-in."""
from src.local_deep_research.security.ssrf_validator import (
validate_url,
)
- assert validate_url("http://[64:ff9b::7f00:1]/") is True
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ # 169.254.170.2 = 0xa9feaa02
+ assert validate_url("http://[64:ff9b::a9fe:aa02]/") is False
+
+ def test_env_falsy_values_keep_blocked(self, monkeypatch):
+ """'false', '0', and unset must all keep the block in place."""
+ from src.local_deep_research.security.ssrf_validator import (
+ validate_url,
+ )
+
+ for value in ("false", "0", "no", ""):
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", value)
+ assert validate_url("http://[64:ff9b::a00:1]/") is False, (
+ f"NAT64 must remain blocked for env value {value!r}"
+ )
+
+ def test_env_true_does_not_bypass_loopback_in_block_list(self, monkeypatch):
+ """Sanity: opting into NAT64 must not accidentally unblock
+ non-NAT64 entries that share a prefix family."""
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert is_ip_blocked("127.0.0.1") is True
+ assert is_ip_blocked("::1") is True
+
+ def test_env_true_does_not_unblock_ipv6_ula(self, monkeypatch):
+ """The carve-out's ``continue`` lives in the same loop that walks
+ ULA (fc00::/7) and link-local (fe80::/10). Pin that opting into
+ NAT64 does not accidentally unblock these adjacent IPv6 ranges."""
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert is_ip_blocked("fc00::1") is True
+ assert is_ip_blocked("fd12:3456:789a::1") is True
+
+ def test_env_true_does_not_unblock_ipv6_link_local(self, monkeypatch):
+ from src.local_deep_research.security.ssrf_validator import (
+ is_ip_blocked,
+ )
+
+ monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
+ assert is_ip_blocked("fe80::1") is True
+
+
+class TestIsNat64WrappedMetadataIp:
+ """Direct unit tests for the shared helper. Both validators rely on
+ its IPv4 short-circuit and on the metadata-set membership check;
+ surface those contracts explicitly so a refactor of either branch
+ can't silently flip them."""
+
+ def test_returns_false_for_ipv4(self):
+ """The helper must short-circuit for IPv4 inputs because it's
+ called after ``is_ip_blocked`` unwraps IPv4-mapped IPv6 — at
+ that point the address is no longer IPv6 and the NAT64 check
+ does not apply."""
+ import ipaddress
+ from src.local_deep_research.security.ssrf_validator import (
+ is_nat64_wrapped_metadata_ip,
+ )
+
+ assert (
+ is_nat64_wrapped_metadata_ip(
+ ipaddress.IPv4Address("169.254.169.254")
+ )
+ is False
+ )
+
+ def test_returns_false_for_non_nat64_ipv6(self):
+ """Public IPv6 (Google DNS) is not in any NAT64 prefix."""
+ import ipaddress
+ from src.local_deep_research.security.ssrf_validator import (
+ is_nat64_wrapped_metadata_ip,
+ )
+
+ assert (
+ is_nat64_wrapped_metadata_ip(
+ ipaddress.IPv6Address("2001:4860:4860::8888")
+ )
+ is False
+ )
+
+ def test_returns_false_for_nat64_wrap_of_non_metadata(self):
+ """[64:ff9b::a00:1] (NAT64 wrap of 10.0.0.1) is in a NAT64
+ prefix but the embedded IPv4 is not metadata — helper returns
+ False so the broader carve-out logic can apply."""
+ import ipaddress
+ from src.local_deep_research.security.ssrf_validator import (
+ is_nat64_wrapped_metadata_ip,
+ )
+
+ assert (
+ is_nat64_wrapped_metadata_ip(
+ ipaddress.IPv6Address("64:ff9b::a00:1")
+ )
+ is False
+ )
+
+ def test_returns_true_for_imds_via_wkp(self):
+ import ipaddress
+ from src.local_deep_research.security.ssrf_validator import (
+ is_nat64_wrapped_metadata_ip,
+ )
+
+ assert (
+ is_nat64_wrapped_metadata_ip(
+ ipaddress.IPv6Address("64:ff9b::a9fe:a9fe")
+ )
+ is True
+ )
+
+ def test_returns_true_for_imds_via_local_use(self):
+ import ipaddress
+ from src.local_deep_research.security.ssrf_validator import (
+ is_nat64_wrapped_metadata_ip,
+ )
+
+ assert (
+ is_nat64_wrapped_metadata_ip(
+ ipaddress.IPv6Address("64:ff9b:1::a9fe:a9fe")
+ )
+ is True
+ )
class TestValidateUrlEdgeCases: