egressguard

package
v1.162.2 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package egressguard vets the outbound connections a server-side fetch makes on behalf of content the platform did not write: a URL an agent hands the util connection, a stylesheet or image a stored document names when the thumbnail renderer draws it. Such a fetch runs inside the network perimeter, so without a guard it reaches what the author of the URL cannot -- a cluster service, a cloud metadata endpoint, a host on the operator's overlay network.

The guard resolves a hostname once, refuses every non-public answer, and dials the vetted address literally, so a public name cannot rebind to an internal address between the check and the connect. A redirect is re-dialed by the transport and passes the same check. An operator with trusted internal hosts lists their prefixes in an allow-list consulted before the internal-range block.

Index

Constants

View Source
const (
	ClassLoopback         = "loopback"
	ClassPrivate          = "private"
	ClassLinkLocal        = "link_local"
	ClassMulticast        = "multicast"
	ClassUnspecified      = "unspecified"
	ClassCGNAT            = "cgnat"
	ClassEmbeddedIPv4     = "embedded_ipv4"
	ClassInternalHostname = "internal_hostname"
)

The classes of address the guard refuses, as egress_blocked_total names them.

Variables

This section is empty.

Functions

This section is empty.

Types

type BlockedError

type BlockedError struct {
	// Host is the hostname or literal address that was refused.
	Host string
	// Reason names the rule that refused it, for a message.
	Reason string
	// Class is the rule as a bounded token, for egress_blocked_total{reason}
	// (#1895): one of the Class* constants.
	Class string
}

BlockedError is a dial the guard refused, as opposed to a network failure. A caller that surfaces it says the destination is not permitted rather than reporting a retryable upstream error, and words the remedy in its own terms: the setting that exempts a prefix belongs to whichever feature owns the guard.

func (*BlockedError) Error

func (e *BlockedError) Error() string

type Guard

type Guard struct {
	// contains filtered or unexported fields
}

Guard vets every outbound dial a guarded client performs.

func New

func New(allowPrivateCIDRs []string) (*Guard, error)

New builds a guard, parsing the operator's allow-list of private prefixes. An unparseable entry is a hard error: silently dropping it would either block a destination the operator explicitly permitted or, if the intent was a broad prefix, go unnoticed until a legitimate fetch fails.

func (*Guard) DialContext

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

DialContext resolves the hostname once, filters the answers, and dials only the vetted literal addresses -- the pin that defeats DNS rebinding. A host whose every address is refused surfaces a *BlockedError; mixed answers dial the permitted subset only.

func (*Guard) Transport

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

Transport returns an HTTP transport whose every dial passes the guard.

It deliberately ignores proxy environment variables (Proxy is nil): an egress proxy sits inside the network perimeter, and routing a guarded fetch through it would let the proxy reach a destination the guard just refused.

Jump to

Keyboard shortcuts

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