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