dialguard

package
v1.45.0 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package dialguard refuses outbound connections to special-purpose addresses, checked on the address ACTUALLY DIALLED.

Policy, ruled by Diego on snowplow#1131 (2026-11-04 evening, replacing an earlier "refuse nothing") and shared verbatim with snowplow so the two components cannot diverge:

REFUSED, on every request, with or without credentials:
  169.254.0.0/16, fe80::/10   cloud metadata and link-local
  0.0.0.0, ::                 unspecified
  224.0.0.0/4, ff00::/8       multicast

ALLOWED: loopback and private ranges (RFC-1918, ULA). In-cluster services -- including
Krateo's own registry at *.svc.cluster.local -- and on-prem endpoints live there, so denying
them would break every installation.

NOT GATED ON CREDENTIALS, and that is a deliberate departure from the first draft of this. The metadata service is an SSRF target with no credential involved: a request that merely FETCHES 169.254.169.254 can return a cloud token. Gating on credentials would have left that open while looking like a fix.

CHECKED AT DIAL TIME ON THE RESOLVED ADDRESS, via net.Dialer.Control, rather than on the hostname at admission. Three consequences, each of which is why this is the right hook:

  1. DNS REBINDING is closed. A name that resolves to a public address when validated and to 169.254.169.254 when dialled is refused, because the check sees the second answer. A hostname check sees only the first.
  2. IDNA AND HOSTNAME SPELLING become irrelevant. Confusables, trailing dots, uppercase, percent-encoding and every other spelling of a name resolve to the same address, and the address is what is checked. A name-based allowlist has to normalise correctly to be sound; this has nothing to normalise.
  3. REDIRECTS are covered without a second mechanism, because every hop dials.

FAILS CLOSED. An unresolvable or unparseable host never produces a dial, so the request fails rather than proceeding -- and DenyAddr refuses anything it cannot parse rather than passing it through. "Could not determine" must not read as "permitted".

NO KNOB AND NO ALLOWLIST, by the same ruling. An escape hatch here is a setting whose only users are the people it exists to stop.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Client

func Client(timeout time.Duration) *http.Client

Client returns an *http.Client with a guarded transport. Exists so no caller has to reach for http.DefaultClient, which has an unguarded transport and is shared process-wide.

func Control

func Control(network, address string, _ syscall.RawConn) error

Control is the net.Dialer.Control hook. Install it on EVERY dialer that can carry a user-influenced destination.

The address is post-resolution: net.Dialer resolves the name and calls Control once per candidate address, immediately before connecting to that address. Returning an error refuses that dial.

func DenyAddr

func DenyAddr(address string) error

DenyAddr reports whether an already-resolved "host:port" may be dialled, as a separate exported function so the policy is testable without a syscall.RawConn and so a caller can pre-check.

func Dialer

func Dialer() *net.Dialer

Dialer returns a net.Dialer with Control installed and the timeouts this repo already used at its three dial sites, so wiring it in is not also a behaviour change.

A CONSTRUCTOR RATHER THAN A DOCUMENTED FIELD TO SET. Three sites built a dialer independently and a fourth and fifth had none at all and fell through to http.DefaultTransport -- which is the failure the ruling warns about: "a check in a builder that some call sites bypass looks complete and isn't". A constructor plus the AST guard in dialguard_wiring_test.go makes the omission a test failure rather than an invisible gap.

func Transport

func Transport() *http.Transport

Transport returns an *http.Transport whose DialContext is guarded, with the pooling settings the existing sites shared. Callers that need to vary a field mutate the result.

Types

type ErrDenied

type ErrDenied struct {
	Addr   string
	Reason string
}

ErrDenied is returned for a refused destination. A sentinel so a caller can distinguish a policy refusal from a network failure: the two have opposite remedies, and conflating them sends an operator to check connectivity for a destination that will never be permitted.

func (*ErrDenied) Error

func (e *ErrDenied) Error() string

Jump to

Keyboard shortcuts

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