Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Security: the shared address classifier behind the dashboard and hub URL guards and the Inbox link fetcher now refuses every IANA special-purpose range, not only the private ones. Added IPv4 `192.0.0.0/24`, `192.0.2.0/24`, `192.88.99.0/24`, `198.18.0.0/15`, `198.51.100.0/24` and `203.0.113.0/24`, and IPv6 `100::/64`, `2001::/32` (Teredo), `2001:db8::/32` and `fec0::/10`, including their IPv4-mapped, NAT64 and 6to4 forms. A host written as dot-separated numbers that is not a valid IPv4 literal (such as `1.2.3.4.5`) is refused instead of being sent to DNS. The Inbox link fetcher now uses the same classifier instead of its own range list, and the range set is listed in `src/docs/security-model.md` and `src/docs/security-threat-model.md`. Public addresses and ranges already refused are unaffected; no `100.64.0.0/10` opt-in was added because no registered hive or hub URL needs one (#19020)
27 changes: 24 additions & 3 deletions src/docs/security-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,9 +193,30 @@ compression ratio) and an XML decoder that refuses DTDs and unknown entities
(no XXE). Links dropped onto the Inbox are
fetched by the hive under an SSRF guard: http/https only, no credentials in
the URL, the hive's own DNS lookup with the connection pinned to the checked
address (any private, loopback, link-local, CGNAT, multicast, ULA or metadata
answer refuses the link), every redirect re-checked (at most 3), the body
size- and time-capped, and the environment proxy never used.
address (any answer in a refused range, listed below, refuses the link), every
redirect re-checked (at most 3), the body size- and time-capped, and the
environment proxy never used.

The same address classifier, `pkg/netguard`, is the single source of truth for
every server-side fetch of a URL a user or remote party supplies: the dashboard
and hub `isPrivateURL` guards and the Inbox link fetcher. An address is judged
by what it is, not how it is written. Decimal, octal, hex and short IPv4
spellings are parsed by value, and IPv4-mapped, NAT64 (`64:ff9b::/96`) and 6to4
(`2002::/16`) addresses are judged by the IPv4 address they carry. A host made
only of dot-separated numbers that is not a valid IPv4 literal, such as
`1.2.3.4.5`, is refused before any DNS lookup. A name that resolves to even one
refused address is refused, and a missing or failing resolver fails closed. The
refused ranges are:

| Family | Ranges |
|---|---|
| IPv4 | `0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10` (carrier-grade NAT, which includes the `100.100.100.200` metadata address), `127.0.0.0/8`, `169.254.0.0/16` (link-local, cloud metadata), `172.16.0.0/12`, `192.0.0.0/24`, `192.0.2.0/24`, `192.88.99.0/24`, `192.168.0.0/16`, `198.18.0.0/15`, `198.51.100.0/24`, `203.0.113.0/24`, `224.0.0.0/4` (multicast), `240.0.0.0/4` (reserved, includes broadcast) |
| IPv6 | `::/128`, `::1/128`, `100::/64` (discard-only), `2001::/32` (Teredo), `2001:db8::/32` (documentation), `fc00::/7` (unique local), `fe80::/10` (link-local), `fec0::/10` (site-local), `ff00::/8` (multicast) |

Names ending in `localhost` are refused as well. There is no opt-in to allow
`100.64.0.0/10`: no registered hive or hub URL uses that range. The
authoritative list is the switch and the `specialPurposePrefixes` table in
`src/pkg/netguard/netguard.go`.

### Customers: people the hive has seen

Expand Down
1 change: 1 addition & 0 deletions src/docs/security-threat-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@ Read each control's exceptions and the residual risks, not just its name.
| `ioscan` | Cleans and matches untrusted text, withholds matches, plants canaries and scans agent output for them. See [ioscan.md](ioscan.md). | Prompt injection and secret leakage before and after the agent. |
| Trajectory review | A second model compares each agent's assigned intent with its recent transcript and pauses it on drift. Fails open if the reviewer is down. | Multi-step goal drift. |
| Token budget | A seven-day budget warns at 90% and stops new tasks when exhausted. | Runaway cost. |
| Shared address classifier | One classifier, `pkg/netguard`, decides which destinations a server-side fetch of a user-supplied URL may reach. It refuses loopback, private, link-local, carrier-grade NAT, multicast, reserved and documentation ranges, IPv6 unique-local and site-local, Teredo and discard-only space, and malformed all-numeric hosts, and it judges IPv4-mapped, NAT64 and 6to4 addresses by the IPv4 address they carry. The full range list is in [security-model.md](security-model.md). | SSRF to cloud metadata and internal services through alternate address spellings. |
| Per-user-ID isolation | Each agent has its own Unix user, terminal socket and token file; the proxy attributes connections by user ID. `su-exec` is the only setuid binary, mode 4750. | Cross-agent file access; unattributed network decisions. |
| Single sign-on and terminal authorization | Ed25519-signed sessions, short-lived signed terminal assertions, per-hive authorization. | Forged hub or terminal access. |
| Hub secret and heartbeat hardening | Per-hive derived keys; heartbeats carry telemetry only, never credentials. | Blast radius of a hub compromise; cross-tenant exposure. |
Expand Down
4 changes: 2 additions & 2 deletions src/pkg/dashboard/private_url_classifier_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,15 @@ func TestIsPrivateURLSharedClassifier(t *testing.T) {
"nat64.example": {"64:ff9b::a9fe:a9fe"},
"6to4.example": {"2002:a00:1::"},
"mcast.example": {"ff05::2"},
"mixed.example": {"203.0.113.10", "fd12::1"},
"mixed.example": {"93.184.216.34", "fd12::1"},
}
orig := privateURLResolver
t.Cleanup(func() { privateURLResolver = orig })
privateURLResolver = func(_ context.Context, host string) ([]string, error) {
if a, ok := answers[host]; ok {
return a, nil
}
return []string{"203.0.113.10"}, nil
return []string{"93.184.216.34"}, nil
}

ctx := context.Background()
Expand Down
8 changes: 4 additions & 4 deletions src/pkg/dashboard/private_url_resolver_testhelper_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,10 @@ func stubPrivateURLResolver(t *testing.T, publicHosts ...string) {
}

// publicTestResolvedAddr is the address stubPrivateURLResolver returns for
// hosts a test declares public. 203.0.113.0/24 is TEST-NET-3 (RFC 5737),
// reserved for documentation, so it is guaranteed never to be routed and never
// to collide with any private range isPrivateURL blocks.
const publicTestResolvedAddr = "203.0.113.10"
// hosts a test declares public. It is a real, globally routable address:
// the shared classifier also refuses the documentation ranges (RFC 5737), so
// they cannot stand in for a public host.
const publicTestResolvedAddr = "93.184.216.34"

// TestStubPrivateURLResolverIsFailClosed is the positive control for the helper
// above: it proves the stub does not accidentally make isPrivateURL permissive.
Expand Down
4 changes: 2 additions & 2 deletions src/pkg/hub/hub_coverage_extra_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -945,7 +945,7 @@ func TestHandleContributeWSProxyNoHive(t *testing.T) {
func TestHandleContributeWSProxyInvalidHiveURL(t *testing.T) {
origResolver := privateURLResolver
privateURLResolver = func(ctx context.Context, host string) ([]string, error) {
return []string{"203.0.113.10"}, nil
return []string{"93.184.216.34"}, nil
}
t.Cleanup(func() { privateURLResolver = origResolver })

Expand All @@ -968,7 +968,7 @@ func TestHandleContributeWSProxyInvalidHiveURL(t *testing.T) {
func TestHandleContributeWSProxyForwardsToSelectedHive(t *testing.T) {
origResolver := privateURLResolver
privateURLResolver = func(ctx context.Context, host string) ([]string, error) {
return []string{"203.0.113.10"}, nil
return []string{"93.184.216.34"}, nil
}
t.Cleanup(func() { privateURLResolver = origResolver })

Expand Down
2 changes: 1 addition & 1 deletion src/pkg/hub/hub_uncovered_branches_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ func stubPublicResolver(t *testing.T) {
t.Helper()
orig := privateURLResolver
privateURLResolver = func(ctx context.Context, host string) ([]string, error) {
return []string{"203.0.113.10"}, nil
return []string{"93.184.216.34"}, nil
}
t.Cleanup(func() { privateURLResolver = orig })
}
Expand Down
4 changes: 2 additions & 2 deletions src/pkg/hub/private_url_classifier_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,15 @@ func TestIsPrivateURLSharedClassifier(t *testing.T) {
"nat64.example": {"64:ff9b::a9fe:a9fe"},
"6to4.example": {"2002:a00:1::"},
"mcast.example": {"ff05::2"},
"mixed.example": {"203.0.113.10", "fd12::1"},
"mixed.example": {"93.184.216.34", "fd12::1"},
}
orig := privateURLResolver
t.Cleanup(func() { privateURLResolver = orig })
privateURLResolver = func(_ context.Context, host string) ([]string, error) {
if a, ok := answers[host]; ok {
return a, nil
}
return []string{"203.0.113.10"}, nil
return []string{"93.184.216.34"}, nil
}

ctx := context.Background()
Expand Down
12 changes: 6 additions & 6 deletions src/pkg/hub/private_url_resolver_testhelper_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ import (
//
// stubPrivateURLResolver installs a deterministic, in-process resolver for the
// duration of one test and restores the production resolver afterwards. It
// resolves any host to publicTestResolvedAddr — a documentation-range address
// that is deliberately OUTSIDE every private prefix isPrivateURL blocks — so a
// resolves any host to publicTestResolvedAddr, a globally routable address
// that is deliberately OUTSIDE every range isPrivateURL blocks, so a
// public hostname is classified public without a single external DNS query.
//
// It resolves ONLY hosts the caller lists. Any other host returns an error,
Expand All @@ -46,10 +46,10 @@ func stubPrivateURLResolver(t *testing.T, publicHosts ...string) {
}

// publicTestResolvedAddr is the address stubPrivateURLResolver returns for
// hosts a test declares public. 203.0.113.0/24 is TEST-NET-3 (RFC 5737),
// reserved for documentation, so it is guaranteed never to be routed and never
// to collide with any private range isPrivateURL blocks.
const publicTestResolvedAddr = "203.0.113.10"
// hosts a test declares public. It is a real, globally routable address:
// the shared classifier also refuses the documentation ranges (RFC 5737), so
// they cannot stand in for a public host.
const publicTestResolvedAddr = "93.184.216.34"

// TestStubPrivateURLResolverIsFailClosed is the positive control for the helper
// above: it proves the stub does not accidentally make isPrivateURL permissive.
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/hub/selfservice_api_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ func newSelfServiceTestEnv(t *testing.T) *selfServiceTestEnv {

origResolver := privateURLResolver
privateURLResolver = func(ctx context.Context, host string) ([]string, error) {
return []string{"203.0.113.10"}, nil
return []string{"93.184.216.34"}, nil
}
t.Cleanup(func() { privateURLResolver = origResolver })

Expand Down
82 changes: 8 additions & 74 deletions src/pkg/inbox/link_fetch.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import (
"time"

"github.com/hivecommons/hive/crux/upstreamproxy"
"github.com/hivecommons/hive/pkg/netguard"
)

// Link fetch limits. A link dropped onto the Inbox is fetched by the hive
Expand Down Expand Up @@ -46,38 +47,6 @@ func linkRefused(format string, args ...any) error {
return fmt.Errorf("%w: %s", ErrLinkRefused, fmt.Sprintf(format, args...))
}

// linkBlockedPrefixes are the address ranges a link may never reach:
// loopback, private, link-local, CGNAT, multicast, reserved and
// documentation ranges, IPv6 ULA and link-local, and the cloud metadata
// addresses (169.254.169.254 and fd00:ec2::254 fall inside link-local and
// ULA; 100.100.100.200 inside CGNAT; 192.0.0.192 inside 192.0.0.0/24).
var linkBlockedPrefixes = mustPrefixes(
"0.0.0.0/8", // "this network"
"10.0.0.0/8", // RFC 1918
"100.64.0.0/10", // CGNAT (RFC 6598)
"127.0.0.0/8", // loopback
"169.254.0.0/16", // link-local, cloud metadata
"172.16.0.0/12", // RFC 1918
"192.0.0.0/24", // IETF protocol assignments
"192.0.2.0/24", // TEST-NET-1
"192.88.99.0/24", // 6to4 relay anycast
"192.168.0.0/16", // RFC 1918
"198.18.0.0/15", // benchmarking
"198.51.100.0/24", // TEST-NET-2
"203.0.113.0/24", // TEST-NET-3
"224.0.0.0/4", // multicast
"240.0.0.0/4", // reserved, broadcast
"::/128", // unspecified
"::1/128", // loopback
"100::/64", // discard-only
"2001::/32", // Teredo
"2001:db8::/32", // documentation
"fc00::/7", // unique local, fd00:ec2::254 metadata
"fe80::/10", // link-local
"fec0::/10", // site-local (deprecated)
"ff00::/8", // multicast
)

// linkBlockedHosts are names refused before any lookup.
var linkBlockedHosts = map[string]bool{
"localhost": true,
Expand All @@ -86,49 +55,14 @@ var linkBlockedHosts = map[string]bool{
"instance-data": true,
}

func mustPrefixes(list ...string) []netip.Prefix {
out := make([]netip.Prefix, len(list))
for i, s := range list {
out[i] = netip.MustParsePrefix(s)
}
return out
}

// nat64Prefix and sixToFour embed an IPv4 address that is checked too.
var (
nat64Prefix = netip.MustParsePrefix("64:ff9b::/96")
sixToFour = netip.MustParsePrefix("2002::/16")
)

// LinkAddrAllowed reports whether a link may connect to addr. IPv4-mapped,
// NAT64 and 6to4 addresses are judged by the IPv4 address they carry.
// LinkAddrAllowed reports whether a link may connect to addr. The address
// classes come from the shared classifier (pkg/netguard), the one source of
// truth for which ranges are refused: loopback, private, link-local, CGNAT,
// multicast, reserved and documentation ranges, IPv6 unique-local and
// site-local, and the cloud metadata addresses. IPv4-mapped, NAT64 and 6to4
// addresses are judged by the IPv4 address they carry.
func LinkAddrAllowed(addr netip.Addr) bool {
if !addr.IsValid() {
return false
}
addr = addr.Unmap()
if addr.Is6() {
b := addr.As16()
switch {
case nat64Prefix.Contains(addr):
if !LinkAddrAllowed(netip.AddrFrom4([4]byte{b[12], b[13], b[14], b[15]})) {
return false
}
case sixToFour.Contains(addr):
if !LinkAddrAllowed(netip.AddrFrom4([4]byte{b[2], b[3], b[4], b[5]})) {
return false
}
}
}
if addr.IsLoopback() || addr.IsPrivate() || addr.IsLinkLocalUnicast() || addr.IsLinkLocalMulticast() || addr.IsMulticast() || addr.IsUnspecified() || addr.IsInterfaceLocalMulticast() {
return false
}
for _, p := range linkBlockedPrefixes {
if p.Contains(addr) {
return false
}
}
return true
return !netguard.Denied(addr)
}

// ValidateLinkURL parses a submitted link and applies the rules that need no
Expand Down
78 changes: 78 additions & 0 deletions src/pkg/netguard/netguard.go
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,14 @@ const (
ReasonThisNetwork = "this-network"
ReasonBroadcast = "broadcast"
ReasonLocalName = "local host name"
// ReasonSpecialPurpose names an IANA special-purpose range that is not
// globally routable and has no more specific reason: documentation,
// benchmarking, protocol assignments, Teredo, discard-only, the 6to4
// relay anycast block and deprecated site-local space.
ReasonSpecialPurpose = "special-purpose"
// ReasonNumericHost names a host written as dot-separated numbers that
// is not a valid IPv4 literal (for example 1.2.3.4.5).
ReasonNumericHost = "malformed numeric host"
)

var (
Expand All @@ -49,8 +57,34 @@ var (
// address that is classified in its own right.
nat64Prefix = netip.MustParsePrefix("64:ff9b::/96")
sixToFour = netip.MustParsePrefix("2002::/16")

// specialPurposePrefixes is the table of IANA special-purpose ranges
// that no public service lives in. It is the range set documented in
// src/docs/security-model.md; keep the two in step. The ranges the
// switch in DenyReason already names (loopback, private, link-local,
// multicast, CGNAT, this-network, reserved) are not repeated here.
specialPurposePrefixes = mustPrefixes(
"192.0.0.0/24", // IETF protocol assignments (RFC 6890)
"192.0.2.0/24", // TEST-NET-1 documentation (RFC 5737)
"192.88.99.0/24", // 6to4 relay anycast (RFC 7526, deprecated)
"198.18.0.0/15", // benchmarking (RFC 2544)
"198.51.100.0/24", // TEST-NET-2 documentation (RFC 5737)
"203.0.113.0/24", // TEST-NET-3 documentation (RFC 5737)
"100::/64", // discard-only (RFC 6666)
"2001::/32", // Teredo (RFC 4380)
"2001:db8::/32", // documentation (RFC 3849)
"fec0::/10", // site-local, deprecated (RFC 3879)
)
)

func mustPrefixes(list ...string) []netip.Prefix {
out := make([]netip.Prefix, len(list))
for i, s := range list {
out[i] = netip.MustParsePrefix(s)
}
return out
}

// DenyReason names the class that bars addr, or "" when addr is globally
// routable and may be fetched. An invalid address is refused.
func DenyReason(addr netip.Addr) string {
Expand Down Expand Up @@ -93,6 +127,11 @@ func DenyReason(addr netip.Addr) string {
case reservedV4.Contains(addr):
return ReasonBroadcast
}
for _, p := range specialPurposePrefixes {
if p.Contains(addr) {
return ReasonSpecialPurpose
}
}
return ""
}

Expand Down Expand Up @@ -240,9 +279,48 @@ func HostDenyReason(host string) (reason string, literal bool) {
if addr, ok := ParseHostLiteral(h); ok {
return DenyReason(addr), true
}
if numericDotted(h) {
return ReasonNumericHost, false
}
return "", false
}

// numericDotted reports whether host has at least one dot and every label is
// a decimal number or a 0x hex number, the shapes inet_aton reads as IPv4
// parts. A host like that which ParseHostLiteral rejected (1.2.3.4.5,
// 256.1.1.1, 08.0.0.1) is not a name any public service has, so it is refused
// rather than handed to DNS.
func numericDotted(host string) bool {
if !strings.Contains(host, ".") {
return false
}
for _, label := range strings.Split(host, ".") {
if !numericLabel(label) {
return false
}
}
return true
}

func numericLabel(label string) bool {
digits := label
isDigit := func(c rune) bool { return c >= '0' && c <= '9' }
if strings.HasPrefix(label, "0x") {
digits = label[len("0x"):]
isDigit = func(c rune) bool { return c >= '0' && c <= '9' || c >= 'a' && c <= 'f' }
}
if digits == "" {
// "0x" alone is zero to inet_aton; an empty label is not a number.
return label != ""
}
for _, c := range digits {
if !isDigit(c) {
return false
}
}
return true
}

// Resolver returns the addresses a host name resolves to, as text.
type Resolver func(ctx context.Context, host string) ([]string, error)

Expand Down
Loading
Loading