Skip to content

Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai

security: classify IPv4-mapped IPv6 by its embedded IPv4; reject host:port allowlist entries (#127)

Francois du Plessis0e897463a58f
diff --git a/src/hyperresearch/web/safe_http.py b/src/hyperresearch/web/safe_http.py
index 2f39106..e733d43 100644
--- a/src/hyperresearch/web/safe_http.py
+++ b/src/hyperresearch/web/safe_http.py
@@ -90,12 +90,19 @@ _CGNAT_NET = ipaddress.ip_network("100.64.0.0/10")
# 6to4 (RFC 3056): a 2002:AABB:CCDD::/48 prefix embeds the IPv4 address
# A.B.C.D, so 2002:7f00:1:: is loopback wearing an IPv6 coat. The transport
# is deprecated and rarely routed, but the ipaddress module does not flag it
-# and the embedded address is what matters. IPv4-mapped (::ffff:a.b.c.d) is
-# already caught because ipaddress unwraps it for the is_* properties.
+# and the embedded address is what matters.
_6TO4_NET = ipaddress.ip_network("2002::/16")
def _is_blocked_ip(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+ # Classify IPv4-mapped IPv6 (::ffff:a.b.c.d) by its embedded IPv4, which
+ # is where the OS sends the connection. The ipaddress is_* properties do
+ # not agree on mapped addresses across interpreters: on 3.11 and 3.13 a
+ # mapped CGNAT address passes every property, and the CGNAT check below
+ # only looks at version-4 addresses, so it was allowed; on 3.12 every
+ # mapped address reports is_reserved, so even a mapped public address
+ # was refused. Unmapping first gives the same answer everywhere.
+ ip = getattr(ip, "ipv4_mapped", None) or ip
if ip.version == 6 and ip in _6TO4_NET:
packed = int(ip) >> 80 & 0xFFFFFFFF
return _is_blocked_ip(ipaddress.IPv4Address(packed))
@@ -146,12 +153,22 @@ def _parse_allowlist(
if not entry:
continue
try:
- networks.append(ipaddress.ip_network(entry, strict=False))
+ # Brackets are URL notation for an IPv6 literal ("[::1]"); the
+ # network types reject them, so parse the address inside.
+ networks.append(ipaddress.ip_network(entry.strip("[]"), strict=False))
except ValueError:
if "/" in entry: # meant as a CIDR, but malformed
raise SafeHTTPError(
f"invalid allow_private_hosts entry {entry!r}: not a valid CIDR"
) from None
+ if ":" in entry:
+ # host:port. URL hostnames never carry the port, so the entry
+ # would become a hostname that can never match: a silent dead
+ # entry that looks like an SSRF refusal of the user's mirror.
+ raise SafeHTTPError(
+ f"invalid allow_private_hosts entry {entry!r}: entries are "
+ "hostnames or CIDRs; drop the port"
+ )
hostnames.add(entry.lower())
return frozenset(hostnames), networks
diff --git a/tests/test_web/test_safe_http.py b/tests/test_web/test_safe_http.py
index c7a5487..fa9ba5c 100644
--- a/tests/test_web/test_safe_http.py
+++ b/tests/test_web/test_safe_http.py
@@ -315,6 +315,33 @@ def test_check_url_allows_6to4_wrapping_public_ipv4():
check_url("http://[2002:808:808::]/")
+# ---------------------------------------------------------------------------
+# IPv4-mapped IPv6 (::ffff:a.b.c.d) is classified by the embedded IPv4. The
+# ipaddress properties disagree across interpreters: 3.11 and 3.13 report a
+# mapped CGNAT address as public, 3.12 reports even a mapped public address
+# as reserved.
+# ---------------------------------------------------------------------------
+
+
+ "url",
+ [
+ "http://[::ffff:10.0.0.1]/",
+ "http://[::ffff:169.254.169.254]/", # mapped cloud metadata
+ "http://[::ffff:100.64.0.1]/", # mapped CGNAT: allowed on 3.11 and 3.13
+ ],
+)
+def test_check_url_rejects_ipv4_mapped_private_forms(url):
+ with pytest.raises(SafeHTTPError, match="non-public address"):
+ check_url(url)
+
+
+def test_check_url_allows_ipv4_mapped_public():
+ """A mapped PUBLIC address stays fetchable: the verdict follows the
+ embedded address, where 3.12's is_reserved refused it wholesale."""
+ check_url("http://[::ffff:8.8.8.8]/")
+
+
# ---------------------------------------------------------------------------
# allow_private_hosts — the [fetch] escape hatch for intranet mirrors
# ---------------------------------------------------------------------------
@@ -382,3 +409,23 @@ def test_safe_get_redirect_to_allowlisted_private_host_is_followed():
allow_private_hosts=("192.168.1.20",),
)
assert resp.content == b"mirror content"
+
+
+# ---------------------------------------------------------------------------
+# allow_private_hosts entry hygiene
+# ---------------------------------------------------------------------------
+
+
[email protected]("entry", ["192.168.1.20:8443", "mirror.internal:8443"])
+def test_allowlist_entry_with_port_is_a_loud_error(entry):
+ """A host:port entry would otherwise become a hostname that can never
+ match (URL hostnames carry no port): a silent dead entry presenting as
+ an SSRF refusal of the user's own mirror."""
+ with pytest.raises(SafeHTTPError, match="drop the port"):
+ check_url("http://8.8.8.8/", allow_private_hosts=(entry,))
+
+
+def test_allowlist_bracketed_ipv6_entry_admits_the_literal():
+ """A bracketed IPv6 entry (URL notation) parses as the address itself
+ instead of becoming a hostname that never matches."""
+ check_url("http://[::1]/", allow_private_hosts=("[::1]",))