netgate

Documentation

Overview

Package netgate issues the only HTTP clients and DNS resolvers a module may use. Authorization is enforced in the transport rather than in calling code, so a module cannot reach an unauthorized host by forgetting a check: the dial is refused before a packet leaves the process.

Index

• type Class
  • func ParseClass(s string) (Class, error)
• type Gate
  • func New(policy *scope.Policy, opts ...Option) *Gate
  • func (g *Gate) HTTPClient(grant Grant, timeout time.Duration) *http.Client
  • func (g *Gate) Permits(host string) bool
  • func (g *Gate) Resolver(grant Grant) *Resolver
  • func (g *Gate) Violations() []core.Violation
• type Grant
• type Option
  • func WithClock(now func() time.Time) Option
• type Resolver
  • func (r *Resolver) LookupCNAME(ctx context.Context, host string) (string, error)
  • func (r *Resolver) LookupHost(ctx context.Context, host string) ([]string, error)
• type Violation
  • func AsViolation(err error) (*Violation, bool)
  • func (v *Violation) Error() string

Types

type Class

type Class string

Class is a module's declared activity. It decides which hosts the module's clients will dial at all.

const (
	// Passive modules may reach their own provider endpoints only.
	Passive Class = "passive"
	// Active modules may reach hosts the scope policy authorizes.
	Active Class = "active"
)

func ParseClass

func ParseClass(s string) (Class, error)

ParseClass validates an activity class read from a descriptor or config.

type Gate

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

Gate holds the policy for a run and records every refusal.

func New

func New(policy *scope.Policy, opts ...Option) *Gate

New returns a Gate enforcing policy. Policy is read here and never mutated.

func (*Gate) HTTPClient

func (g *Gate) HTTPClient(grant Grant, timeout time.Duration) *http.Client

HTTPClient returns a client that refuses to dial any host outside grant.

func (*Gate) Permits

func (g *Gate) Permits(host string) bool

Permits exposes the run's policy for recording an asset's in-scope flag. It answers a question; it does not authorize a connection.

func (*Gate) Resolver

func (g *Gate) Resolver(grant Grant) *Resolver

Resolver returns a resolver bound to grant.

func (*Gate) Violations

func (g *Gate) Violations() []core.Violation

Violations returns every refusal recorded so far.

type Grant

type Grant struct {
	ModuleID string
	Class    Class
	// Endpoints are provider hostnames a passive module may reach. An entry
	// may be a wildcard such as "*.crt.sh".
	Endpoints []string
}

Grant is what a module is allowed to talk to. The pipeline builds it from the module's descriptor; a module never constructs its own.

type Option

type Option func(*Gate)

Option configures a Gate.

func WithClock

func WithClock(now func() time.Time) Option

WithClock replaces the clock used to timestamp violations.

type Resolver

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

Resolver is the only DNS entry point a module gets. A passive module is handed one that refuses every name: resolving a discovered host is active work, and the provider hostname a passive module talks to is resolved inside the HTTP dial, not here.

func (*Resolver) LookupCNAME

func (r *Resolver) LookupCNAME(ctx context.Context, host string) (string, error)

LookupCNAME returns the canonical name for host.

func (*Resolver) LookupHost

func (r *Resolver) LookupHost(ctx context.Context, host string) ([]string, error)

LookupHost resolves host to addresses.

type Violation

type Violation struct {
	ModuleID string
	Target   string
	Reason   string
	At       time.Time
}

Violation is an attempt to reach a host the policy did not authorize. It is returned to the caller as an error and recorded on the Gate, because a module that swallows the error must still show up in the run summary.

func AsViolation

func AsViolation(err error) (*Violation, bool)

AsViolation reports whether err was caused by a refused dial.

func (*Violation) Error

func (v *Violation) Error() string