bindguard

Documentation

Overview

Package bindguard is the inbound network policy every listener Flynn opens is bound through: a default-loopback gate that decides whether a given listen address may be bound. It is the inbound mirror of netguard (the outbound egress gate): where netguard stops a connection the agent makes from reaching somewhere it should not, bindguard stops a listener the agent opens from being reachable by someone it should not.

The doctrine is bind-safe by default. A listener binds the loopback interface unless an operator explicitly opts into wider exposure, and a wildcard bind (0.0.0.0, ::, or an empty host, which binds every interface including ones the operator does not know about) is refused unconditionally: even when exposure is granted, a specific interface address must be named. The recommended way to reach a service from off the machine is a tunnel to its loopback bind, not a public bind, so the safe default needs no extra thought and the unsafe shape needs an explicit, auditable choice.

The gate is enforced at the point of bind. A host given as a name is resolved and every resolved address must pass, so a name that resolves to a non-loopback address is not silently bound off-host.

Index

• func CheckHost(host string, e Exposure) error
• func FreeLoopbackPort() (int, error)
• func Listen(network, addr string, e Exposure) (net.Listener, error)
• type Exposure
  • func Exposed() Exposure
  • func Loopback() Exposure

Functions

func CheckHost

func CheckHost(host string, e Exposure) error

CheckHost reports whether host (the host part of a listen address) may be bound under e. An empty host, or a host that parses to the unspecified address (0.0.0.0 or ::), is a wildcard bind and is always refused. A loopback host is always allowed. Any other address is allowed only when e.AllowNonLoopback is set. A non-IP host is resolved and every resolved address must pass.

func FreeLoopbackPort

func FreeLoopbackPort() (int, error)

FreeLoopbackPort asks the OS for an unused loopback TCP port by binding port 0 and reading back the assignment, then releasing it for a server to claim. The brief gap between release and the real bind is the standard, accepted way to choose a port. It goes through the loopback policy so even free-port discovery cannot bind off-loopback.

func Listen

func Listen(network, addr string, e Exposure) (net.Listener, error)

Listen binds a listener on addr (host:port) for network, enforcing e. It is the governed counterpart of the standard net.Listen: the one place a TCP listener is opened, so a new bind cannot bypass the inbound policy. The address is checked before the bind, so an unsafe address fails closed rather than opening a socket.

Types

type Exposure

type Exposure struct {
	// AllowNonLoopback permits binding a specific, non-loopback unicast interface
	// address (a chosen LAN or public IP). It is the explicit operator opt-in for
	// exposing a service off the loopback interface. It never permits a wildcard bind:
	// a specific address must always be named.
	AllowNonLoopback bool
}

Exposure decides how widely a listener may bind. The zero Exposure is loopback-only (bind-safe by default): a bind is allowed only on the loopback interface. Granting AllowNonLoopback additionally permits a named non-loopback unicast interface address, but never a wildcard bind.

func Exposed

func Exposed() Exposure

Exposed permits binding a named non-loopback interface address (still never a wildcard). Use it only for a deliberate, audited exposure; prefer a tunnel to a loopback bind.

func Loopback

func Loopback() Exposure

Loopback is the bind-safe default: only the loopback interface may be bound.