Documentation
¶
Overview ¶
Package outbound provides a standard-library-only HTTP client for destinations supplied by users, such as webhook URLs. It validates every request and the addresses actually dialed, including requests that reuse an existing connection.
The default policy allows public HTTPS destinations. Exact host and CIDR allowlists may additionally trust private or plaintext HTTP destinations, but never enable metadata endpoints, link-local, multicast, unspecified, or selected address-translation ranges. An allowlist is an exception to the public-only default, not a restriction that disables other public HTTPS destinations.
Clients returned by Policy.Client disable environment proxies and all redirects. Use that client for the actual request: Validate alone is a check-then-use and cannot prevent DNS rebinding. Keep the client's transport and redirect policy intact. This package does not retry requests, authenticate destinations, limit response bodies, or redact net/http's URL-bearing errors.
The policy originated in OwlCron. Its MIT license and attribution are retained in LICENSE-OWLCRON and NOTICE at the module root.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrBlocked = errors.New("outbound destination is prohibited by security policy")
ErrBlocked reports an invalid or prohibited destination. It never includes the URL, hostname, or address. Use errors.Is to classify wrapped client errors.
var ErrDNSResolution = errors.New("outbound DNS resolution failed")
ErrDNSResolution reports a failed DNS lookup without exposing resolver details.
var ErrInvalidOptions = errors.New("invalid outbound policy options")
ErrInvalidOptions reports malformed configuration without repeating its input.
var ErrNoAddresses = errors.New("outbound DNS returned no addresses")
ErrNoAddresses reports a successful lookup that returned no addresses.
Functions ¶
This section is empty.
Types ¶
type Options ¶
Options configures exceptions to the default public-HTTPS policy. Entries do not restrict access to other public HTTPS destinations. Wildcards, URL schemes, ports, trailing dots, scoped IPv6 addresses and IPv4-mapped CIDRs are rejected. Use exact DNS hostnames, bare IP literals, or CIDRs respectively. Metadata and other always-prohibited addresses remain blocked by any exception. NewPolicy copies and normalizes these slices; later caller mutations have no effect.
type Policy ¶
type Policy struct {
// contains filtered or unexported fields
}
Policy is an immutable destination policy, safe for concurrent requests. Its zero value permits public HTTPS and no other destinations.
func NewPolicy ¶
NewPolicy validates the options and returns an independent policy. An invalid entry rejects the entire configuration; errors never contain the supplied entry.
func (*Policy) Client ¶
Client returns a fresh client with its own connection pool. Reuse the returned client across requests and call CloseIdleConnections when it is no longer used. The timeout is ten seconds. Proxies and redirects are disabled, and TLS uses the standard library's certificate verification and protocol defaults.
Every request is checked even when a connection is reused. New connections additionally resolve and check the destination immediately before dialing a numeric address. Plaintext HTTP requires explicit trust at both stages.
Changing Transport or CheckRedirect can bypass these protections. The client does not impose response-size limits; callers must bound the bodies they read.