Documentation
¶
Overview ¶
Package urlguard provides host-owned URL normalization, origin admission, and SSRF-hardened transport construction for outbound requests that a codefly host makes on behalf of untrusted provider code.
Provider code never dials the network directly. It hands the host a descriptor; the host normalizes and admits the origin here, resolves and pins a single peer IP, and dials only that IP. This closes the classic bypasses: URL userinfo, encoded path traversal, scheme-relative URLs, proxy environment influence, credentialed redirects, and DNS rebinding between validation and dial.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Client ¶
func Client(origin Origin, pinned Resolution, deadlines Deadlines) *http.Client
Client builds an SSRF-hardened HTTP client bound to one pinned resolution. The transport has no proxy, dials only the pinned IP regardless of the address the URL carries (defeating DNS rebinding), verifies TLS against the origin host, and the client refuses every redirect.
Types ¶
type Ceiling ¶
type Ceiling struct {
Schemes []string
HostPatterns []string
Ports []uint32
AllowedClasses []NetworkClass
}
Ceiling is the manifest-declared origin ceiling. A concrete origin is admitted only if it stays inside every dimension of the ceiling. Host patterns are bounded: either an exact host or a single "*." wildcard that matches proper subdomains only.
func (Ceiling) Admit ¶
Admit normalizes raw and confirms it stays within the ceiling. It returns the normalized origin on success. Admission is purely structural: it does not resolve DNS. The caller pins a peer with Resolve and dials with Client.
func (Ceiling) AdmitOrigin ¶
AdmitOrigin confirms an already-normalized origin stays within the ceiling.
type Deadlines ¶
Deadlines bounds each phase of an outbound request.
func DefaultDeadlines ¶
func DefaultDeadlines() Deadlines
DefaultDeadlines are conservative bounds suitable for vendor management APIs.
type NetworkClass ¶
type NetworkClass string
NetworkClass classifies a concrete resolved address. It is independent of the provider proto so this package stays reusable; callers map it to their own vocabulary.
const ( ClassPublic NetworkClass = "public" ClassLoopback NetworkClass = "loopback" ClassLinkLocal NetworkClass = "link-local" ClassPrivate NetworkClass = "private" )
func Classify ¶
func Classify(ip net.IP) NetworkClass
Classify maps a concrete IP to its network class. Cloud metadata endpoints (169.254.169.254) fall in link-local and are blocked with the rest of that class unless a rule explicitly admits link-local.
type Origin ¶
Origin is a normalized, host-attested base origin. Host is a canonical lowercase ASCII hostname or IP literal with no trailing dot; Port is always explicit.
func NormalizeOrigin ¶
NormalizeOrigin parses and canonicalizes a base-origin string. It rejects anything that could smuggle a second interpretation past admission: URL userinfo, a path/query/fragment, opaque or scheme-relative forms, non-HTTP(S) schemes, and IDNA-ambiguous hosts.
type Resolution ¶
type Resolution struct {
IP net.IP
Class NetworkClass
}
Resolution is the single pinned peer for one operation.
func Resolve ¶
func Resolve(ctx context.Context, resolver *net.Resolver, origin Origin, allowed []NetworkClass) (Resolution, error)
Resolve looks up the origin host exactly once, classifies every returned address, and pins the first admitted one. If any returned address is a disallowed class the resolution fails closed — a host that returns one public and one private answer must not be dialable. An IP-literal host is classified without a lookup.
Source Files