engine

package
v0.4.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package engine runs scans: it selects checks permitted by the environment's mode cap, executes them against in-scope targets and streams findings.

Index

Constants

View Source
const (
	DefaultConcurrency  = 4
	DefaultCheckTimeout = 60 * time.Second
)

Defaults used when Options leave a field zero.

View Source
const TXTPrefix = "scout-verify="

TXTPrefix prefixes the token in a DNS TXT record.

View Source
const WellKnownPath = "/.well-known/scout-verify.txt"

WellKnownPath is where a target can publish its ownership token.

Variables

View Source
var (
	// ErrKilled is returned when the global kill switch is engaged.
	ErrKilled = errors.New("scout: scan killed by kill switch")
	// ErrOutsideWindow is returned when the request falls outside the allowed
	// scan window.
	ErrOutsideWindow = errors.New("scout: request outside allowed scan window")
	// ErrOutOfScope is returned when the request target is not in scope.
	ErrOutOfScope = errors.New("scout: request target out of scope")
)

Guard errors. These are returned by the guard transport before any request reaches the network, so callers can tell a blocked request apart from a real transport failure.

View Source
var ErrCheckTimeout = errors.New("check timed out")

ErrCheckTimeout is recorded when a check exceeds its timeout.

View Source
var ErrNotVerified = errors.New("ownership not verified")

ErrNotVerified means no ownership proof was found for a host.

Functions

func NewScanID

func NewScanID() string

NewScanID returns a random 128-bit scan identifier.

func OwnershipToken

func OwnershipToken(key []byte, host string) string

OwnershipToken is the token a host must publish to prove its owner wants it scanned. With a key it is an HMAC unique to this Scout installation; without one it is a plain hash of the host.

Types

type Bus

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

Bus fans events out to subscribers. Publishing never blocks: a slow subscriber drops events instead of stalling the scan.

func NewBus

func NewBus() *Bus

NewBus returns an empty bus.

func (*Bus) Dropped

func (b *Bus) Dropped() int64

Dropped is how many events were dropped because a subscriber was full.

func (*Bus) Publish

func (b *Bus) Publish(e Event)

Publish delivers e to every subscriber that has room.

func (*Bus) Subscribe

func (b *Bus) Subscribe(buffer int) (<-chan Event, func())

Subscribe returns a channel of events and a function that unsubscribes and closes it.

type Decision

type Decision struct {
	Check  core.Check
	Run    bool
	Reason string // empty when Run is true
}

Decision says whether one check will run in a scan, and why not if not.

type Engine

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

Engine runs scans. It is safe for concurrent use.

func New

func New(reg *core.Registry, opts Options) *Engine

New returns an engine that draws checks from reg.

func (*Engine) Checks

func (e *Engine) Checks() []core.Check

Checks returns every registered check, sorted by ID.

func (*Engine) Plan

func (e *Engine) Plan(ctx context.Context, req Request) (Plan, error)

Plan returns what Run would do for req without running any check. The only traffic it may send is the read-only ownership lookup (DNS TXT or the well-known file) that Run would also make before Active mode.

func (*Engine) Run

func (e *Engine) Run(ctx context.Context, req Request) (core.ScanResult, error)

Run executes a scan and returns its result. Check failures are recorded in the result, never returned: only a broken request fails Run.

type Event

type Event struct {
	Type    EventType     `json:"type"`
	ScanID  string        `json:"scan_id"`
	Time    time.Time     `json:"time"`
	CheckID string        `json:"check_id,omitempty"`
	Count   int           `json:"count,omitempty"` // findings from one check
	Error   string        `json:"error,omitempty"`
	Finding *core.Finding `json:"finding,omitempty"`
	// Total and Done report progress on scan.started and check.finished.
	Total int `json:"total,omitempty"`
	Done  int `json:"done,omitempty"`
	// Result is set on scan.finished. Findings are omitted to keep events small.
	Result *core.ScanResult `json:"result,omitempty"`
}

Event is published on the Bus as a scan progresses.

type EventType

type EventType string

EventType names a scan lifecycle event.

const (
	EventScanStarted   EventType = "scan.started"
	EventCheckFinished EventType = "check.finished"
	EventFinding       EventType = "finding"
	EventScanFinished  EventType = "scan.finished"
)

type KillSwitch

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

KillSwitch is a goroutine-safe global stop control for a scan. Once Kill is called every in-flight and subsequent guarded request fails fast with ErrKilled until Resume is called. The zero value is not usable — construct with NewKillSwitch.

func NewKillSwitch

func NewKillSwitch() *KillSwitch

NewKillSwitch returns a KillSwitch in the running (not killed) state.

func (*KillSwitch) Kill

func (k *KillSwitch) Kill()

Kill engages the switch. Safe to call repeatedly and from any goroutine.

func (*KillSwitch) Killed

func (k *KillSwitch) Killed() bool

Killed reports whether the switch is currently engaged.

func (*KillSwitch) Resume

func (k *KillSwitch) Resume()

Resume disengages the switch, allowing guarded requests through again.

type Options

type Options struct {
	// Concurrency is how many checks run at once.
	Concurrency int
	// CheckTimeout bounds each check run.
	CheckTimeout time.Duration
	Logger       *slog.Logger
	// Now is the clock; tests override it.
	Now func() time.Time

	// Scope limits what checks may touch. Empty Hosts means only the
	// target's own host.
	Scope core.Scope
	// RateLimit is max requests per second per host; <= 0 disables it.
	RateLimit int
	// Window restricts when scans may run; nil allows any time.
	Window *Window
	// Kill is the global kill switch; nil means none.
	Kill *KillSwitch
	// Transport is the base HTTP transport; nil uses http.DefaultTransport.
	Transport http.RoundTripper
	// SigningKey signs the X-Scout-Scan header. Empty generates a random
	// key per engine, which Sentinel cannot verify; set it to share one.
	SigningKey []byte
	// Verifier proves target ownership before Active mode on non-local
	// hosts. Nil uses DNS and the well-known file, keyed by SigningKey.
	Verifier *Verifier
	// Store persists scans and supplies history for FirstSeen and status
	// carry-over. Nil keeps results in memory only.
	Store storage.Store
	// Bus receives scan progress and finding events. Nil disables events.
	Bus *Bus
	// Scoring tunes the score; Assessed is filled from the checks that ran.
	Scoring scoring.Options
}

Options configure an Engine.

type Plan

type Plan struct {
	Target    core.Target `json:"target"`
	Requested core.Mode   `json:"requested_mode"`
	Effective core.Mode   `json:"effective_mode"`
	CapReason string      `json:"cap_reason"`
	Entries   []PlanEntry `json:"entries"`
}

Plan is what a scan would do, computed by the same policy code Run uses.

func (Plan) Counts

func (p Plan) Counts() (run, skipped int)

Counts returns how many checks would run and be skipped.

func (Plan) Render

func (p Plan) Render(w io.Writer) error

Render writes the plan as a human-readable table.

type PlanEntry

type PlanEntry struct {
	CheckID     string        `json:"check_id"`
	Category    core.Category `json:"category"`
	Mode        core.Mode     `json:"mode"`
	Run         bool          `json:"run"`
	Reason      string        `json:"reason,omitempty"`
	Description string        `json:"description,omitempty"`
}

PlanEntry is one check's fate in a planned scan.

type Policy

type Policy struct {
	Requested core.Mode
	Cap       core.Mode
	CapReason string
	Effective core.Mode
}

Policy is the mode decision for one scan: the requested mode, the cap imposed by the environment and opt-in, and the effective mode.

func NewPolicy

func NewPolicy(t core.Target, requested core.Mode) Policy

NewPolicy caps the requested mode by the target's environment and opt-in.

func (Policy) Decide

func (p Policy) Decide(c core.Check) Decision

Decide applies the policy to one check.

type Request

type Request struct {
	Target core.Target
	// Mode is the requested mode; the engine caps it by policy.
	Mode core.Mode
	// Checks restricts the scan to these check IDs (used by "verify fix").
	// Empty means every registered check.
	Checks []string
	// ID is the scan ID to use; empty generates one. Lets callers that run
	// scans in the background return the ID immediately.
	ID string
	// Ephemeral runs without loading history or persisting the result, for
	// one-off re-checks such as "verify fix".
	Ephemeral bool
}

Request describes one scan.

type Resolver

type Resolver interface {
	LookupTXT(ctx context.Context, name string) ([]string, error)
}

Resolver looks up DNS TXT records. *net.Resolver satisfies it.

type Verifier

type Verifier struct {
	Key      []byte
	Resolver Resolver
	// TTL is how long a successful verification is cached.
	TTL time.Duration
	Now func() time.Time
	// contains filtered or unexported fields
}

Verifier checks target ownership by DNS TXT record or well-known file and caches successes.

func NewVerifier

func NewVerifier(key []byte) *Verifier

NewVerifier returns a verifier using the system DNS resolver.

func (*Verifier) Verify

func (v *Verifier) Verify(ctx context.Context, t core.Target, client *http.Client) (string, error)

Verify proves ownership of t's host. It returns how it was proven ("local", "dns", "well-known", "cached"). The HTTP check uses client, which must be the scan's guarded client.

type Window

type Window struct {
	Start, End string
	Days       []time.Weekday
	Location   *time.Location
}

Window describes when scanning is permitted. A nil *Window allows all times.

Start and End are "HH:MM" in 24-hour time, interpreted in Location. If End is less than or equal to Start the window wraps past midnight (e.g. 22:00–06:00). Days, if non-empty, restricts the window to those weekdays; an empty Days means every day. If Location is nil, time.Local is used.

A Window is a safety control, so it fails closed: a malformed Start/End string causes Allows to return false.

func (*Window) Allows

func (w *Window) Allows(t time.Time) bool

Allows reports whether t falls inside the window.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL