surfguard

func (Policy) Allow ¶

func (p Policy) Allow(prefixes ...netip.Prefix) Policy

Allow returns a policy that admits the given prefixes where the default deny tables or the IPv6 allocated-unicast allowlist would refuse them. Allow never overrides Deny, structural defenses, or the IANASpecialUse tables. Invalid prefixes panic: allowing is a construction-time decision by trusted code, and a silently dropped allowance would fail closed in a way that masks the bug.

func (Policy) AllowAllPorts ¶

func (p Policy) AllowAllPorts() Policy

AllowAllPorts returns a policy whose connection layer does not restrict ports. Address policy still applies.

func (Policy) AllowLoopback ¶

func (p Policy) AllowLoopback() Policy

AllowLoopback returns a policy that admits 127.0.0.0/8 and ::1 on any port, including under IANASpecialUse. It exists so httptest fixtures (which bind random loopback ports) work against otherwise-strict policies. Never enable it outside tests and tooling that must reach operator-named local targets.

package main

import (
	"fmt"

	surfguard "github.com/basecamp/surfguard/go"
)

func main() {
	fixture := surfguard.Policy{}.AllowLoopback()
	fmt.Println(fixture.BlockedHost("127.0.0.1"))
	fmt.Println(fixture.BlockedHost("169.254.169.254"))
}

Output:
false
true

func (Policy) AllowPorts ¶

func (p Policy) AllowPorts(ports ...uint16) Policy

AllowPorts returns a policy whose connection layer admits exactly the given ports (accumulating with earlier calls) instead of the default {80, 443}. Loopback targets under AllowLoopback are exempt from port checks. Port 0 panics.

func (Policy) Blocked ¶

func (p Policy) Blocked(addr netip.Addr) bool

Blocked reports whether addr must be refused under the policy. Invalid and zoned addresses fail closed. This is the classification core every other layer delegates to.

IPv4-mapped input (::ffff:a.b.c.d) is blocked outright: a mapped address in classification input is a hostile AAAA record or a caller bug, never a legitimate public target. (The dial layer unmaps before judging instead, because there the kernel really is about to connect to the embedded IPv4.)

func (Policy) BlockedHost ¶

func (p Policy) BlockedHost(host string) bool

BlockedHost judges a host string without ever querying DNS: address literals (IPv6, dotted-quad, legacy inet_aton spellings, full-width prefixes) are classified; everything else — every hostname included — is reported blocked, because a name's addresses are unknowable without resolution.

A false result therefore means "an admitted address literal", NOT "a safe host": it is never false for a name. Do not use it as an allow-gate for names — a hostname will always return true (fails closed). For names, use Policy.ResolvePublicAddrs or Policy.CheckURL, and pin the returned addresses.

func (Policy) CheckRedirect ¶

func (p Policy) CheckRedirect(next func(req *http.Request, via []*http.Request) error) func(req *http.Request, via []*http.Request) error

CheckRedirect returns an http.Client CheckRedirect function that enforces redirect policy (pass nil for next, or a caller callback to run alongside).

The caller callback runs first. Any non-nil result it returns — including http.ErrUseLastResponse — stops the client from following the redirect, so no unvalidated request is ever sent; that result is returned unchanged. Only when the caller approves (returns nil, having possibly mutated the request) does the policy validate, and it validates the request that will actually go on the wire:

• Hop cap: at most Policy.MaxRedirects redirects (default 10; 0 follows none).
• Scheme: only http and https, and never an https→http downgrade — the dial layer cannot see schemes, so this is the one redirect property that must be enforced here.
• Host: literal and numeric Location hosts are classified synchronously and refused when blocked or malformed. Named hosts pass — their addresses are judged at dial time by Policy.ControlContext, which re-runs for every hop.

The policy is not skippable: a caller who returns nil cannot cause a fetch to a refused target, because validation runs after their callback on the final request.

func (Policy) CheckURL ¶

func (p Policy) CheckURL(ctx context.Context, rawURL string) error

CheckURL returns nil if and only if rawURL's host resolves and every answer is admitted under the policy. A mixed public+blocked answer is refused: an unpinned connect could pick the blocked one. Errors are Violation (blocked or malformed; matches ErrBlocked) or UnresolvableError (matches ErrUnresolvable).

CheckURL judges addresses only. Scheme, port, and redirect policy are enforced by Policy.Client; DNS rebinding between this check and a later connect is only defeated by dial-time enforcement or caller pinning.

func (Policy) Client ¶

func (p Policy) Client() *http.Client

Client returns a real *http.Client enforcing the policy: every request URL is checked for a well-formed host via Policy.RoundTripper, every connection is judged at dial time via Policy.ControlContext, every redirect hop is re-validated via Policy.CheckRedirect, and requests time out after 30 seconds (adjust on the returned client if needed — but keep some timeout: a policy-refused target should not be able to stall callers either).

func (Policy) Control ¶

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

Control is Policy.ControlContext without a context, for net.Dialer's Control field and APIs that take the two-argument form.

func (Policy) ControlContext ¶

func (p Policy) ControlContext(_ context.Context, network, address string, _ syscall.RawConn) error

ControlContext is the enforcement core: install it as net.Dialer's ControlContext and every socket connect attempt — each Happy Eyeballs race entrant, each redirect hop's dial, each connection-pool miss — is judged by its literal address at the moment of connection. There is no gap between the address checked and the address connected, which is what defeats DNS rebinding.

Only tcp4/tcp6 are admitted. IPv4-mapped addresses are unmapped before judgment: at dial time the kernel really connects to the embedded IPv4. The port must be in the policy's allowed set (default 80 and 443; loopback under Policy.AllowLoopback is exempt).

func (Policy) Deny ¶

func (p Policy) Deny(prefixes ...netip.Prefix) Policy

Deny returns a policy that refuses the given prefixes ahead of every other rule, including Allow and AllowLoopback. Invalid prefixes panic.

func (Policy) DialContext ¶

func (p Policy) DialContext(ctx context.Context, network, address string) (net.Conn, error)

DialContext dials with enforcement installed. Network may be "tcp", "tcp4", or "tcp6"; the resolved per-family attempts are each judged by Policy.ControlContext.

Address literals — including legacy inet_aton spellings like "2130706433" or "0x7f000001" — are canonicalized to their dotted/colon form before the dialer runs, so the numeric-host defense holds here too: the raw token is never handed to a resolver that might treat it as a name and follow a wildcard answer. Named hosts are left for the dialer to resolve, and every resulting address is judged by Policy.ControlContext.

package main

import (
	"errors"
	"fmt"
	"net/http"

	surfguard "github.com/basecamp/surfguard/go"
)

func main() {
	policy := surfguard.Policy{}
	transport := &http.Transport{
		Proxy:       nil, // never proxy: the proxy address would be judged instead of the target
		DialContext: policy.DialContext,
	}
	client := &http.Client{Transport: transport, CheckRedirect: policy.CheckRedirect(nil)}
	_, err := client.Get("http://127.0.0.1/")
	fmt.Println(errors.Is(err, surfguard.ErrBlocked))
}

Output:
true

func (Policy) IANASpecialUse ¶

func (p Policy) IANASpecialUse() Policy

IANASpecialUse returns a policy that additionally blocks every prefix in the checked-in IANA IPv4 and IPv6 special-purpose registry snapshots, including globally reachable service infrastructure (AMT, AS112, the whole NAT64 well-known prefix). The tables also apply to NAT64/SIIT-embedded IPv4, so they cannot be bypassed via IPv6 encoding.

Use it for advertised or discovered infrastructure values — data a remote peer chose. A target must never choose its own policy; trusted consumer code chooses it.

package main

import (
	"errors"
	"fmt"

	surfguard "github.com/basecamp/surfguard/go"
)

func main() {
	policy := surfguard.Policy{}.IANASpecialUse()
	client := policy.Client()
	_, err := client.Get("http://[64:ff9b::5db8:d822]/") // NAT64 WKP, even wrapping a public IPv4
	fmt.Println(errors.Is(err, surfguard.ErrBlocked))
}

Output:
true

func (Policy) MaxRedirects ¶

func (p Policy) MaxRedirects(n int) Policy

MaxRedirects returns a policy whose client follows at most n redirects (default 10). Zero means redirects are not followed at all. Negative n panics.

func (Policy) ResolvePublicAddrs ¶

func (p Policy) ResolvePublicAddrs(ctx context.Context, host string) ([]netip.Addr, error)

ResolvePublicAddrs resolves host and returns every admitted address, IPv4 before IPv6 with resolver order retained within each family — a deterministic failover order for callers that pin the selected address at connection time. Blocked answers are filtered, so a resolvable host whose every answer is blocked yields an empty slice and a nil error.

Names are looked up per address family (see Resolver). Address literals — including legacy inet_aton spellings — are classified authoritatively without DNS. Malformed hosts return a Violation with ReasonMalformedHost (where Ruby's resolve_public_ips returns [] silently; Go callers check errors). An empty or invalid DNS answer returns an UnresolvableError, which is deliberately not part of the ErrBlocked family: it means retry later, not deactivate.

package main

import (
	"context"
	"errors"
	"fmt"

	surfguard "github.com/basecamp/surfguard/go"
)

func main() {
	addrs, err := surfguard.ResolvePublicAddrs(context.Background(), "93.184.216.34")
	if err != nil {
		var unresolvable *surfguard.UnresolvableError
		if errors.As(err, &unresolvable) {
			// Retry later: the host may resolve next time.
		}
		return
	}
	for _, addr := range addrs {
		fmt.Println(addr) // dial these, in order
	}
}

Output:
93.184.216.34

func (Policy) RoundTripper ¶

func (p Policy) RoundTripper() http.RoundTripper

RoundTripper returns Policy.Transport wrapped in the URL-shape check, for callers assembling their own *http.Client. It validates the host of every request it carries — the initial one and each redirect hop — before delegating.

This check cannot live at the dial layer: an http.Transport dials req.URL.Hostname(), which has already stripped the brackets from an authority, so by then a bracketed host is indistinguishable from a bare one. Nor can it be left to net/url: its IP-literal validation tightened after Go 1.23, this module's floor, where url.Parse still accepts "http://[example.com]/" and reports the host as the ordinary name "example.com".

func (Policy) Transport ¶

func (p Policy) Transport() *http.Transport

Transport returns a real *http.Transport wired to the enforcement layer. Proxying is deliberately disabled — with a proxy configured, dial-time checks would judge the proxy's address rather than the target's, which is the classic bypass in copy-pasted Control snippets. Do not set Proxy on the returned transport.

It judges addresses, not URL shape: an http.Transport dials req.URL.Hostname(), so a malformed authority is already normalized away by the time it is reached. Wrap it in Policy.RoundTripper — as Policy.Client does — to refuse malformed hosts as well.

func (Policy) WithResolver ¶

func (p Policy) WithResolver(r Resolver) Policy

WithResolver returns a policy whose resolution layer (Policy.CheckURL, Policy.ResolvePublicAddrs) uses r instead of net.DefaultResolver. It is L2-only by design: it does not, and cannot, reconfigure the net.Dialer the enforcement layer builds (that field is a concrete *net.Resolver, whereas this seam is an interface so tests can inject fakes). The dial layer is unaffected regardless — it judges the literal address of every connect attempt no matter who resolved it, so there is no pre-check/dial gap to exploit. A nil r restores net.DefaultResolver.

func (Reason) String ¶

func (r Reason) String() string

String names the reason for structured logging. It never echoes input.

func (*UnresolvableError) Error ¶

func (u *UnresolvableError) Error() string

func (*UnresolvableError) Unwrap ¶

func (u *UnresolvableError) Unwrap() []error

Unwrap exposes ErrUnresolvable and the underlying resolver cause.

A cause that itself matches ErrBlocked is deliberately left out of the chain: a Resolver is caller-supplied code, and one that applies its own policy could return that sentinel. Carrying it here would make a single error match both families at once and collapse the retry-versus-deactivate distinction they exist to draw — a caller that deactivates targets on ErrBlocked would deactivate one whose lookup merely failed. The cause stays reachable through the Err field either way.

func (*Violation) Error ¶

func (v *Violation) Error() string

func (*Violation) Unwrap ¶

func (v *Violation) Unwrap() error