Documentation
¶
Overview ¶
Package outbound_guard keeps a program's outbound connections to the public internet, for the ones it makes to targets a user or a datastore chose: a feed address to fetch, a host to scan.
It refuses loopback, private, link-local, cloud metadata, reserved, documentation, multicast and the other address ranges the public internet does not route. Check accepts a raw IP address, a hostname, a host:port or a URL; a hostname is resolved and every answer must be public, and a failed or empty lookup is refused. DialControl makes the same check where a net.Dialer connects, which also catches a redirect, or a name that resolves to an internal address only when dialled.
A scanner engine with a connection policy of its own can be given DeniedPrefixStrings, so that it refuses the same ranges when it connects.
Index ¶
- Variables
- func AppendDeniedPrefixStrings(values []string) []string
- func DeniedPrefixStrings() []string
- func DeniedPrefixes() []netip.Prefix
- func DialControl(_ string, address string, _ syscall.RawConn) error
- func HostForTarget(target string) string
- func IsPublic(addr netip.Addr) bool
- func IsPublicIP(ip net.IP) bool
- func IsPublicTarget(ctx context.Context, target string) bool
- func IsPublicTargetWithLookup(ctx context.Context, target string, lookupIP LookupIPFunc) bool
- func PrefixFromIPNet(ipNet *net.IPNet) (netip.Prefix, error)
- func PrefixOverlapsDenied(ipNet *net.IPNet) (bool, error)
- type LookupIPFunc
- type Target
Constants ¶
This section is empty.
Variables ¶
var ( ErrDNSLookupFailed = errors.New("DNS lookup failed") ErrNoIPAddresses = errors.New("DNS lookup returned no IP addresses") // ErrNotPublic is a target, or a connection, to an address outside the public internet. ErrNotPublic = errors.New("not a public address") // ErrInvalidNetwork is an IP network that is no IPv4 or IPv6 prefix. ErrInvalidNetwork = errors.New("invalid IP network") )
Functions ¶
func AppendDeniedPrefixStrings ¶
AppendDeniedPrefixStrings appends the shared CIDR deny list to values, preserving existing values and avoiding duplicates.
func DeniedPrefixStrings ¶
func DeniedPrefixStrings() []string
DeniedPrefixStrings returns the CIDR deny list as strings.
func DeniedPrefixes ¶
DeniedPrefixes returns the parsed CIDR deny list.
func DialControl ¶
DialControl is a net.Dialer's Control that refuses a connection to an address that is not public. It is checked on the address the connection is made to, after any resolution, so that a redirect, or a name resolving to an internal address only when dialled, is caught where a check of the name beforehand would not be; a dialer using it must not go through a proxy, or the address checked is the proxy's.
func HostForTarget ¶
HostForTarget extracts the hostname or IP portion from a raw target.
func IsPublic ¶
IsPublic reports whether addr is outside the deny list: not loopback, private, link-local, cloud metadata, reserved, documentation, multicast or any other range the public internet does not route. An address with a zone is refused whatever it is: a zone scopes an address to one link, which no public address needs, and netip.Prefix.Contains is false for a zoned address, so ::1%lo would otherwise pass a check of every prefix it is in.
func IsPublicIP ¶
IsPublicIP reports whether ip is outside the deny list.
func IsPublicTarget ¶
IsPublicTarget reports whether target resolves to public addresses alone.
func IsPublicTargetWithLookup ¶
func IsPublicTargetWithLookup(ctx context.Context, target string, lookupIP LookupIPFunc) bool
IsPublicTargetWithLookup reports whether target resolves, with lookupIP, to public addresses alone.
func PrefixFromIPNet ¶
PrefixFromIPNet converts ipNet into a normalized netip.Prefix.
Types ¶
type LookupIPFunc ¶
LookupIPFunc resolves host into IP addresses.
type Target ¶
Target describes the normalized target data used by the checks.
func Check ¶
Check parses a target and checks that it is public, resolving it with the default resolver.
func CheckWithLookup ¶
CheckWithLookup parses a target and checks that it is public, resolving it with lookupIP.
target may be a raw IP, hostname, host:port, or URL. Hostnames are resolved and every resulting IP must be outside the shared deny list. DNS errors and empty DNS answers fail closed.
func ResolveTarget ¶
ResolveTarget parses target and returns the IPs the checks are made of.