egressguard

package
v0.7.7-dev.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package egressguard is the core's SSRF egress guard: every fetch the registry makes to an address someone else chose (a webhook endpoint, an OIDC issuer, a README image, an MCP server's vendor) goes through it. A candidate address must be public unicast, the address dialled is the one checked (no second lookup between the check and the connect), no redirect is followed and no proxy is taken from the environment.

It lives in pkg/ so that modules outside the core use this one implementation rather than a copy: the enterprise build's vault vendor client and the CLI's OAuth fetches. internal/webhook keeps its names as aliases of these.

Index

Constants

View Source
const DefaultTimeout = 10 * time.Second

DefaultTimeout bounds one request when a Guard names no Timeout: the webhook delivery's 10 s.

Variables

This section is empty.

Functions

This section is empty.

Types

type BlockedAddressError

type BlockedAddressError struct {
	Host string
	IP   string
}

BlockedAddressError is the guarded dialer's refusal of a destination that resolves to a non-public address, or to none.

func (*BlockedAddressError) Error

func (e *BlockedAddressError) Error() string

type Guard

type Guard struct {
	AllowLoopback bool
	LookupNetIP   func(ctx context.Context, host string) ([]netip.Addr, error)
	TLS           *tls.Config
	Timeout       time.Duration
	HTTPSOnly     bool
	Proxy         *url.URL
}

Guard is the SSRF egress policy. The zero value is production's.

AllowLoopback is a test-only seam so a loopback httptest server can be reached; production leaves it false. LookupNetIP is the resolver seam; nil means net.DefaultResolver. Tests use it to answer a name with an address of their choosing, the only way to exercise the resolve-then-pin half of DialContext. TLS is the client's TLS configuration: nil in production (system roots), a pool trusting an httptest certificate in a test. Timeout bounds one request (DefaultTimeout when zero). HTTPSOnly refuses a request that is not https before anything is dialled, for a caller whose every destination must be (an OAuth vendor).

Proxy, when set, is a fixed CONNECT proxy the operator names: production's worker reaches vendors' token endpoints only through its allowlisting egress proxy. The client then dials that proxy's address and nothing else, asks it for a tunnel to the target, and before asking resolves the target's name and refuses it if any answer is not public unicast; only https is carried, whatever HTTPSOnly says. The proxy resolves the name again when it opens the tunnel, so this check is not pinned the way a direct dial is: the proxy's own exact-host allowlist is what bounds where a tunnel goes. The environment's proxy settings are never read, with or without it.

func (Guard) Client

func (g Guard) Client() *http.Client

Client is an HTTP client bound to the guard: the checked dialer, no redirect followed, no proxy from the environment, no connection kept for reuse, and the guard's timeout on the whole request, the TLS handshake and the response's headers.

func (Guard) DialContext

func (g Guard) DialContext(ctx context.Context, network, addr string) (net.Conn, error)

DialContext resolves the host, verifies every candidate address, and dials a verified address directly (not the hostname) so a DNS answer cannot change between the check and the connect (TOCTOU / DNS-rebinding defense). Because this runs on every attempt, re-resolution per attempt is inherent. It is exported for a caller that must build its own transport; Client is the usual way in.

func (Guard) IsAllowedIP

func (g Guard) IsAllowedIP(ip netip.Addr) bool

IsAllowedIP reports whether ip is a public unicast address worth reaching. It refuses the ranges the IANA IPv4 and IPv6 special-purpose registries list as not globally reachable (see specialPurpose), the multicast ranges, loopback unless the test seam allows it, and any IPv6 address outside the global unicast space 2000::/3. IPv4-mapped IPv6 is unmapped first so ::ffff:10.0.0.1 cannot smuggle a private v4 address past the check, and an IPv6 address that embeds an IPv4 one (6to4, NAT64, IPv4-translated, ISATAP) is judged by the address it embeds.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL