scope

Documentation

Index

• Variables
• type ContextDialer
• type MatchMode
• type Options
• type Policy
  • func New(target config.TargetConfig) *Policy
  • func NewWithMode(target config.TargetConfig, mode MatchMode) (*Policy, error)
  • func NewWithOptions(target config.TargetConfig, opts Options) (*Policy, error)
  • func (p *Policy) AllowsHost(raw string) bool
  • func (p *Policy) AllowsURL(raw string) bool
  • func (p *Policy) CheckRedirect(req *http.Request, via []*http.Request) error
  • func (p *Policy) DialContext(ctx context.Context, network, address string) (net.Conn, error)
  • func (p *Policy) FilterHosts(hosts []string) []string
  • func (p *Policy) FilterURLs(urls []string) []string
  • func (p *Policy) Mode() MatchMode
  • func (p *Policy) ResolveAndValidateHost(ctx context.Context, raw string) ([]net.IPAddr, error)
  • func (p *Policy) SafeHTTPClient(base *http.Client) *http.Client
  • func (p *Policy) SafeTransport(base *http.Transport) *http.Transport
  • func (p *Policy) ValidateURL(ctx context.Context, raw string) error
  • func (p *Policy) ValidationError() error
• type PublicOriginOptions
• type PublicOriginPolicy
  • func NewPublicOriginPolicy(raw string, opts PublicOriginOptions) (*PublicOriginPolicy, error)
  • func (p *PublicOriginPolicy) AllowsURL(raw string) bool
  • func (p *PublicOriginPolicy) DialContext(ctx context.Context, network, address string) (net.Conn, error)
  • func (p *PublicOriginPolicy) Origin() string
  • func (p *PublicOriginPolicy) ResolveAndValidate(ctx context.Context) ([]net.IPAddr, error)
  • func (p *PublicOriginPolicy) SafeHTTPClient(base *http.Client) *http.Client
  • func (p *PublicOriginPolicy) SafeTransport(base *http.Transport) *http.Transport
  • func (p *PublicOriginPolicy) ValidateURL(ctx context.Context, raw string) error
• type Resolver

Variables

var (
	ErrInvalidPublicOrigin = errors.New("invalid public HTTPS origin")
	ErrOriginMismatch      = errors.New("request is outside the configured HTTPS origin")
)

var (
	ErrInvalidTarget = errors.New("invalid scope target")
	ErrOutOfScope    = errors.New("host is outside the authorized scope")
	ErrUnsafeAddress = errors.New("host resolves to a non-public address")
)

Types

type ContextDialer

type ContextDialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

ContextDialer is the subset of net.Dialer used by the guarded transport. Supplying one is primarily useful for tests and controlled runtimes.

type MatchMode

type MatchMode string

MatchMode controls whether an authorized root also authorizes its children.

const (
	// ModeRules derives authorization from each configured rule: a bare hostname
	// is exact, while a leading "*." explicitly includes its DNS children.
	ModeRules MatchMode = "rules"
	// ModeSubdomains forces every configured root to authorize both the root
	// itself and all of its DNS subdomains.
	ModeSubdomains MatchMode = "subdomains"
	// ModeExact authorizes configured hostnames only.
	ModeExact MatchMode = "exact"
)

type Options

type Options struct {
	Mode     MatchMode
	Resolver Resolver
	Dialer   ContextDialer
}

Options configures a Policy. A zero Mode uses the explicit rule syntax: bare hostnames are exact and "*." rules include children.

type Policy

type Policy struct {
	// contains filtered or unexported fields
}

Policy is the single source of truth for deciding whether a host or URL is authorized for active scanning. Static Allows* methods never perform DNS. ResolveAndValidateHost, DialContext, and CheckRedirect add network safety.

func New

func New(target config.TargetConfig) *Policy

New derives scope from the configured rules. Bare domains are exact; only a leading "*." authorizes children. Invalid rules create a fail-closed policy; ValidationError exposes the reason.

func NewWithMode

func NewWithMode(target config.TargetConfig, mode MatchMode) (*Policy, error)

NewWithMode creates a policy using an explicit matching mode.

func NewWithOptions

func NewWithOptions(target config.TargetConfig, opts Options) (*Policy, error)

NewWithOptions validates every configured rule and returns a fail-closed policy on error. Public suffixes, single-label names, IP literals, alternative IP spellings, and malformed DNS names are never valid authorization roots.

func (*Policy) AllowsHost

func (p *Policy) AllowsHost(raw string) bool

func (*Policy) AllowsURL

func (p *Policy) AllowsURL(raw string) bool

func (*Policy) CheckRedirect

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

CheckRedirect is suitable for http.Client.CheckRedirect. It validates scope and DNS on every hop. Sensitive headers are removed on host changes before the request can be sent, even when both hosts are otherwise in scope.

func (*Policy) DialContext

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

DialContext is suitable for http.Transport.DialContext. It resolves on every new connection, validates every returned address, then dials the already resolved numeric IP. This removes the DNS-check-to-connect TOCTOU window.

func (*Policy) FilterHosts

func (p *Policy) FilterHosts(hosts []string) []string

func (*Policy) FilterURLs

func (p *Policy) FilterURLs(urls []string) []string

func (*Policy) Mode

func (p *Policy) Mode() MatchMode

Mode returns the policy's configured matching behavior.

func (*Policy) ResolveAndValidateHost

func (p *Policy) ResolveAndValidateHost(ctx context.Context, raw string) ([]net.IPAddr, error)

ResolveAndValidateHost resolves an authorized hostname and rejects the entire answer set when any address is non-public. No DNS result is cached: each call represents a fresh connection/redirect boundary.

func (*Policy) SafeHTTPClient

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

SafeHTTPClient returns a shallow clone of base (or a default client) wired for guarded direct connections and redirect validation.

func (*Policy) SafeTransport

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

SafeTransport clones base (or http.DefaultTransport) and installs the guarded dialer. Proxies are disabled because a proxy would resolve the hostname again, defeating address validation and IP pinning.

func (*Policy) ValidateURL

func (p *Policy) ValidateURL(ctx context.Context, raw string) error

ValidateURL performs the network-aware URL check used at redirect boundaries.

func (*Policy) ValidationError

func (p *Policy) ValidationError() error

ValidationError is non-nil when the backward-compatible New constructor had to create a deny-all policy because one of its rules was unsafe.

type PublicOriginOptions

type PublicOriginOptions struct {
	Resolver Resolver
	Dialer   ContextDialer
}

PublicOriginOptions provides deterministic resolver/dialer injection for a public service endpoint such as an AI API. Production callers normally leave both fields nil.

type PublicOriginPolicy

type PublicOriginPolicy struct {
	// contains filtered or unexported fields
}

PublicOriginPolicy protects an exact HTTPS origin that is intentionally outside target scope. It rejects mixed/non-public DNS answers and connects to a validated numeric address, while TLS still authenticates the request URL's original hostname.

func NewPublicOriginPolicy

func NewPublicOriginPolicy(raw string, opts PublicOriginOptions) (*PublicOriginPolicy, error)

NewPublicOriginPolicy validates the lexical origin. DNS is intentionally checked again at every connection boundary instead of being trusted here. Paths are permitted for versioned API bases; userinfo, queries, fragments, local names, public suffixes, and alternative IP spellings are not.

func (*PublicOriginPolicy) AllowsURL

func (p *PublicOriginPolicy) AllowsURL(raw string) bool

AllowsURL is a DNS-free exact-origin check suitable for request dispatch.

func (*PublicOriginPolicy) DialContext

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

DialContext pins each new connection to a freshly validated numeric address.

func (*PublicOriginPolicy) Origin

func (p *PublicOriginPolicy) Origin() string

Origin returns the canonical scheme/host/effective-port tuple and never includes a path, userinfo, query, or fragment.

func (*PublicOriginPolicy) ResolveAndValidate

func (p *PublicOriginPolicy) ResolveAndValidate(ctx context.Context) ([]net.IPAddr, error)

ResolveAndValidate resolves the configured origin and rejects the entire answer set if even one address is private or special-use.

func (*PublicOriginPolicy) SafeHTTPClient

func (p *PublicOriginPolicy) SafeHTTPClient(base *http.Client) *http.Client

SafeHTTPClient returns a clone that refuses cross-origin requests and every redirect. http.ErrUseLastResponse prevents net/http from wrapping an untrusted Location URL into a diagnostic while still returning the bounded response to the caller for status handling.

func (*PublicOriginPolicy) SafeTransport

func (p *PublicOriginPolicy) SafeTransport(base *http.Transport) *http.Transport

SafeTransport installs the public-address dialer and removes every alternate direct-TLS/proxy path that could bypass it.

func (*PublicOriginPolicy) ValidateURL

func (p *PublicOriginPolicy) ValidateURL(ctx context.Context, raw string) error

ValidateURL verifies both exact origin and current public DNS without ever reflecting the caller-controlled URL in its error.

type Resolver

type Resolver interface {
	LookupIPAddr(ctx context.Context, host string) ([]net.IPAddr, error)
}

Resolver is deliberately compatible with net.Resolver and injectable so callers can make DNS decisions deterministic in tests.