destination

package
v0.77.1 Latest Latest
Warning

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

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

Documentation

Overview

Package destination decides which network destinations a client may connect to, for services that connect outbound to addresses an untrusted party can influence (webhook delivery, reverse proxies, SOCKS gateways).

The decision is made at the socket, after name resolution and before the connection is made, so it covers redirects, DNS rebinding and a hostname that resolves to several addresses. A check at configuration time is a convenience only.

Index

Constants

This section is empty.

Variables

View Source
var ErrDenied = errors.New("destination not allowed")

ErrDenied is returned, wrapped, when a policy does not allow a destination. Callers can map it to a validation error or a refused request with errors.Is.

Functions

func IsCloudMetadataAddress

func IsCloudMetadataAddress(addr netip.Addr) bool

IsCloudMetadataAddress reports whether addr is where a cloud provider serves instance metadata. IPv4-mapped and NAT64 addresses are judged by the IPv4 address they carry.

func IsPublicAddress

func IsPublicAddress(addr netip.Addr) bool

IsPublicAddress reports whether addr is a public internet address: not loopback, private (including IPv6 unique local addresses, and so Fly.io's private network), link-local (including cloud metadata), multicast, unspecified or in a special-use range. IPv4-mapped and NAT64 addresses are judged by the IPv4 address they carry.

Types

type Config

type Config struct {
	// AllowPrefixes are CIDR ranges allowed in addition to public addresses.
	AllowPrefixes []string `desc:"CIDR ranges allowed in addition to public addresses" mapstructure:"allow"`

	// OnlyPrefixes are the only CIDR ranges allowed; public addresses are not
	// allowed unless listed.
	OnlyPrefixes []string `desc:"the only CIDR ranges allowed, replacing the public-address default" mapstructure:"only"`

	// AllowedPorts restricts destination ports when set.
	AllowedPorts []int `desc:"destination ports allowed, any when empty" mapstructure:"allowed-ports"`

	// AllowCloudMetadata permits cloud metadata endpoints.
	AllowCloudMetadata bool `desc:"allow cloud metadata endpoints" mapstructure:"allow-cloud-metadata"`
}

Config is a Policy in the form services take it in their configuration.

func (Config) Check

func (cfg Config) Check(c *configcheck.Collector)

Check reports to c a range that is not a CIDR prefix, a port out of range, and allow ranges given together with only, which would be ignored. c is positioned at the config's own block.

func (Config) Policy

func (cfg Config) Policy() (Policy, error)

Policy returns the Policy for cfg. It returns an error for a range that is not a CIDR prefix; Check reports the same.

type Policy

type Policy struct {
	// AllowPrefixes are exceptions to the default deny of non-public
	// addresses, for example the private network of a deployment.
	AllowPrefixes []netip.Prefix

	// OnlyPrefixes, when set, allows only these ranges and replaces the
	// public-address default. AllowPrefixes has no effect with it.
	OnlyPrefixes []netip.Prefix

	// AllowedPorts, when set, restricts destination ports.
	AllowedPorts []int

	// AllowCloudMetadata permits cloud metadata endpoints, which are denied
	// otherwise.
	AllowCloudMetadata bool
}

Policy decides which destinations a client may connect to. The zero value allows only public addresses on any port.

Cloud metadata endpoints are denied unless AllowCloudMetadata is set, whatever the prefixes say, so a broad allow-list cannot expose them by accident.

func (Policy) Check

func (p Policy) Check(dest netip.AddrPort) error

Check returns an error wrapping ErrDenied when the policy does not allow connecting to dest. IPv4-mapped and NAT64 addresses are judged by the IPv4 address they carry.

func (Policy) Client

func (p Policy) Client(maxRedirects int) *http.Client

Client returns an http.Client using Transport that follows at most maxRedirects redirects. With zero it follows none and returns the redirect response itself. A redirect to a denied address is refused at the dial.

func (Policy) Control

func (p Policy) Control(_, address string, _ syscall.RawConn) error

Control is a net.Dialer.Control hook. It checks the numeric address a dial is about to connect to, after name resolution and before the socket connects, so no path to a denied address remains however the dial was reached.

func (Policy) Dialer

func (p Policy) Dialer() *net.Dialer

Dialer returns a net.Dialer that enforces the policy on every address it connects to.

func (Policy) Transport

func (p Policy) Transport() http.RoundTripper

Transport returns an http.RoundTripper that enforces the policy on every connection it makes, and refuses any scheme other than http and https. It does not use a proxy from the environment: a proxy would be the address dialled, and the destination behind it would escape the policy.

A kept-alive connection is not re-checked per request. A live connection cannot rebind to another peer, so the check made when it was opened still holds; a new connection resolves and checks afresh.

Jump to

Keyboard shortcuts

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