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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.