diff --git a/.changeset/netguard-package.md b/.changeset/netguard-package.md new file mode 100644 index 000000000..9aea1533c --- /dev/null +++ b/.changeset/netguard-package.md @@ -0,0 +1,5 @@ +--- +"github.com/livekit/protocol": patch +--- + +Add `utils/netguard`, a check that refuses internal and reserved addresses, for clients that connect to destinations a caller supplies: `IsBlockedIP`, `CheckHost`, `BlockInternal`, `NewDialControl`, `ParseCIDR`, and `ReportOnly` and `ReportOnlyContext`, which report what a check would refuse and let the connection go ahead. Existing packages are unchanged. diff --git a/utils/netguard/netguard.go b/utils/netguard/netguard.go new file mode 100644 index 000000000..1bf8a00e1 --- /dev/null +++ b/utils/netguard/netguard.go @@ -0,0 +1,228 @@ +// Copyright 2026 LiveKit, Inc. +// +// 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 netguard refuses connections to internal and reserved addresses, so +// a destination a caller does not trust cannot reach the host's own network. +// +// A dial guard sees the address being connected to, which is the proxy's when +// the client uses one, so a guarded http.Transport should set Proxy to nil. +package netguard + +import ( + "context" + "errors" + "fmt" + "net" + "net/netip" + "slices" + "strings" + "syscall" +) + +// ErrBlockedAddress marks a destination the guard refuses. It threads through a +// transport's url.Error, so callers can classify it as permanent. +var ErrBlockedAddress = errors.New("blocked destination address") + +var errShortMappedPrefix = errors.New("an IPv4-mapped prefix needs at least 96 bits") + +var blockedPrefixes = func() []netip.Prefix { + cidrs := []string{ + "100.64.0.0/10", // RFC 6598 CGNAT (carrier-grade NAT) + "0.0.0.0/8", // "this network" (RFC 1122) + "240.0.0.0/4", // reserved for future use (RFC 1112) + "198.18.0.0/15", // benchmarking (RFC 2544) + "192.0.0.0/24", // IETF protocol assignments (RFC 6890) + "192.88.99.0/24", // 6to4 relay anycast (RFC 3068, deprecated) + "192.0.2.0/24", // TEST-NET-1 documentation (RFC 5737) + "198.51.100.0/24", // TEST-NET-2 documentation (RFC 5737) + "203.0.113.0/24", // TEST-NET-3 documentation (RFC 5737) + "64:ff9b:1::/48", // NAT64 local-use prefix (RFC 8215) + "::/96", // IPv4-compatible IPv6 (RFC 4291, deprecated; embeds a v4 address) + "::ffff:0:0:0/96", // IPv4-translated (RFC 2765; embeds a v4 address) + "2002::/16", // 6to4 (RFC 3056; embeds a v4 address) + "2001::/23", // IETF protocol assignments (RFC 2928), includes Teredo 2001::/32 (RFC 4380; embeds a v4 address) + "fec0::/10", // IPv6 site-local (deprecated, RFC 3879) + "100::/64", // discard-only (RFC 6666) + "2001:db8::/32", // IPv6 documentation (RFC 3849) + "3fff::/20", // IPv6 documentation (RFC 9637) + "5f00::/16", // SRv6 SIDs (RFC 9602) + } + prefixes := make([]netip.Prefix, 0, len(cidrs)) + for _, c := range cidrs { + prefixes = append(prefixes, netip.MustParsePrefix(c)) + } + return prefixes +}() + +// CheckHost rejects a URL host that is localhost, a blocked IP literal, or an +// IP literal with a zone. A port, and brackets around an IPv6 literal, are +// accepted. It only catches configuration mistakes early: host names, and IPv4 +// spellings netip.ParseAddr rejects such as 127.1, pass here and are checked by +// a dial guard once resolved. +func CheckHost(host string) error { + if h, _, err := net.SplitHostPort(host); err == nil { + host = h + } + host = strings.TrimSuffix(strings.ToLower(host), ".") + if host == "localhost" || strings.HasSuffix(host, ".localhost") { + return ErrBlockedAddress + } + host = strings.TrimSuffix(strings.TrimPrefix(host, "["), "]") + if addr, err := netip.ParseAddr(host); err == nil { + if addr.Zone() != "" || IsBlockedIP(addr.AsSlice()) { + return ErrBlockedAddress + } + } + return nil +} + +// BlockInternal is a net.Dialer Control function that refuses every address +// IsBlockedIP reports, and any zoned address. +func BlockInternal(_, address string, _ syscall.RawConn) error { + return checkDialAddress(address, true, nil, nil) +} + +// ReportOnly wraps a net.Dialer Control function so that an address it refuses +// with ErrBlockedAddress is passed to report and the connection goes ahead. +// Other errors from control are returned unchanged. +func ReportOnly( + control func(network, address string, c syscall.RawConn) error, + report func(address string, err error), +) func(network, address string, c syscall.RawConn) error { + return func(network, address string, c syscall.RawConn) error { + err := control(network, address, c) + if errors.Is(err, ErrBlockedAddress) { + report(address, err) + return nil + } + return err + } +} + +// ReportOnlyContext is ReportOnly for net.Dialer.ControlContext, passing the +// dial context to report. Under http.Transport that context carries the values +// of the request that started the dial; a request that reuses a pooled +// connection does not dial, so it is not reported. +func ReportOnlyContext( + control func(network, address string, c syscall.RawConn) error, + report func(ctx context.Context, address string, err error), +) func(ctx context.Context, network, address string, c syscall.RawConn) error { + return func(ctx context.Context, network, address string, c syscall.RawConn) error { + err := control(network, address, c) + if errors.Is(err, ErrBlockedAddress) { + report(ctx, address, err) + return nil + } + return err + } +} + +// NewDialControl returns a net.Dialer Control function that refuses addresses +// in blocked, and private ones when blockPrivate is set, unless they are also +// in allowed. An allowed address is never refused, so a broad allowed range +// such as 0.0.0.0/0 also lets loopback and the cloud metadata address through. +// Prefixes should come from ParseCIDR. +func NewDialControl(blockPrivate bool, blocked, allowed []netip.Prefix) func(network, address string, c syscall.RawConn) error { + return func(_, address string, _ syscall.RawConn) error { + return checkDialAddress(address, blockPrivate, blocked, allowed) + } +} + +// ParseCIDR parses a range for NewDialControl. A dialed address is unmapped +// before matching, so an IPv4-mapped range is converted to its IPv4 range. +func ParseCIDR(cidr string) (netip.Prefix, error) { + p, err := netip.ParsePrefix(cidr) + if err != nil { + return netip.Prefix{}, err + } + if p.Addr().Is4In6() { + if p.Bits() < 96 { + return netip.Prefix{}, errShortMappedPrefix + } + p = netip.PrefixFrom(p.Addr().Unmap(), p.Bits()-96) + } + return p, nil +} + +func checkDialAddress(address string, blockPrivate bool, blocked, allowed []netip.Prefix) error { + ap, err := netip.ParseAddrPort(address) + if err != nil { + return err + } + addr := ap.Addr().WithZone("").Unmap() + if prefixesContain(allowed, addr) { + return nil + } + // an allowed entry is an exception, so only refusal widens to the embedded IPv4 address + if ap.Addr().Zone() != "" || + (blockPrivate && isBlocked(addr)) || + prefixesContain(blocked, addr) || + prefixesContain(blocked, embeddedIPv4(addr)) { + return fmt.Errorf("%w: %s", ErrBlockedAddress, ap.Addr()) + } + return nil +} + +func prefixesContain(prefixes []netip.Prefix, addr netip.Addr) bool { + return slices.ContainsFunc(prefixes, func(p netip.Prefix) bool { return p.Contains(addr) }) +} + +var ( + nat64Prefix = netip.MustParsePrefix("64:ff9b::/96") + v4CompatPrefix = netip.MustParsePrefix("::/96") + sixToFour = netip.MustParsePrefix("2002::/16") +) + +// Returns the IPv4 address a NAT64, v4-compatible or 6to4 address carries, or +// the zero Addr, which no prefix contains. +func embeddedIPv4(addr netip.Addr) netip.Addr { + b := addr.As16() + switch { + case nat64Prefix.Contains(addr), v4CompatPrefix.Contains(addr): + return netip.AddrFrom4([4]byte(b[12:])) + case sixToFour.Contains(addr): + return netip.AddrFrom4([4]byte(b[2:6])) + default: + return netip.Addr{} + } +} + +// IsBlockedIP reports whether ip falls in a range a guarded client must never +// dial: loopback, RFC1918 private and IPv6 ULA (fc00::/7), link-local unicast +// (including the 169.254.169.254 cloud-metadata IP and fe80::/10), link-local +// multicast, the unspecified address, any multicast, and the reserved ranges +// listed in blockedPrefixes. An address in the NAT64 well-known prefix is +// judged by the IPv4 address it carries. A nil or malformed ip is reported as +// blocked. +func IsBlockedIP(ip net.IP) bool { + addr, ok := netip.AddrFromSlice(ip) + if !ok { + return true + } + return isBlocked(addr.Unmap()) +} + +// addr must be unmapped. +func isBlocked(addr netip.Addr) bool { + if nat64Prefix.Contains(addr) { + return isBlocked(embeddedIPv4(addr)) + } + return addr.IsLoopback() || + addr.IsPrivate() || + addr.IsLinkLocalUnicast() || + addr.IsLinkLocalMulticast() || + addr.IsUnspecified() || + addr.IsMulticast() || + prefixesContain(blockedPrefixes, addr) +} diff --git a/utils/netguard/netguard_test.go b/utils/netguard/netguard_test.go new file mode 100644 index 000000000..311b42abd --- /dev/null +++ b/utils/netguard/netguard_test.go @@ -0,0 +1,290 @@ +// Copyright 2026 LiveKit, Inc. +// +// 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 netguard + +import ( + "context" + "net" + "net/http" + "net/http/httptest" + "net/netip" + "syscall" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestIsBlockedIP(t *testing.T) { + cases := []struct { + ip string + blocked bool + }{ + // internal / reserved ranges the SSRF guard must reject + {"127.0.0.1", true}, // IPv4 loopback + {"10.0.0.1", true}, // RFC1918 + {"172.16.0.1", true}, // RFC1918 + {"192.168.1.1", true}, // RFC1918 + {"169.254.169.254", true}, // link-local including cloud metadata + {"100.64.0.1", true}, // RFC6598 CGNAT + {"::1", true}, // IPv6 loopback + {"fc00::1", true}, // IPv6 ULA + {"fe80::1", true}, // IPv6 link-local + {"64:ff9b::10.0.0.1", true}, // well-known NAT64 carrying RFC1918 + {"64:ff9b::169.254.169.254", true}, // well-known NAT64 carrying cloud metadata + {"64:ff9b::127.0.0.1", true}, // well-known NAT64 carrying loopback + {"64:ff9b::8.8.8.8", false}, // well-known NAT64 carrying a public address + {"64:ff9b:1::1", true}, // local-use NAT64 + {"64:ff9b:1::808:808", true}, // local-use NAT64, whatever it carries + {"0.1.2.3", true}, // 0.0.0.0/8 "this network" + {"240.0.0.1", true}, // 240.0.0.0/4 reserved + {"198.19.0.1", true}, // 198.18.0.0/15 benchmarking + {"192.0.0.1", true}, // 192.0.0.0/24 IETF protocol assignments + {"192.88.99.1", true}, // 192.88.99.0/24 6to4 relay anycast + {"::c0a8:101", true}, // ::/96 v4-compatible (embeds 192.168.1.1) + {"2002:c0a8:101::1", true}, // 6to4 (embeds 192.168.1.1) + {"2001::1", true}, // 2001::/32 Teredo (embeds IPv4) + {"2001:1ff::1", true}, // 2001::/23 IETF protocol assignments, outside Teredo + {"fec0::1", true}, // fec0::/10 deprecated IPv6 site-local + {"192.0.2.1", true}, // 192.0.2.0/24 TEST-NET-1 + {"198.51.100.1", true}, // 198.51.100.0/24 TEST-NET-2 + {"203.0.113.1", true}, // 203.0.113.0/24 TEST-NET-3 + {"100::1", true}, // 100::/64 discard-only + {"2001:db8::1", true}, // 2001:db8::/32 documentation + {"3fff::1", true}, // 3fff::/20 documentation + {"5f00::1", true}, // 5f00::/16 SRv6 SIDs + {"2001:200::1", false}, // just past 2001::/23 (WIDE, public) + {"::ffff:169.254.169.254", true}, // IPv4-mapped cloud metadata + {"::ffff:0:a9fe:a9fe", true}, // ::ffff:0:0:0/96 IPv4-translated (embeds 169.254.169.254) + {"::ffff:8.8.8.8", false}, // IPv4-mapped public address + // public addresses that must remain reachable + {"8.8.8.8", false}, + {"1.1.1.1", false}, + {"2606:4700:4700::1111", false}, + } + for _, c := range cases { + ip := net.ParseIP(c.ip) + require.NotNil(t, ip, "parse %s", c.ip) + require.Equal(t, c.blocked, IsBlockedIP(ip), "IsBlockedIP(%s)", c.ip) + } + + for _, ip := range []net.IP{nil, {}, {127, 0, 0}, make(net.IP, 5)} { + require.True(t, IsBlockedIP(ip), "IsBlockedIP(%#v)", ip) + } + require.False(t, IsBlockedIP(net.IPv4(8, 8, 8, 8).To4()), "4-byte form of a public address") +} + +func TestCheckHost(t *testing.T) { + for _, host := range []string{"example.com", "93.184.215.14", "2606:4700::1111", "[2606:4700::1111]", + "example.com:443", "[2606:4700::1111]:443", + } { + require.NoError(t, CheckHost(host), host) + } + for _, host := range []string{ + "localhost", "LOCALHOST.", "api.localhost", + "127.0.0.1", "10.0.0.1", "169.254.169.254", + "::1", "::ffff:10.0.0.1", "0.0.0.0", + "[::1]", "[::ffff:10.0.0.1]", + "fe80::1%eth0", "2606:4700::1111%eth0", "[2606:4700::1111%eth0]", + "127.0.0.1:80", "[::1]:80", "localhost:8080", "[fe80::1%eth0]:443", + } { + require.ErrorIs(t, CheckHost(host), ErrBlockedAddress, host) + } +} + +func TestNewDialControl(t *testing.T) { + cases := []struct { + blockPrivate bool + blocked, allowed []string + want map[string]bool + }{ + { + blockPrivate: true, + blocked: []string{"8.8.8.0/24"}, + allowed: []string{"10.1.0.0/16"}, + want: map[string]bool{ + "8.8.8.8:443": true, + "[::ffff:8.8.8.8]:443": true, + "1.1.1.1:443": false, + "10.1.2.3:443": false, + "[::ffff:10.1.2.3]:80": false, + "10.2.0.1:443": true, + "[64:ff9b::a01:203]:80": true, + "[64:ff9b::101:101]:443": false, + "[::10.1.2.3]:80": true, + "[2002:a01:203::]:80": true, + "[64:ff9b::a02:1]:80": true, + "[fe80::1%eth0]:443": true, + "[2607:f8b0::1%eth0]:443": true, + }, + }, + { + blocked: []string{"10.0.0.0/8"}, + want: map[string]bool{ + "10.0.0.1:80": true, + "[64:ff9b::a00:1]:80": true, + "[::10.0.0.1]:80": true, + "[2002:a00:1::]:80": true, + "[64:ff9b::808:808]:80": false, + "8.8.8.8:80": false, + "[fe80::1%eth0]:443": true, + "[2607:f8b0::1%eth0]:443": true, + "[::ffff:8.8.8.8%eth0]:443": true, + }, + }, + { + blockPrivate: true, + allowed: []string{"0.0.0.0/0"}, + want: map[string]bool{ + "10.0.0.1:80": false, + "127.0.0.1:80": false, + "169.254.169.254:80": false, + "[::1]:80": true, + "[::]:80": true, + }, + }, + { + blockPrivate: true, + allowed: []string{"fe80::/10"}, + want: map[string]bool{ + "[fe80::1%eth0]:80": false, + "[2607:f8b0::1%eth0]:80": true, + }, + }, + { + blocked: []string{"::ffff:8.8.8.0/120"}, + want: map[string]bool{ + "8.8.8.8:443": true, + "[::ffff:8.8.8.8]:443": true, + "8.8.9.1:443": false, + }, + }, + { + blockPrivate: true, + allowed: []string{"::ffff:10.1.0.0/112"}, + want: map[string]bool{ + "10.1.2.3:443": false, + "[::ffff:10.1.2.3]:443": false, + "10.2.0.1:443": true, + }, + }, + } + for _, c := range cases { + control := NewDialControl(c.blockPrivate, mustParseCIDRs(t, c.blocked), mustParseCIDRs(t, c.allowed)) + for address, blocked := range c.want { + checkDial(t, control, address, blocked) + } + } +} + +func TestParseCIDR(t *testing.T) { + p, err := ParseCIDR("::ffff:10.1.0.0/112") + require.NoError(t, err) + require.Equal(t, netip.MustParsePrefix("10.1.0.0/16"), p) + + for _, cidr := range []string{"10.0.0.0/33", "not-a-cidr", "::ffff:0:0/80"} { + _, err := ParseCIDR(cidr) + require.Error(t, err, cidr) + } +} + +func TestReportOnly(t *testing.T) { + type reported struct { + address string + err error + } + var got []reported + control := ReportOnly(BlockInternal, func(address string, err error) { + got = append(got, reported{address, err}) + }) + + require.NoError(t, control("tcp", "169.254.169.254:80", nil)) + require.Len(t, got, 1) + require.Equal(t, "169.254.169.254:80", got[0].address) + require.ErrorIs(t, got[0].err, ErrBlockedAddress) + + require.NoError(t, control("tcp", "8.8.8.8:443", nil)) + require.Error(t, control("tcp", "not-an-address", nil)) + require.Len(t, got, 1, "only refused addresses are reported") +} + +func TestReportOnlyContext(t *testing.T) { + type destKey struct{} + type reported struct { + dest, address string + err error + } + var got []reported + control := ReportOnlyContext(BlockInternal, func(ctx context.Context, address string, err error) { + dest, _ := ctx.Value(destKey{}).(string) + got = append(got, reported{dest, address, err}) + }) + + ctx := context.WithValue(context.Background(), destKey{}, "a") + require.NoError(t, control(ctx, "tcp", "169.254.169.254:80", nil)) + require.NoError(t, control(ctx, "tcp", "8.8.8.8:443", nil)) + require.Error(t, control(ctx, "tcp", "not-an-address", nil)) + require.Len(t, got, 1, "only refused addresses are reported") + require.Equal(t, "a", got[0].dest) + require.Equal(t, "169.254.169.254:80", got[0].address) + require.ErrorIs(t, got[0].err, ErrBlockedAddress) + + // http.Transport passes the request's context values to the dial. + srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})) + defer srv.Close() + dialer := &net.Dialer{ControlContext: control} + client := &http.Client{Transport: &http.Transport{DialContext: dialer.DialContext}} + defer client.CloseIdleConnections() + + got = nil + req, err := http.NewRequestWithContext(context.WithValue(ctx, destKey{}, "b"), http.MethodGet, srv.URL, nil) + require.NoError(t, err) + resp, err := client.Do(req) + require.NoError(t, err, "a report-only refusal must not fail the request") + require.NoError(t, resp.Body.Close()) + require.Len(t, got, 1) + require.Equal(t, "b", got[0].dest) + require.Equal(t, srv.Listener.Addr().String(), got[0].address) +} + +func TestBlockInternal(t *testing.T) { + checkDial(t, BlockInternal, "[fe80::1%eth0]:443", true) + checkDial(t, BlockInternal, "[2607:f8b0::1%eth0]:443", true) + checkDial(t, BlockInternal, "127.0.0.1:80", true) + checkDial(t, BlockInternal, "169.254.169.254:80", true) + checkDial(t, BlockInternal, "8.8.8.8:443", false) + checkDial(t, BlockInternal, "[64:ff9b::a9fe:a9fe]:80", true) + checkDial(t, BlockInternal, "[64:ff9b::808:808]:443", false) +} + +func mustParseCIDRs(t *testing.T, cidrs []string) []netip.Prefix { + t.Helper() + prefixes := make([]netip.Prefix, 0, len(cidrs)) + for _, c := range cidrs { + p, err := ParseCIDR(c) + require.NoError(t, err, c) + prefixes = append(prefixes, p) + } + return prefixes +} + +func checkDial(t *testing.T, control func(string, string, syscall.RawConn) error, address string, blocked bool) { + t.Helper() + err := control("tcp", address, nil) + if blocked { + require.ErrorIs(t, err, ErrBlockedAddress, address) + } else { + require.NoError(t, err, address) + } +}