fix: harden httpx dialer IP validation (#4102)

## Summary
- Harden the IP validation used by the HTTP dialer
(`GetSSRFDialContext`) to also cover IPv6 transition mechanism
addresses, IPv6 scoped (zoned) addresses and the CGNAT range.
- Decode the IPv4 address embedded in NAT64 (Well-Known Prefix), 6to4,
Teredo and IPv4-compatible addresses and validate it recursively; block
the local-use NAT64 prefix wholesale.

## Why
- The guard relied on Go's `net.IP` predicates (`IsLoopback`,
`IsPrivate`, `IsUnspecified`, `IsMulticast`, `IsLinkLocalUnicast`,
`IsLinkLocalMulticast`), which operate on the literal address. These do
not decode IPv6 transition prefixes, so an address that embeds a
private/reserved IPv4 destination is not recognized as internal.
- The guard also used `net.ParseIP`, which rejects IPv6 addresses
carrying a zone identifier (e.g. `fe80::1%eth0`) and returns `nil`, so
such addresses fell through as if they were a valid public destination.

## Changes In This PR
- New `internal/pkg/httpx/ssrf.go`:
- `isInternalIP(ip)` - runs the standard checks plus CGNAT (RFC 6598);
blocks the RFC 8215 local-use NAT64 prefix `64:ff9b:1::/48` outright;
otherwise decodes transition addresses and recurses on the embedded
IPv4.
- `embeddedIPv4(ip16)` - extracts the embedded IPv4 only from the NAT64
Well-Known Prefix `64:ff9b::/96` (low 32 bits), 6to4 `2002::/16` (bits
16-47), Teredo `2001::/32` (bit-inverted low 32 bits) and
IPv4-compatible `::/96`. The local-use prefix is intentionally not
decoded here, since its IPv4 layout is operator-defined and not globally
reachable.
  - Module-level parsed CIDR prefixes.
- `internal/pkg/httpx/http.go`: `GetSSRFDialContext` now parses the dial
host with `netip.ParseAddr` (which accepts zone identifiers), strips the
zone for validation, and fails closed on any host that cannot be parsed
as an IP. The original zoned address is still used for the actual
connection. `EnablePrivateNet` opt-out is preserved.
- Tests:
- `internal/pkg/httpx/ssrf_unit_test.go` - `isInternalIP`,
`embeddedIPv4`, CGNAT boundaries, the real RFC 6052 `/48` layout case,
public-address cases.
- `internal/pkg/httpx/http_test.go` - dialer-level regression cases for
the transition prefixes, the `/48` local-use bypass, CGNAT and zoned
link-local addresses.

## Notes
- No config or runtime behavior change for valid public addresses;
transition addresses wrapping a public IPv4 still connect normally.
- The fix is shared by all consumers of the dialer: the HTTP source/sink
client (`internal/io/http/client.go`) and the service executor
(`internal/service/executors.go`); no changes needed there.
- Validation runs once per new TCP connection (transports use
keep-alive), not per message.
- All `internal/pkg/httpx` tests pass; `internal/io/http` passes (one
pre-existing unrelated failure, `TestRestSinkRecoverErr`, exists on
`master` as well).

Signed-off-by: Jiyong Huang <huangjy@emqx.io>

Author: ngjaying

internal/pkg/httpx/http.go

@@ -23,6 +23,7 @@ import (
 	"mime/multipart"
 	"net"
 	"net/http"
+	"net/netip"
 	"net/url"
 	"os"
 	"path/filepath"
@@ -245,8 +246,17 @@ func GetSSRFDialContext(timeout time.Duration) func(ctx context.Context, network
 				if err != nil {
 					return err
 				}
-				ip := net.ParseIP(host)
-				if ip != nil && (ip.IsLoopback() || ip.IsPrivate() || ip.IsUnspecified() || ip.IsMulticast() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast()) {
+				// net.ParseIP rejects IPv6 addresses carrying a zone identifier
+				// (e.g. "fe80::1%eth0"), which would then fall through as nil
+				// and bypass the internal-network check. Use netip.ParseAddr,
+				// which accepts zones, strip the zone for validation, and fail
+				// closed on any host that cannot be parsed as an IP.
+				na, err := netip.ParseAddr(host)
+				if err != nil {
+					return fmt.Errorf("invalid dial address %q: %w", host, err)
+				}
+				ip := net.IP(na.WithZone("").AsSlice())
+				if isInternalIP(ip) {
 					return fmt.Errorf("ip %s is in internal network", ip.String())
 				}
 				return nil

internal/pkg/httpx/http_test.go

@@ -119,6 +119,44 @@ func TestGetSSRFDialContext(t *testing.T) {
 		}
 	})
 
+	t.Run("Block IPv6 transition addresses that wrap an internal IPv4", func(t *testing.T) {
+		// Regression test for GHSA-4q5r-r938-8xr2: the SSRF guard must decode
+		// IPv6 transition mechanisms and block the embedded private IPv4.
+		conf.Config.Basic.EnablePrivateNet = false
+		dialer := GetSSRFDialContext(time.Second)
+
+		cases := []string{
+			// NAT64 (RFC 6052) /96 wrapping 169.254.169.254
+			"[64:ff9b::a9fe:a9fe]:80",
+			// RFC 8215 local-use NAT64 /48: real embedded IPv4 is 169.254.169.254
+			// (bytes 6-7/9-10) while low 32 bits read as 8.8.8.8.
+			"[64:ff9b:1:a9fe:a9:fe00:808:808]:80",
+			// 6to4 (RFC 3056) wrapping 127.0.0.1
+			"[2002:7f00:1::]:80",
+			// Teredo (RFC 4380) wrapping 169.254.169.254
+			"[2001:0:4136:e378:8000:63bf:5601:5601]:80",
+			// IPv4-compatible (RFC 4291) wrapping 10.0.0.1
+			"[::10.0.0.1]:80",
+			// CGNAT (RFC 6598)
+			"100.64.0.1:80",
+			// IPv6 scoped addresses with a zone identifier. net.ParseIP rejects
+			// the zone and returns nil, which used to bypass the check.
+			"[fe80::1%eth0]:80",
+			"[::1%lo]:80",
+			"[64:ff9b::a9fe:a9fe%eth0]:80",
+		}
+		for _, addr := range cases {
+			conn, err := dialer(context.Background(), "tcp", addr)
+			assert.Error(t, err, addr)
+			if err != nil {
+				assert.Contains(t, err.Error(), "in internal network", addr)
+			}
+			if conn != nil {
+				conn.Close()
+			}
+		}
+	})
+
 	t.Run("Allow private IP when enabled", func(t *testing.T) {
 		conf.Config.Basic.EnablePrivateNet = true
 		dialer := GetSSRFDialContext(time.Second)

internal/pkg/httpx/ssrf.go

@@ -0,0 +1,107 @@
+// Copyright 2025 EMQ Technologies Co., Ltd.
+//
+// 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.
+
+package httpx
+
+import (
+	"bytes"
+	"fmt"
+	"net"
+)
+
+var (
+	// IPv6 transition mechanism prefixes that embed an IPv4 address.
+	nat64Prefix     = mustParseCIDR("64:ff9b::/96") // RFC 6052 (NAT64 Well-Known Prefix)
+	sixToFourPrefix = mustParseCIDR("2002::/16")    // RFC 3056 (6to4)
+	teredoPrefix    = mustParseCIDR("2001::/32")    // RFC 4380 (Teredo)
+	// Carrier-grade NAT (RFC 6598) is not detected by net.IP.IsPrivate.
+	cgnatPrefix = mustParseCIDR("100.64.0.0/10")
+	// RFC 8215 local-use NAT64 prefix. It is not globally reachable and does
+	// not carry an IPv4 address at a fixed position, so it is blocked wholesale
+	// rather than decoded. (Only the /96 Well-Known Prefix carries IPv4 in the
+	// low 32 bits per RFC 6052.)
+	nat64LocalUsePrefix = mustParseCIDR("64:ff9b:1::/48")
+)
+
+func mustParseCIDR(s string) *net.IPNet {
+	_, n, err := net.ParseCIDR(s)
+	if err != nil {
+		panic(fmt.Sprintf("httpx: invalid CIDR %q: %v", s, err))
+	}
+	return n
+}
+
+// isInternalIP reports whether ip points to a loopback, private, link-local or
+// otherwise reserved address that the SSRF guard must block.
+//
+// It decodes IPv6 transition mechanism addresses (NAT64 Well-Known Prefix,
+// 6to4, Teredo and IPv4-compatible) to extract and recursively validate the
+// embedded IPv4 address, so a private/reserved IPv4 destination cannot be
+// reached by wrapping it inside an IPv6 transition address (GHSA-4q5r-r938-8xr2).
+func isInternalIP(ip net.IP) bool {
+	if ip == nil {
+		return false
+	}
+	// Standard private/reserved ranges; works for both IPv4 and IPv6.
+	if ip.IsLoopback() || ip.IsPrivate() || ip.IsUnspecified() ||
+		ip.IsMulticast() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() {
+		return true
+	}
+	if ip4 := ip.To4(); ip4 != nil {
+		// Carrier-grade NAT (RFC 6598) is not covered by net.IP.IsPrivate.
+		return cgnatPrefix.Contains(ip4)
+	}
+	ip16 := ip.To16()
+	if ip16 == nil {
+		return false
+	}
+	// RFC 8215 local-use NAT64 prefix: block outright, it is not globally
+	// reachable and its IPv4 layout is operator-defined.
+	if nat64LocalUsePrefix.Contains(ip16) {
+		return true
+	}
+	if inner, ok := embeddedIPv4(ip16); ok {
+		return isInternalIP(inner)
+	}
+	return false
+}
+
+// embeddedIPv4 extracts the IPv4 address embedded in an IPv6 transition
+// mechanism address. It returns the embedded IPv4 address and true when the
+// address belongs to a known transition prefix, otherwise nil and false.
+func embeddedIPv4(ip16 net.IP) (net.IP, bool) {
+	// IPv4-compatible (::/96 with the first 96 bits set to zero, RFC 4291,
+	// deprecated). Loopback (::1) and unspecified (::) have an all-zero prefix
+	// too, but they are already rejected by the standard checks in isInternalIP
+	// before this function is called.
+	var zero [12]byte
+	if bytes.Equal(ip16[:12], zero[:]) {
+		return ip16[12:16].To4(), true
+	}
+	switch {
+	case nat64Prefix.Contains(ip16):
+		// NAT64 Well-Known Prefix (RFC 6052): only /96 is well-known, and the
+		// embedded IPv4 address occupies the low 32 bits. Other prefix lengths
+		// are operator-chosen Network-Specific Prefixes and are not decoded.
+		return ip16[12:16].To4(), true
+	case sixToFourPrefix.Contains(ip16):
+		// 6to4 (RFC 3056): the embedded IPv4 address occupies bits 16-47.
+		return ip16[2:6].To4(), true
+	case teredoPrefix.Contains(ip16):
+		// Teredo (RFC 4380): the client IPv4 address occupies the low 32 bits
+		// but each octet is bit-inverted.
+		return net.IPv4(^ip16[12], ^ip16[13], ^ip16[14], ^ip16[15]).To4(), true
+	}
+	return nil, false
+}

internal/pkg/httpx/ssrf_unit_test.go

@@ -0,0 +1,178 @@
+// Copyright 2025 EMQ Technologies Co., Ltd.
+//
+// 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.
+
+package httpx
+
+import (
+	"net"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// narcted for IPv4 -> NAT64 (RFC 6052) address
+func nat64For(ipv4 string) string {
+	b := net.ParseIP(ipv4).To4()
+	addr := make(net.IP, 16)
+	addr[0], addr[1] = 0x00, 0x64
+	addr[2], addr[3] = 0xff, 0x9b
+	addr[12], addr[13], addr[14], addr[15] = b[0], b[1], b[2], b[3]
+	return addr.String()
+}
+
+// 6to4For maps an IPv4 -> 6to4 (RFC 3056) address
+func sixToFourFor(ipv4 string) string {
+	b := net.ParseIP(ipv4).To4()
+	addr := make(net.IP, 16)
+	addr[0], addr[1] = 0x20, 0x02
+	addr[2], addr[3], addr[4], addr[5] = b[0], b[1], b[2], b[3]
+	return addr.String()
+}
+
+// teredoFor maps an IPv4 -> Teredo (RFC 4380) address. The client IPv4 octets
+// are bit-inverted.
+func teredoFor(ipv4 string) string {
+	b := net.ParseIP(ipv4).To4()
+	addr := make(net.IP, 16)
+	addr[0], addr[1] = 0x20, 0x01 // 2001::/32
+	addr[2], addr[3] = 0, 0
+	addr[4], addr[5], addr[6], addr[7] = 0x41, 0x36, 0xe3, 0x78 // arbitrary server
+	addr[8], addr[9] = 0x80, 0x00                               // flags
+	addr[10], addr[11] = 0x63, 0xbf                             // client port
+	addr[12], addr[13], addr[14], addr[15] = ^b[0], ^b[1], ^b[2], ^b[3]
+	return addr.String()
+}
+
+// TestIsInternalIP_SSRFTransitionAddresses guards against the IPv6 transition
+// address bypass described in GHSA-4q5r-r938-8xr2. The previously-bypassed
+// addresses must now be reported as internal.
+func TestIsInternalIP_SSRFTransitionAddresses(t *testing.T) {
+	internal := []struct {
+		label string
+		ip    string
+	}{
+		// IPv4 ranges that were already blocked.
+		{"ipv4 loopback", "127.0.0.1"},
+		{"ipv4 private 10", "10.0.0.1"},
+		{"ipv4 private 172", "172.16.0.1"},
+		{"ipv4 private 192", "192.168.1.1"},
+		{"ipv4 link-local metadata", "169.254.169.254"},
+		{"ipv4 unspecified", "0.0.0.0"},
+		{"ipv4 multicast", "224.0.0.1"},
+		{"ipv4 cgnat", "100.64.0.1"},
+		{"ipv4 cgnat edge low", "100.64.0.0"},
+		{"ipv4 cgnat edge high", "100.127.255.255"},
+		// IPv6 native ranges that were already blocked.
+		{"ipv6 loopback", "::1"},
+		{"ipv6 private ula", "fc00::1"},
+		{"ipv6 link-local", "fe80::1"},
+		{"ipv6 unspecified", "::"},
+		// NAT64 (RFC 6052) wrapping an internal IPv4.
+		{"nat64 loopback", nat64For("127.0.0.1")},
+		{"nat64 metadata", nat64For("169.254.169.254")},
+		{"nat64 private", nat64For("10.0.0.1")},
+		// NAT64 local-use (RFC 8215) prefix is blocked wholesale; the next
+		// case uses the *real* RFC 6052 /48 layout (v4 in bytes 6-7/9-10, u in
+		// byte 8, suffix in bytes 11-15) so the embedded IPv4 is 169.254.169.254
+		// while the low 32 bits read as 8.8.8.8. The previous implementation
+		// decoded the low 32 bits and let this through.
+		{"nat64 local-use /48 bypass", "64:ff9b:1:a9fe:a9:fe00:808:808"},
+		// Any address under 64:ff9b:1::/48 is blocked (local-use, not globally
+		// reachable), including one whose low 32 bits are a public IPv4.
+		{"nat64 local-use low-32 public", "64:ff9b:1::808:808"},
+		// 6to4 (RFC 3056) wrapping an internal IPv4.
+		{"6to4 loopback", sixToFourFor("127.0.0.1")},
+		{"6to4 metadata", sixToFourFor("169.254.169.254")},
+		{"6to4 private", sixToFourFor("10.0.0.1")},
+		// Teredo (RFC 4380) wrapping an internal IPv4.
+		{"teredo loopback", teredoFor("127.0.0.1")},
+		{"teredo metadata", teredoFor("169.254.169.254")},
+		// IPv4-compatible (RFC 4291, deprecated).
+		{"ipv4-compatible private", "::10.0.0.1"},
+		{"ipv4-compatible loopback", "::127.0.0.1"},
+		{"ipv4-compatible metadata", "::169.254.169.254"},
+		// IPv4-mapped wrapping an internal IPv4.
+		{"ipv4-mapped loopback", "::ffff:127.0.0.1"},
+		{"ipv4-mapped metadata", "::ffff:169.254.169.254"},
+		{"ipv4-mapped cgnat", "::ffff:100.64.0.1"},
+	}
+	for _, tt := range internal {
+		t.Run(tt.label, func(t *testing.T) {
+			ip := net.ParseIP(tt.ip)
+			assert.NotNil(t, ip, "failed to parse %s", tt.ip)
+			assert.True(t, isInternalIP(ip), "%s (%s) must be blocked", tt.label, tt.ip)
+		})
+	}
+}
+
+func TestIsInternalIP_PublicAddressesAllowed(t *testing.T) {
+	public := []struct {
+		label string
+		ip    string
+	}{
+		{"ipv4 public dns", "8.8.8.8"},
+		{"ipv4 public cloudflare", "1.1.1.1"},
+		{"ipv4 just below cgnat", "100.63.255.255"},
+		{"ipv4 just above cgnat", "100.128.0.0"},
+		// NAT64 wrapping a *public* IPv4 must be allowed: reaching a public
+		// address through NAT64 is not an SSRF issue.
+		{"nat64 public dns", nat64For("8.8.8.8")},
+		// 6to4 wrapping a public IPv4.
+		{"6to4 public dns", sixToFourFor("8.8.8.8")},
+		// Teredo wrapping a public IPv4.
+		{"teredo public dns", teredoFor("8.8.8.8")},
+		// Regular public IPv6.
+		{"ipv6 public", "2606:4700:4700::1111"},
+	}
+	for _, tt := range public {
+		t.Run(tt.label, func(t *testing.T) {
+			ip := net.ParseIP(tt.ip)
+			assert.NotNil(t, ip, "failed to parse %s", tt.ip)
+			assert.False(t, isInternalIP(ip), "%s (%s) must not be blocked", tt.label, tt.ip)
+		})
+	}
+}
+
+func TestIsInternalIP_Nil(t *testing.T) {
+	assert.False(t, isInternalIP(nil))
+	assert.False(t, isInternalIP(net.IP{}))
+}
+
+func TestEmbeddedIPv4(t *testing.T) {
+	tests := []struct {
+		name   string
+		ip     string
+		want   string
+		wantOK bool
+	}{
+		{"nat64 /96", nat64For("169.254.169.254"), "169.254.169.254", true},
+		{"6to4", sixToFourFor("8.8.8.8"), "8.8.8.8", true},
+		{"teredo", teredoFor("127.0.0.1"), "127.0.0.1", true},
+		{"ipv4-compatible", "::10.0.0.1", "10.0.0.1", true},
+		{"not transition", "2606:4700:4700::1111", "", false},
+		{"ipv4-mapped is handled by to4, not here", "::ffff:8.8.8.8", "", false},
+		// RFC 8215 local-use is blocked wholesale by isInternalIP, never decoded.
+		{"nat64 local-use /48", "64:ff9b:1:a9fe:a9:fe00:808:808", "", false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ip16 := net.ParseIP(tt.ip).To16()
+			got, ok := embeddedIPv4(ip16)
+			assert.Equal(t, tt.wantOK, ok)
+			if ok {
+				assert.Equal(t, tt.want, got.String())
+			}
+		})
+	}
+}