outbound_guard

package
v1.115.0 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 10 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func AppendDeniedPrefixStrings(values []string) []string

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

func DeniedPrefixes() []netip.Prefix

DeniedPrefixes returns the parsed CIDR deny list.

func DialControl

func DialControl(_ string, address string, _ syscall.RawConn) error

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

func HostForTarget(target string) string

HostForTarget extracts the hostname or IP portion from a raw target.

func IsPublic

func IsPublic(addr netip.Addr) bool

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

func IsPublicIP(ip net.IP) bool

IsPublicIP reports whether ip is outside the deny list.

func IsPublicTarget

func IsPublicTarget(ctx context.Context, target string) bool

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

func PrefixFromIPNet(ipNet *net.IPNet) (netip.Prefix, error)

PrefixFromIPNet converts ipNet into a normalized netip.Prefix.

func PrefixOverlapsDenied

func PrefixOverlapsDenied(ipNet *net.IPNet) (bool, error)

PrefixOverlapsDenied reports whether ipNet overlaps any denied prefix.

Types

type LookupIPFunc

type LookupIPFunc func(ctx context.Context, network string, host string) ([]net.IP, error)

LookupIPFunc resolves host into IP addresses.

type Target

type Target struct {
	Target   string
	Host     string
	IPs      []net.IP
	DirectIP bool
}

Target describes the normalized target data used by the checks.

func Check

func Check(ctx context.Context, target string) (*Target, error)

Check parses a target and checks that it is public, resolving it with the default resolver.

func CheckWithLookup

func CheckWithLookup(ctx context.Context, target string, lookupIP LookupIPFunc) (*Target, error)

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

func ResolveTarget(ctx context.Context, target string, lookupIP LookupIPFunc) (*Target, error)

ResolveTarget parses target and returns the IPs the checks are made of.

Jump to

Keyboard shortcuts

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