Add an egress CIDR allowlist to the SSRF guard (closes #204) (#217)

internal/delivery/client_ssrf_test.go

@@ -18,8 +18,9 @@ func newSSRFTestEngine() *delivery.Engine {
 	log := slog.New(slog.DiscardHandler)
 
 	client := &http.Client{
-		Timeout:   30 * time.Second,
-		Transport: delivery.NewSSRFSafeTransport(),
+		Timeout: 30 * time.Second,
+		Transport: delivery.NewTestGuard().
+			NewSSRFSafeTransport(),
 	}
 
 	return delivery.NewTestEngine(log, client, 1)
@@ -36,8 +37,8 @@ func TestClientForConfig_TimeoutKeepsSSRFGuard(t *testing.T) {
 	engine := newSSRFTestEngine()
 
 	blocked := []string{
-		"http://127.0.0.1/hook",
-		"http://169.254.169.254/latest/meta-data/",
+		loopbackHookURL,
+		metadataURL,
 		"http://[fe80::1]/hook",
 	}
 

internal/delivery/engine.go

@@ -121,6 +121,7 @@ type EngineParams struct {
 	DB        *database.Database
 	DBManager *database.WebhookDBManager
 	Logger    *logger.Logger
+	SSRFGuard *Guard
 }
 
 // Engine processes queued deliveries in the background
@@ -176,7 +177,7 @@ func New(
 
 	e.initTargets(&http.Client{
 		Timeout:   httpClientTimeout,
-		Transport: NewSSRFSafeTransport(),
+		Transport: params.SSRFGuard.NewSSRFSafeTransport(),
 	})
 
 	e.registerHooks(lc)

internal/delivery/export_test.go

@@ -5,6 +5,7 @@ import (
 	"log/slog"
 	"net"
 	"net/http"
+	"net/netip"
 	"time"
 
 	"go.uber.org/fx"
@@ -38,6 +39,26 @@ func ExportIsBlockedIP(ip net.IP) bool {
 	return isBlockedIP(ip)
 }
 
+// NewTestGuard builds an SSRF Guard from an explicit egress
+// allowlist, without going through config. Passing no prefixes
+// yields the default guard, which blocks every private/reserved
+// range.
+func NewTestGuard(allowed ...netip.Prefix) *Guard {
+	return &Guard{allowed: allowed}
+}
+
+// ExportCheckIP exposes the guard's single decision point, so a
+// test can assert the policy both the validator and the dialer
+// inherit without needing a live destination.
+func (g *Guard) ExportCheckIP(ip net.IP) error {
+	return g.checkIP(ip)
+}
+
+// ExportAlwaysBlockedNetworks exposes alwaysBlockedNetworks.
+func ExportAlwaysBlockedNetworks() []*net.IPNet {
+	return alwaysBlockedNetworks
+}
+
 // ExportBlockedNetworks exposes blockedNetworks.
 func ExportBlockedNetworks() []*net.IPNet {
 	return blockedNetworks

internal/delivery/ssrf.go

@@ -6,8 +6,11 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"net/netip"
 	"net/url"
 	"time"
+
+	"sneak.berlin/go/webhooker/internal/config"
 )
 
 const (
@@ -25,20 +28,83 @@ var (
 	errBlockedIP = errors.New(
 		"blocked private/reserved IP range",
 	)
+	errBlockedMetadata = errors.New(
+		"blocked link-local or cloud instance metadata " +
+			"address: ALLOWED_EGRESS_CIDRS cannot open it",
+	)
 	errInvalidScheme = errors.New(
 		"only http and https are allowed",
 	)
 )
 
 // blockedNetworks contains all private/reserved IP ranges
-// that should be blocked to prevent SSRF attacks.
+// that should be blocked to prevent SSRF attacks. An operator
+// can permit specific blocks out of this set with
+// ALLOWED_EGRESS_CIDRS; see Guard.
 //
 //nolint:gochecknoglobals // package-level network list is appropriate here
 var blockedNetworks []*net.IPNet
 
+// alwaysBlockedNetworks are the ranges no configuration can
+// open: the link-local blocks and the cloud instance metadata
+// endpoints that live outside them. Reaching one is credential
+// or user-data theft rather than delivery to an internal
+// service, so a supplied CIDR that covers such an address still
+// leaves it blocked.
+//
+// Inclusion criterion — an address belongs here only if BOTH
+// hold, and every entry below satisfies both:
+//
+//  1. It is a fixed address assigned by the provider, or a
+//     range reserved by IANA — never one the operator chose.
+//     That is what makes a host route free: it cannot collide
+//     with anything the operator runs.
+//  2. Reaching it discloses credentials, or user data or
+//     bootstrap material — something granting onward access, or
+//     not cheaply rotated.
+//
+// Both halves are load-bearing, so use them to refuse a
+// candidate and say why. An endpoint disclosing only the
+// operator's own inventory (instance id, region, disks, NICs)
+// fails (2): letting a delivery target reach the operator's own
+// infrastructure is the feature ALLOWED_EGRESS_CIDRS exists to
+// provide. But (2) is not "IAM credentials only" either —
+// fd00:42::42 serves /user_data and /conf rather than tokens,
+// and user data routinely carries bootstrap secrets. An address
+// stays out if it fails (1) however well it clears (2): a host
+// route inside a block operators really assign from, such as
+// 10.0.0.0/8, can collide with a real internal service and
+// forfeits the justification in (1).
+//
+// A publicly routable unicast address does not belong here even
+// when it clears both halves. Nothing in this list can be
+// reopened, so putting a public address here leaves the operator
+// no escape hatch at all — the condition ALLOWED_EGRESS_CIDRS
+// exists to remove. Default-block it in blockedNetworks instead,
+// which an allowlist can override.
+//
+// This is a criterion, not an enumeration of every metadata
+// address in existence.
+//
+// Every entry is either already in blockedNetworks — this list is
+// what makes it unconditional — or an alternate encoding of
+// 169.254.169.254 that Contains does not match against
+// 169.254.0.0/16. Every entry outside the link-local blocks is a
+// /32 or /128 host route, so blocking it costs an operator
+// nothing else on the surrounding network.
+//
+// Derive membership from the address, never from the vendor's
+// prose. Several providers call these endpoints "link-local" or
+// even "localhost" in their own documentation while the address
+// is a ULA outside fe80::/10, so a set derived from the docs
+// comes out wrong.
+//
+//nolint:gochecknoglobals // package-level network list is appropriate here
+var alwaysBlockedNetworks []*net.IPNet
+
 //nolint:gochecknoinits // init is the idiomatic way to parse CIDRs once at startup
 func init() {
-	cidrs := []string{
+	blockedNetworks = mustParseCIDRs([]string{
 		"127.0.0.0/8",
 		"10.0.0.0/8",
 		"172.16.0.0/12",
@@ -56,7 +122,72 @@ func init() {
 		"::1/128",
 		"fc00::/7",
 		"fe80::/10",
-	}
+	})
+
+	// Every entry is named. The set must not grow or shrink
+	// without a matching change to
+	// TestAlwaysBlockedNetworks_PinnedSet.
+	//
+	// The IPv4-mapped form ::ffff:169.254.169.254 needs no
+	// entry: net.IPNet.Contains normalises it via To4() before
+	// comparing, so 169.254.0.0/16 already matches it. To4()
+	// does not normalise the IPv4-compatible or NAT64 forms,
+	// which is why those are listed separately.
+	alwaysBlockedNetworks = mustParseCIDRs([]string{
+		// IPv4 link-local, carrying the 169.254.169.254
+		// metadata service used by AWS, Azure, DigitalOcean,
+		// Hetzner, OpenStack and others. Not Alibaba, which uses
+		// 100.100.100.200 below exclusively.
+		"169.254.0.0/16",
+		// IPv6 link-local, its IPv6 counterpart.
+		"fe80::/10",
+
+		// IPv6 metadata endpoints in ULA space. Each is a host
+		// route, and fd00::/8 is an ordinary block for an
+		// operator to allowlist, so without these entries that
+		// one allowlist line hands out cloud credentials on
+		// every provider below.
+		//
+		// AWS IPv6 IMDS.
+		"fd00:ec2::254/128",
+		// AWS EKS Pod Identity Agent, which issues pod identity
+		// credentials. A second AWS endpoint, distinct from
+		// IMDS above. AWS's own docs call it "localhost".
+		"fd00:ec2::23/128",
+		// GCP metadata server for IPv6-only instances.
+		"fd20:ce::254/128",
+		// Oracle OCI IMDS, serving /opc/v2 instance principals.
+		"fd00:c1::a9fe:a9fe/128",
+		// Scaleway metadata, serving /user_data and /conf.
+		"fd00:42::42/128",
+		// Linode/Akamai metadata. Akamai's docs call it
+		// "link-local"; it is not.
+		"fd00:a9fe:a9fe::1/128",
+
+		// IPv4 metadata endpoints outside link-local.
+		//
+		// Alibaba Cloud metadata. It sits in CGNAT
+		// 100.64.0.0/10, which Tailscale also uses, so an
+		// operator allowlisting a Tailscale peer's range would
+		// otherwise reopen it.
+		"100.100.100.200/32",
+		// Oracle Cloud Classic metadata. Inside the blocked
+		// 192.0.0.0/24, so this entry is what stops an
+		// allowlist from opening it.
+		"192.0.0.192/32",
+
+		// 169.254.169.254 as an IPv4-compatible IPv6 address.
+		"::a9fe:a9fe/128",
+		// 169.254.169.254 behind the NAT64 well-known prefix.
+		"64:ff9b::a9fe:a9fe/128",
+	})
+}
+
+// mustParseCIDRs parses a list of CIDR literals, panicking on a
+// bad one. The inputs are compile-time constants, so a failure
+// is a programming error rather than a runtime condition.
+func mustParseCIDRs(cidrs []string) []*net.IPNet {
+	networks := make([]*net.IPNet, 0, len(cidrs))
 
 	for _, cidr := range cidrs {
 		_, network, err := net.ParseCIDR(cidr)
@@ -67,16 +198,15 @@ func init() {
 			))
 		}
 
-		blockedNetworks = append(
-			blockedNetworks, network,
-		)
+		networks = append(networks, network)
 	}
+
+	return networks
 }
 
-// isBlockedIP checks whether an IP address falls within
-// any blocked private/reserved network range.
-func isBlockedIP(ip net.IP) bool {
-	for _, network := range blockedNetworks {
+// matchesAny reports whether ip falls inside any of networks.
+func matchesAny(networks []*net.IPNet, ip net.IP) bool {
+	for _, network := range networks {
 		if network.Contains(ip) {
 			return true
 		}
@@ -85,9 +215,40 @@ func isBlockedIP(ip net.IP) bool {
 	return false
 }
 
+// isBlockedIP checks whether an IP address falls within
+// any blocked private/reserved network range, before any
+// operator allowlist is considered.
+func isBlockedIP(ip net.IP) bool {
+	return matchesAny(blockedNetworks, ip)
+}
+
+// Guard makes every SSRF decision in the process.
+//
+// It holds the operator's ALLOWED_EGRESS_CIDRS allowlist and
+// applies it in exactly one place, checkIP, which both the
+// target-creation validator (ValidateTargetURL) and the delivery
+// dialer call. Routing both through the same function is the
+// point: when the two paths decided separately they drifted and
+// disagreed, which is what made a target creatable but
+// undeliverable.
+//
+// The guard is always on. The allowlist only ever adds specific
+// networks to what the default blocklist refuses, and no
+// configuration turns the guard off wholesale.
+type Guard struct {
+	// allowed is the operator's ALLOWED_EGRESS_CIDRS. Empty
+	// (the default) means the default blocklist stands as-is.
+	allowed []netip.Prefix
+}
+
+// NewGuard builds the process-wide SSRF guard from configuration.
+func NewGuard(cfg *config.Config) *Guard {
+	return &Guard{allowed: cfg.AllowedEgressCIDRs}
+}
+
 // ValidateTargetURL checks that an HTTP delivery target
 // URL is safe from SSRF attacks.
-func ValidateTargetURL(
+func (g *Guard) ValidateTargetURL(
 	ctx context.Context, targetURL string,
 ) error {
 	parsed, err := url.Parse(targetURL)
@@ -111,36 +272,79 @@ func ValidateTargetURL(
 	}
 
 	if ip := net.ParseIP(host); ip != nil {
-		return checkBlockedIP(ip)
+		return g.checkIP(ip)
 	}
 
-	return validateHostname(ctx, host)
+	return g.validateHostname(ctx, host)
 }
 
-func validateScheme(scheme string) error {
-	if scheme != "http" && scheme != "https" {
+// NewSSRFSafeTransport creates an http.Transport with a
+// custom DialContext that refuses connections to any address
+// this guard blocks. It resolves and checks at dial time, so a
+// name that passed validation but now answers with a blocked
+// address (DNS rebinding) is still refused.
+func (g *Guard) NewSSRFSafeTransport() *http.Transport {
+	return &http.Transport{
+		DialContext: g.ssrfDialContext,
+	}
+}
+
+// allows reports whether ip falls inside the operator's
+// configured egress allowlist.
+func (g *Guard) allows(ip net.IP) bool {
+	if len(g.allowed) == 0 {
+		return false
+	}
+
+	addr, ok := netip.AddrFromSlice(ip)
+	if !ok {
+		return false
+	}
+
+	// Config unmaps every parsed prefix, so an IPv4-mapped
+	// address has to be unmapped too or it would never match.
+	addr = addr.Unmap()
+
+	for _, prefix := range g.allowed {
+		if prefix.Contains(addr) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// checkIP is the single point at which SSRF policy is decided.
+//
+// The order is the policy:
+//
+//  1. alwaysBlockedNetworks is refused before the allowlist is
+//     consulted, so no configured CIDR reaches link-local or a
+//     cloud instance metadata endpoint.
+//  2. The allowlist is consulted next, so a listed private
+//     network becomes reachable.
+//  3. Everything else keeps the default blocklist's answer.
+func (g *Guard) checkIP(ip net.IP) error {
+	if matchesAny(alwaysBlockedNetworks, ip) {
 		return fmt.Errorf(
-			"unsupported URL scheme %q: %w",
-			scheme, errInvalidScheme,
+			"target IP %s: %w", ip, errBlockedMetadata,
 		)
 	}
 
-	return nil
-}
+	if g.allows(ip) {
+		return nil
+	}
 
-func checkBlockedIP(ip net.IP) error {
 	if isBlockedIP(ip) {
 		return fmt.Errorf(
-			"target IP %s is in a blocked "+
-				"private/reserved range: %w",
-			ip, errBlockedIP,
+			"target IP %s: %w", ip, errBlockedIP,
 		)
 	}
 
 	return nil
 }
 
-func validateHostname(
+func (g *Guard) validateHostname(
 	ctx context.Context, host string,
 ) error {
 	dnsCtx, cancel := context.WithTimeout(
@@ -165,11 +369,11 @@ func validateHostname(
 	}
 
 	for _, ipAddr := range ips {
-		if isBlockedIP(ipAddr.IP) {
+		err = g.checkIP(ipAddr.IP)
+		if err != nil {
 			return fmt.Errorf(
-				"hostname %q resolves to blocked "+
-					"IP %s: %w",
-				host, ipAddr.IP, errBlockedIP,
+				"hostname %q resolves to a blocked address: %w",
+				host, err,
 			)
 		}
 	}
@@ -177,16 +381,7 @@ func validateHostname(
 	return nil
 }
 
-// NewSSRFSafeTransport creates an http.Transport with a
-// custom DialContext that blocks connections to
-// private/reserved IP addresses.
-func NewSSRFSafeTransport() *http.Transport {
-	return &http.Transport{
-		DialContext: ssrfDialContext,
-	}
-}
-
-func ssrfDialContext(
+func (g *Guard) ssrfDialContext(
 	ctx context.Context,
 	network, addr string,
 ) (net.Conn, error) {
@@ -209,11 +404,11 @@ func ssrfDialContext(
 	}
 
 	for _, ipAddr := range ips {
-		if isBlockedIP(ipAddr.IP) {
+		err = g.checkIP(ipAddr.IP)
+		if err != nil {
 			return nil, fmt.Errorf(
-				"ssrf: connection to %s (%s) "+
-					"blocked: %w",
-				host, ipAddr.IP, errBlockedIP,
+				"ssrf: connection to %s blocked: %w",
+				host, err,
 			)
 		}
 	}
@@ -225,3 +420,14 @@ func ssrfDialContext(
 		net.JoinHostPort(ips[0].IP.String(), port),
 	)
 }
+
+func validateScheme(scheme string) error {
+	if scheme != "http" && scheme != "https" {
+		return fmt.Errorf(
+			"unsupported URL scheme %q: %w",
+			scheme, errInvalidScheme,
+		)
+	}
+
+	return nil
+}

internal/delivery/ssrf_allowlist_test.go

@@ -0,0 +1,562 @@
+package delivery_test
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"net/url"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/webhooker/internal/delivery"
+)
+
+// Addresses the SSRF tests in this package share.
+const (
+	// metadataIP is the cloud instance metadata address, and
+	// metadataURL an endpoint on it. The guard must never reach
+	// either, whatever an operator lists.
+	metadataIP  = "169.254.169.254"
+	metadataURL = "http://" + metadataIP + "/latest/meta-data/"
+
+	// loopbackHookURL is a target on this host: blocked by
+	// default, reachable only once an operator allowlists
+	// loopback.
+	loopbackHookURL = "http://127.0.0.1/hook"
+
+	// publicIP is an ordinary public address, which the guard
+	// permits with or without an allowlist.
+	publicIP = "93.184.216.34"
+
+	// allowAllIPv4 and allowAllIPv6 are the widest allowlist
+	// entries expressible: the whole internet, in each family.
+	// Nothing unconditionally blocked may be reachable under
+	// them.
+	allowAllIPv4 = "0.0.0.0/0"
+	allowAllIPv6 = "::/0"
+
+	// allowAllULA is the ordinary ULA block an operator lists to
+	// reach their own IPv6 network. Several providers park a
+	// metadata endpoint inside it.
+	allowAllULA = "fd00::/8"
+
+	// metadataRefusalClause is the part of the refusal that only
+	// alwaysBlockedNetworks produces. Asserting it, rather than
+	// the bare word "blocked", is what proves the unconditional
+	// set did the refusing and not the default blocklist.
+	metadataRefusalClause = "ALLOWED_EGRESS_CIDRS cannot open it"
+)
+
+// TestGuardAllowlist_PermittedCIDRDelivers proves the escape
+// hatch actually works end to end: with 127.0.0.0/8 allowed, the
+// guard's own transport connects to a loopback server and gets a
+// response back. The default guard, given the identical URL,
+// refuses it — so the delivery succeeds because of the allowlist
+// and nothing else.
+func TestGuardAllowlist_PermittedCIDRDelivers(t *testing.T) {
+	t.Parallel()
+
+	srv := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusNoContent)
+		},
+	))
+	t.Cleanup(srv.Close)
+
+	// httptest listens on loopback, which the default blocklist
+	// covers: exactly the "forward to a service on this host"
+	// case the allowlist exists for.
+	requireLoopback(t, srv.URL)
+
+	guard := delivery.NewTestGuard(
+		netip.MustParsePrefix("127.0.0.0/8"),
+	)
+
+	require.NoError(t,
+		guard.ValidateTargetURL(context.Background(), srv.URL),
+		"an allowlisted loopback target must pass validation",
+	)
+
+	client := &http.Client{
+		Timeout:   5 * time.Second,
+		Transport: guard.NewSSRFSafeTransport(),
+	}
+
+	req, err := http.NewRequestWithContext(
+		context.Background(), http.MethodPost, srv.URL, nil,
+	)
+	require.NoError(t, err)
+
+	resp, err := client.Do(req)
+	require.NoError(t,
+		err, "an allowlisted loopback target must be deliverable",
+	)
+
+	defer func() { _ = resp.Body.Close() }()
+
+	assert.Equal(t, http.StatusNoContent, resp.StatusCode)
+
+	// The same URL through the default guard must still fail, or
+	// this test would pass without the allowlist doing anything.
+	assert.Error(t,
+		delivery.NewTestGuard().ValidateTargetURL(
+			context.Background(), srv.URL,
+		),
+		"without the allowlist the same target must be refused",
+	)
+}
+
+// TestGuardAllowlist_UnlistedPrivateStillRefused proves the
+// allowlist grants only what it names. A guard that opens one
+// private block must keep refusing every other one, at both the
+// validation and the delivery entry point.
+func TestGuardAllowlist_UnlistedPrivateStillRefused(t *testing.T) {
+	t.Parallel()
+
+	// Only 10.1.0.0/16 is open — a narrow block inside a much
+	// wider private range, so the test can tell "permits the
+	// listed block" from "permits anything private".
+	guard := delivery.NewTestGuard(
+		netip.MustParsePrefix("10.1.0.0/16"),
+	)
+
+	refused := []string{
+		"http://192.168.1.10/hook",
+		"http://172.16.0.1/hook",
+		loopbackHookURL,
+		"http://[fc00::1]/hook",
+		"http://100.64.0.1/hook",
+		// Private, adjacent to the allowed block, outside it.
+		"http://10.2.0.1/hook",
+	}
+
+	for _, target := range refused {
+		t.Run(target, func(t *testing.T) {
+			t.Parallel()
+
+			err := guard.ValidateTargetURL(
+				context.Background(), target,
+			)
+			require.Error(t,
+				err, "%s is not allowlisted and must be refused",
+				target,
+			)
+			assert.Contains(t, err.Error(), "blocked")
+
+			assertDialRefused(t, guard, target)
+		})
+	}
+
+	// The block that is listed must in fact be permitted, so the
+	// refusals above are selective rather than a guard that
+	// ignores its allowlist entirely.
+	assert.NoError(t,
+		guard.ValidateTargetURL(
+			context.Background(), "http://10.1.2.3/hook",
+		),
+		"the allowlisted block must be permitted",
+	)
+}
+
+// TestGuardAllowlist_MetadataAlwaysRefused is the load-bearing
+// case: cloud instance metadata endpoints are credential theft
+// rather than delivery to an internal service, so no allowlist
+// reaches one. Every guard below names a CIDR that covers its
+// target — including 0.0.0.0/0, ::/0, and the ordinary ULA and
+// CGNAT blocks an operator would really list — and the address
+// must stay refused anyway, on both the validation and the
+// delivery path.
+func TestGuardAllowlist_MetadataAlwaysRefused(t *testing.T) {
+	t.Parallel()
+
+	for _, tt := range metadataAlwaysRefusedCases() {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			guard := delivery.NewTestGuard(
+				netip.MustParsePrefix(tt.allow),
+			)
+
+			err := guard.ValidateTargetURL(
+				context.Background(), tt.target,
+			)
+			require.Error(t,
+				err,
+				"%s must stay blocked even though %s covers it",
+				tt.target, tt.allow,
+			)
+			assert.Contains(t,
+				err.Error(),
+				metadataRefusalClause,
+				"the refusal must say why it cannot be opened",
+			)
+
+			// The metadata clause, not just "blocked": that is
+			// what distinguishes the unconditional set from the
+			// ordinary blocklist.
+			assertDialRefusedWith(
+				t, guard, tt.target, metadataRefusalClause,
+			)
+		})
+	}
+}
+
+// metadataAlwaysRefusedCase is one (allowlist, target) pair that
+// must be refused: allow covers target, and target must stay
+// blocked regardless.
+type metadataAlwaysRefusedCase struct {
+	name   string
+	allow  string
+	target string
+}
+
+// metadataAlwaysRefusedCases enumerates every unconditionally
+// blocked address together with an allowlist entry that would
+// otherwise reach it. Split by family of address only to stay
+// under the function-length limit.
+func metadataAlwaysRefusedCases() []metadataAlwaysRefusedCase {
+	cases := linkLocalRefusedCases()
+	cases = append(cases, ulaMetadataRefusedCases()...)
+	cases = append(cases, ipv4MetadataRefusedCases()...)
+
+	return append(cases, encodedMetadataRefusedCases()...)
+}
+
+// linkLocalRefusedCases covers the link-local blocks, including
+// an operator naming the metadata address outright.
+func linkLocalRefusedCases() []metadataAlwaysRefusedCase {
+	return []metadataAlwaysRefusedCase{
+		{
+			name:   "exact metadata host",
+			allow:  "169.254.169.254/32",
+			target: metadataURL,
+		},
+		{
+			name:   "whole link-local block",
+			allow:  "169.254.0.0/16",
+			target: metadataURL,
+		},
+		{
+			name:   "supernet covering link-local",
+			allow:  "169.0.0.0/8",
+			target: metadataURL,
+		},
+		{
+			name:   "the entire IPv4 internet",
+			allow:  allowAllIPv4,
+			target: metadataURL,
+		},
+		{
+			name:   "other link-local address",
+			allow:  allowAllIPv4,
+			target: "http://169.254.1.1/",
+		},
+		{
+			name:   "IPv6 link-local",
+			allow:  allowAllIPv6,
+			target: "http://[fe80::1]/",
+		},
+	}
+}
+
+// ulaMetadataRefusedCases covers the metadata endpoints parked
+// in ULA space. Every one is opened by the single ordinary
+// allowlist entry fd00::/8, which is the whole reason they need
+// their own /128 host routes: fe80::/10 does not cover a ULA,
+// whatever the vendor's documentation calls the address.
+func ulaMetadataRefusedCases() []metadataAlwaysRefusedCase {
+	return []metadataAlwaysRefusedCase{
+		{
+			name:   "AWS IPv6 IMDS under an allowlisted ULA block",
+			allow:  allowAllULA,
+			target: "http://[fd00:ec2::254]/latest/meta-data/",
+		},
+		{
+			// A second AWS credential endpoint, distinct from
+			// IMDS. AWS's own docs call this one "localhost".
+			name:   "AWS EKS Pod Identity under an allowlisted ULA block",
+			allow:  allowAllULA,
+			target: "http://[fd00:ec2::23]/v1/credentials",
+		},
+		{
+			name:   "GCP IPv6 metadata under an allowlisted ULA block",
+			allow:  allowAllULA,
+			target: "http://[fd20:ce::254]/computeMetadata/v1/",
+		},
+		{
+			name:   "Oracle OCI IPv6 IMDS under an allowlisted ULA block",
+			allow:  allowAllULA,
+			target: "http://[fd00:c1::a9fe:a9fe]/opc/v2/instance/",
+		},
+		{
+			name:   "Scaleway IPv6 metadata under an allowlisted ULA block",
+			allow:  allowAllULA,
+			target: "http://[fd00:42::42]/conf",
+		},
+		{
+			// Akamai's docs call this "link-local"; it is a ULA,
+			// so fe80::/10 does not cover it.
+			name:   "Linode IPv6 metadata under an allowlisted ULA block",
+			allow:  allowAllULA,
+			target: "http://[fd00:a9fe:a9fe::1]/v1/instance",
+		},
+	}
+}
+
+// ipv4MetadataRefusedCases covers the IPv4 metadata endpoints
+// that sit outside link-local: one in CGNAT and one in the
+// blocked 192.0.0.0/24, each reachable only through an allowlist
+// that this set overrides.
+func ipv4MetadataRefusedCases() []metadataAlwaysRefusedCase {
+	return []metadataAlwaysRefusedCase{
+		{
+			// Tailscale uses 100.64.0.0/10, so an operator
+			// forwarding to a Tailscale peer lists exactly this.
+			name:   "Alibaba metadata under allowlisted CGNAT",
+			allow:  "100.64.0.0/10",
+			target: "http://100.100.100.200/latest/meta-data/",
+		},
+		{
+			// Inside the already-blocked 192.0.0.0/24, so only
+			// an allowlist can reach it — and must not.
+			name:   "Oracle Cloud Classic metadata under 0.0.0.0/0",
+			allow:  allowAllIPv4,
+			target: "http://192.0.0.192/latest/meta-data/",
+		},
+	}
+}
+
+// encodedMetadataRefusedCases covers the alternate IPv6
+// encodings of 169.254.169.254.
+func encodedMetadataRefusedCases() []metadataAlwaysRefusedCase {
+	return []metadataAlwaysRefusedCase{
+		{
+			// To4() does not normalise the IPv4-compatible form,
+			// so this needs its own always-blocked entry.
+			name:   "IPv4-compatible IPv6 form of the metadata IP",
+			allow:  allowAllIPv6,
+			target: "http://[::a9fe:a9fe]/latest/meta-data/",
+		},
+		{
+			// Nor the NAT64 well-known prefix form.
+			name:   "NAT64 form of the metadata IP",
+			allow:  allowAllIPv6,
+			target: "http://[64:ff9b::a9fe:a9fe]/latest/meta-data/",
+		},
+		{
+			// Already refused before this change: IPNet.Contains
+			// calls To4() first, so the mapped form matches
+			// 169.254.0.0/16. Pinned so it cannot regress.
+			//
+			// Allowed under 0.0.0.0/0 rather than ::/0: allows()
+			// unmaps before matching, so ::/0 would not cover the
+			// unmapped v4 address and the case would not prove
+			// the allowlist was overridden.
+			name:   "IPv4-mapped IPv6 form of the metadata IP",
+			allow:  allowAllIPv4,
+			target: "http://[::ffff:169.254.169.254]/latest/meta-data/",
+		},
+	}
+}
+
+// TestGuardAllowlist_PublicUnaffected asserts the allowlist does
+// not narrow anything: public addresses were reachable before it
+// existed and stay reachable, whether or not a list is set.
+func TestGuardAllowlist_PublicUnaffected(t *testing.T) {
+	t.Parallel()
+
+	guards := map[string]*delivery.Guard{
+		"default": delivery.NewTestGuard(),
+		"with allowlist": delivery.NewTestGuard(
+			netip.MustParsePrefix("10.0.0.0/8"),
+		),
+	}
+
+	for name, guard := range guards {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			assert.NoError(t,
+				guard.ValidateTargetURL(
+					context.Background(),
+					"http://"+publicIP+"/webhook",
+				),
+			)
+		})
+	}
+}
+
+// TestGuardCheckIP_BothPathsShareOneDecision asserts that the
+// validator and the dialer are not two policies that happen to
+// agree: both are defined in terms of checkIP, so the exported
+// decision function is the whole answer for a given address.
+func TestGuardCheckIP_BothPathsShareOneDecision(t *testing.T) {
+	t.Parallel()
+
+	guard := delivery.NewTestGuard(
+		netip.MustParsePrefix("10.0.0.0/8"),
+	)
+
+	tests := []struct {
+		ip      string
+		allowed bool
+	}{
+		{"10.1.2.3", true},
+		{publicIP, true},
+		{"192.168.1.1", false},
+		{"127.0.0.1", false},
+		{metadataIP, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.ip, func(t *testing.T) {
+			t.Parallel()
+
+			ip := net.ParseIP(tt.ip)
+			require.NotNil(t, ip)
+
+			decision := guard.ExportCheckIP(ip)
+
+			validation := guard.ValidateTargetURL(
+				context.Background(), "http://"+hostFor(tt.ip)+"/x",
+			)
+
+			if tt.allowed {
+				require.NoError(t, decision)
+				require.NoError(t, validation)
+
+				return
+			}
+
+			require.Error(t, decision)
+			require.Error(t, validation,
+				"validation must refuse what checkIP refuses",
+			)
+		})
+	}
+}
+
+// TestAlwaysBlockedNetworks_PinnedSet pins the unconditional set
+// exactly, so it cannot quietly grow or shrink.
+//
+// It stays deliberately small. Everything else in the default
+// blocklist is an operator's own network and must remain
+// openable, or the escape hatch would not work — which is why
+// the metadata endpoints outside the link-local range are host
+// routes rather than the blocks that contain them.
+func TestAlwaysBlockedNetworks_PinnedSet(t *testing.T) {
+	t.Parallel()
+
+	nets := delivery.ExportAlwaysBlockedNetworks()
+
+	got := make([]string, 0, len(nets))
+	for _, n := range nets {
+		got = append(got, n.String())
+	}
+
+	want := []string{
+		// IPv4 link-local: the 169.254.169.254 metadata
+		// service on AWS, Azure and others.
+		"169.254.0.0/16",
+		// IPv6 link-local.
+		"fe80::/10",
+		// AWS IPv6 IMDS, inside the ULA space an operator may
+		// legitimately allowlist.
+		"fd00:ec2::254/128",
+		// AWS EKS Pod Identity Agent, likewise ULA.
+		"fd00:ec2::23/128",
+		// GCP metadata for IPv6-only instances, likewise ULA.
+		"fd20:ce::254/128",
+		// Oracle OCI IMDS over IPv6, likewise ULA.
+		"fd00:c1::a9fe:a9fe/128",
+		// Scaleway metadata over IPv6, likewise ULA.
+		"fd00:42::42/128",
+		// Linode/Akamai metadata over IPv6, likewise ULA.
+		"fd00:a9fe:a9fe::1/128",
+		// Alibaba Cloud metadata, inside CGNAT.
+		"100.100.100.200/32",
+		// Oracle Cloud Classic metadata, inside the blocked
+		// 192.0.0.0/24.
+		"192.0.0.192/32",
+		// 169.254.169.254 as an IPv4-compatible IPv6 address.
+		"::a9fe:a9fe/128",
+		// 169.254.169.254 behind the NAT64 well-known prefix.
+		"64:ff9b::a9fe:a9fe/128",
+	}
+
+	assert.Equal(t, want, got)
+}
+
+// requireLoopback fails the test unless rawURL's host is a
+// loopback address, so the allowlist test cannot silently stop
+// exercising a blocked range.
+func requireLoopback(t *testing.T, rawURL string) {
+	t.Helper()
+
+	parsed, err := url.Parse(rawURL)
+	require.NoError(t, err)
+
+	ip := net.ParseIP(parsed.Hostname())
+	require.NotNil(t, ip, "test server host must be an IP literal")
+	require.True(t, ip.IsLoopback(),
+		"test server must listen on loopback, got %s", ip,
+	)
+}
+
+// assertDialRefused asserts the guard's transport refuses to
+// connect to target, which is the delivery-time half of the
+// policy. It never reaches the network: the guard checks the
+// resolved address before dialling.
+func assertDialRefused(
+	t *testing.T, guard *delivery.Guard, target string,
+) {
+	t.Helper()
+
+	assertDialRefusedWith(t, guard, target, "blocked")
+}
+
+// assertDialRefusedWith is assertDialRefused with the refusal
+// text pinned. Callers testing the unconditional set pass
+// metadataRefusalClause so the subtest cannot pass on an
+// ordinary blocklist refusal instead.
+func assertDialRefusedWith(
+	t *testing.T, guard *delivery.Guard, target, clause string,
+) {
+	t.Helper()
+
+	client := &http.Client{
+		Timeout:   5 * time.Second,
+		Transport: guard.NewSSRFSafeTransport(),
+	}
+
+	req, err := http.NewRequestWithContext(
+		context.Background(), http.MethodPost, target, nil,
+	)
+	require.NoError(t, err)
+
+	resp, err := client.Do(req)
+	if resp != nil {
+		_ = resp.Body.Close()
+	}
+
+	require.Error(t, err,
+		"delivery to %s must be refused by the dialer", target,
+	)
+	assert.Contains(t, err.Error(), clause,
+		"the refusal must come from the SSRF guard",
+	)
+}
+
+// hostFor renders an IP as it appears in a URL host, bracketing
+// IPv6 literals.
+func hostFor(ip string) string {
+	if net.ParseIP(ip).To4() == nil {
+		return "[" + ip + "]"
+	}
+
+	return ip
+}

internal/delivery/ssrf_test.go

@@ -31,10 +31,10 @@ func TestIsBlockedIP_PrivateRanges(t *testing.T) {
 		{"192.168.0.1", "192.168.0.1", true},
 		{"192.168.255.255", "192.168.255.255", true},
 		{"169.254.0.1", "169.254.0.1", true},
-		{"169.254.169.254", "169.254.169.254", true},
+		{metadataIP, metadataIP, true},
 		{"8.8.8.8", "8.8.8.8", false},
 		{"1.1.1.1", "1.1.1.1", false},
-		{"93.184.216.34", "93.184.216.34", false},
+		{publicIP, publicIP, false},
 		{"::1", "::1", true},
 		{"fd00::1", "fd00::1", true},
 		{"fc00::1", "fc00::1", true},
@@ -72,12 +72,12 @@ func TestValidateTargetURL_Blocked(t *testing.T) {
 	t.Parallel()
 
 	blockedURLs := []string{
-		"http://127.0.0.1/hook",
+		loopbackHookURL,
 		"http://127.0.0.1:8080/hook",
 		"https://10.0.0.1/hook",
 		"http://192.168.1.1/webhook",
 		"http://172.16.0.1/api",
-		"http://169.254.169.254/latest/meta-data/",
+		metadataURL,
 		"http://[::1]/hook",
 		"http://[fc00::1]/hook",
 		"http://[fe80::1]/hook",
@@ -88,7 +88,7 @@ func TestValidateTargetURL_Blocked(t *testing.T) {
 		t.Run(u, func(t *testing.T) {
 			t.Parallel()
 
-			err := delivery.ValidateTargetURL(
+			err := delivery.NewTestGuard().ValidateTargetURL(
 				context.Background(), u,
 			)
 
@@ -112,7 +112,7 @@ func TestValidateTargetURL_Allowed(t *testing.T) {
 		t.Run(u, func(t *testing.T) {
 			t.Parallel()
 
-			err := delivery.ValidateTargetURL(
+			err := delivery.NewTestGuard().ValidateTargetURL(
 				context.Background(), u,
 			)
 
@@ -126,7 +126,7 @@ func TestValidateTargetURL_Allowed(t *testing.T) {
 func TestValidateTargetURL_InvalidScheme(t *testing.T) {
 	t.Parallel()
 
-	err := delivery.ValidateTargetURL(
+	err := delivery.NewTestGuard().ValidateTargetURL(
 		context.Background(), "ftp://example.com/hook",
 	)
 
@@ -140,7 +140,7 @@ func TestValidateTargetURL_InvalidScheme(t *testing.T) {
 func TestValidateTargetURL_EmptyHost(t *testing.T) {
 	t.Parallel()
 
-	err := delivery.ValidateTargetURL(
+	err := delivery.NewTestGuard().ValidateTargetURL(
 		context.Background(), "http:///path",
 	)
 
@@ -150,7 +150,7 @@ func TestValidateTargetURL_EmptyHost(t *testing.T) {
 func TestValidateTargetURL_InvalidURL(t *testing.T) {
 	t.Parallel()
 
-	err := delivery.ValidateTargetURL(
+	err := delivery.NewTestGuard().ValidateTargetURL(
 		context.Background(), "://invalid",
 	)
 

internal/delivery/url_mask_test.go

@@ -185,7 +185,7 @@ func TestDoHTTPRequest_TransportErrorMasksURL(t *testing.T) {
 func TestValidateTargetURL_UnparsableURLIsMasked(t *testing.T) {
 	t.Parallel()
 
-	err := delivery.ValidateTargetURL(
+	err := delivery.NewTestGuard().ValidateTargetURL(
 		context.TODO(),
 		"https://hooks.slack.com"+maskSecretPath+"\n",
 	)