Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(ssrf): unwrap IPv6 transition addresses in the URL guard (#19517)

Aroh Mauryaea2ce6d32393
diff --git a/common/ssrf_guard.py b/common/ssrf_guard.py
index e478cda0a7..9ec4f66a0e 100644
--- a/common/ssrf_guard.py
+++ b/common/ssrf_guard.py
@@ -99,18 +99,33 @@ def _allow_any_host() -> bool:
return os.environ.get(_ALLOW_ANY_HOST_ENV, "").strip().lower() in {"1", "true", "yes", "on"}
+_NAT64_WELL_KNOWN_PREFIX = ipaddress.ip_network("64:ff9b::/96")
+
+
def _effective_ip(
ip: ipaddress.IPv4Address | ipaddress.IPv6Address,
) -> ipaddress.IPv4Address | ipaddress.IPv6Address:
- """Return the IPv4 equivalent for IPv4-mapped IPv6 addresses, unchanged otherwise.
+ """Return the routable IPv4 address carried by an IPv6 address, unchanged otherwise.
+
+ Some IPv6 forms embed an arbitrary IPv4 address that ``is_global`` does not
+ look at, so a private/link-local IPv4 target could be reached by wrapping it:
+
+ - IPv4-mapped ``::ffff:127.0.0.1``
+ - NAT64 well-known prefix ``64:ff9b::7f00:1`` (RFC 6052)
+ - deprecated IPv4-compatible ``::127.0.0.1`` (RFC 4291)
- Without this normalization ``::ffff:127.0.0.1`` would pass ``is_global``
- as an IPv6Address in some Python versions, bypassing the loopback check.
+ 6to4 (``2002::/16``) and Teredo (``2001::/32``) are already handled by
+ ``ipaddress.is_global``.
"""
- if isinstance(ip, ipaddress.IPv6Address):
- mapped = ip.ipv4_mapped
- if mapped is not None:
- return mapped
+ if not isinstance(ip, ipaddress.IPv6Address):
+ return ip
+ mapped = ip.ipv4_mapped
+ if mapped is not None:
+ return mapped
+ if ip in _NAT64_WELL_KNOWN_PREFIX:
+ return ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
+ if ip.packed[:12] == b"\x00" * 12:
+ return ipaddress.IPv4Address(ip.packed[12:])
return ip
diff --git a/internal/utility/ssrf.go b/internal/utility/ssrf.go
index 8c7b499a79..44735de857 100644
--- a/internal/utility/ssrf.go
+++ b/internal/utility/ssrf.go
@@ -124,6 +124,10 @@ func isGlobalIP(ip net.IP) bool {
return false
}
if v4 := ip.To4(); v4 != nil {
+ // 0.0.0.0/8 — "this network"; 0.x.y.z routes to localhost on Linux.
+ if v4[0] == 0 {
+ return false
+ }
// CGNAT 100.64.0.0/10 — not flagged by IsPrivate in older Go versions.
if v4[0] == 100 && v4[1]&0xC0 == 64 {
return false
@@ -159,10 +163,51 @@ func isGlobalIP(ip net.IP) bool {
if v6[0] == 0x01 && v6[1] == 0x00 && allZero(v6[2:8]) {
return false
}
+ // IPv6 transition addresses (6to4, NAT64, Teredo, IPv4-compatible) embed
+ // an arbitrary IPv4 address that none of the checks above look at. Unwrap
+ // and re-check it so 2002:7f00:1::1 is treated as 127.0.0.1.
+ for _, inner := range embeddedIPv4(v6) {
+ if !isGlobalIP(inner) {
+ return false
+ }
+ }
}
return true
}
+// embeddedIPv4 returns the IPv4 addresses carried inside an IPv6 transition
+// address, or nil when it carries none. Teredo yields two: the relay server and
+// the (obfuscated) client.
+func embeddedIPv4(v6 net.IP) []net.IP {
+ switch {
+ // 6to4 — RFC 3056, 2002::/16, IPv4 in bytes 2-6.
+ case v6[0] == 0x20 && v6[1] == 0x02:
+ return []net.IP{net.IPv4(v6[2], v6[3], v6[4], v6[5])}
+
+ // NAT64 well-known prefix — RFC 6052, 64:ff9b::/96, IPv4 in the low 32 bits.
+ case v6[0] == 0x00 && v6[1] == 0x64 && v6[2] == 0xff && v6[3] == 0x9b && allZero(v6[4:12]):
+ return []net.IP{net.IPv4(v6[12], v6[13], v6[14], v6[15])}
+
+ // NAT64 local-use prefix — RFC 8215, 64:ff9b:1::/48. The embedded IPv4
+ // position depends on the operator's prefix length, so block the range.
+ case v6[0] == 0x00 && v6[1] == 0x64 && v6[2] == 0xff && v6[3] == 0x9b && v6[4] == 0x00 && v6[5] == 0x01:
+ return []net.IP{net.IPv4zero}
+
+ // Teredo — RFC 4380, 2001::/32. Server IPv4 in bytes 4-8, client IPv4 in
+ // bytes 12-16 obfuscated by XOR with 0xff.
+ case v6[0] == 0x20 && v6[1] == 0x01 && v6[2] == 0x00 && v6[3] == 0x00:
+ return []net.IP{
+ net.IPv4(v6[4], v6[5], v6[6], v6[7]),
+ net.IPv4(v6[12]^0xff, v6[13]^0xff, v6[14]^0xff, v6[15]^0xff),
+ }
+
+ // IPv4-compatible — deprecated ::a.b.c.d, not unwrapped by net.IP.To4.
+ case allZero(v6[0:12]):
+ return []net.IP{net.IPv4(v6[12], v6[13], v6[14], v6[15])}
+ }
+ return nil
+}
+
func allZero(b []byte) bool {
for _, x := range b {
if x != 0 {
diff --git a/internal/utility/ssrf_test.go b/internal/utility/ssrf_test.go
index 36ffbb00f1..d4d0c0bc6e 100644
--- a/internal/utility/ssrf_test.go
+++ b/internal/utility/ssrf_test.go
@@ -120,6 +120,48 @@ func TestAssertURLSafe(t *testing.T) {
ips: []string{"203.0.113.5"},
want: want{errSubstr: "non-public address"},
},
+ {
+ name: "0.0.0.0/8 rejected",
+ url: "http://stub/",
+ ips: []string{"0.1.2.3"},
+ want: want{errSubstr: "non-public address"},
+ },
+ {
+ name: "6to4 wrapping loopback rejected",
+ url: "http://stub/",
+ ips: []string{"2002:7f00:1::1"},
+ want: want{errSubstr: "non-public address"},
+ },
+ {
+ name: "NAT64 well-known prefix wrapping metadata IP rejected",
+ url: "http://stub/",
+ ips: []string{"64:ff9b::a9fe:a9fe"},
+ want: want{errSubstr: "non-public address"},
+ },
+ {
+ name: "NAT64 local-use prefix rejected",
+ url: "http://stub/",
+ ips: []string{"64:ff9b:1::7f00:1"},
+ want: want{errSubstr: "non-public address"},
+ },
+ {
+ name: "Teredo wrapping loopback client rejected",
+ url: "http://stub/",
+ ips: []string{"2001:0:0:0:0:0:80ff:fffe"},
+ want: want{errSubstr: "non-public address"},
+ },
+ {
+ name: "IPv4-compatible wrapping loopback rejected",
+ url: "http://stub/",
+ ips: []string{"::7f00:1"},
+ want: want{errSubstr: "non-public address"},
+ },
+ {
+ name: "NAT64 well-known prefix wrapping public IP allowed",
+ url: "http://stub/",
+ ips: []string{"64:ff9b::808:808"},
+ want: want{host: "stub", ip: "64:ff9b::808:808"},
+ },
}
for _, tc := range cases {
diff --git a/test/unit_test/common/test_ssrf_guard.py b/test/unit_test/common/test_ssrf_guard.py
new file mode 100644
index 0000000000..26f76bc45d
--- /dev/null
+++ b/test/unit_test/common/test_ssrf_guard.py
@@ -0,0 +1,75 @@
+#
+# Copyright 2025 The InfiniFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+"""Tests for the shared SSRF guard in common.ssrf_guard."""
+
+from __future__ import annotations
+
+import socket
+from unittest.mock import patch
+
+import pytest
+
+from common import ssrf_guard
+
+
+def _addr_infos(*ips: str):
+ infos = []
+ for ip in ips:
+ family = socket.AF_INET6 if ":" in ip else socket.AF_INET
+ infos.append((family, socket.SOCK_STREAM, 6, "", (ip, 0)))
+ return infos
+
+
+def _resolve_to(*ips: str):
+ return patch("common.ssrf_guard.socket.getaddrinfo", return_value=_addr_infos(*ips))
+
+
+def test_allows_public_ipv4():
+ with _resolve_to("93.184.216.34"):
+ host, ip = ssrf_guard.assert_url_is_safe("https://example.com/")
+ assert host == "example.com"
+ assert ip == "93.184.216.34"
+
+
+ "addr",
+ [
+ "127.0.0.1",
+ "10.0.0.5",
+ "169.254.169.254",
+ "::ffff:127.0.0.1",
+ # IPv6 transition addresses embedding a private/link-local IPv4 target.
+ "64:ff9b::7f00:1", # NAT64 well-known prefix -> 127.0.0.1
+ "64:ff9b::a9fe:a9fe", # NAT64 well-known prefix -> 169.254.169.254 (cloud metadata)
+ "::7f00:1", # deprecated IPv4-compatible -> 127.0.0.1
+ ],
+)
+def test_blocks_non_public_targets(addr):
+ with _resolve_to(addr), pytest.raises(ValueError, match="non-public address"):
+ ssrf_guard.assert_url_is_safe("http://attacker.example/")
+
+
+def test_nat64_wrapping_public_ipv4_is_allowed():
+ # 64:ff9b::808:808 is the NAT64 representation of 8.8.8.8 and stays reachable.
+ with _resolve_to("64:ff9b::808:808"):
+ host, _ = ssrf_guard.assert_url_is_safe("http://nat64.example/")
+ assert host == "nat64.example"
+
+
+def test_assert_host_is_safe_blocks_nat64_private():
+ with _resolve_to("64:ff9b::a9fe:a9fe"), pytest.raises(ValueError, match="non-public address"):
+ ssrf_guard.assert_host_is_safe("attacker.example")