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