destination

package
v0.77.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 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"`

	// DenyPrefixes are CIDR ranges refused even when allow or only contains
	// them. The order of evaluation is cloud metadata, then deny, then only,
	// or allow and the public-address default.
	DenyPrefixes []string `desc:"CIDR ranges refused even inside an allowed range" mapstructure:"deny"`

	// 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

	// DenyPrefixes are refused even when OnlyPrefixes or AllowPrefixes contains
	// them, for an address inside an allowed range that must stay unreachable,
	// such as a platform service on a private network.
	DenyPrefixes []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.

An address is judged in this order: cloud metadata (unless AllowCloudMetadata), then DenyPrefixes, then OnlyPrefixes, or AllowPrefixes and the public-address default. A deny range is final: no allow range overrides it.

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