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 ¶
const ( DefaultConcurrency = 4 DefaultCheckTimeout = 60 * time.Second )
Defaults used when Options leave a field zero.
const TXTPrefix = "scout-verify="
TXTPrefix prefixes the token in a DNS TXT record.
const WellKnownPath = "/.well-known/scout-verify.txt"
WellKnownPath is where a target can publish its ownership token.
Variables ¶
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.
var ErrCheckTimeout = errors.New("check timed out")
ErrCheckTimeout is recorded when a check exceeds its timeout.
var ErrNotVerified = errors.New("ownership not verified")
ErrNotVerified means no ownership proof was found for a host.
Functions ¶
func OwnershipToken ¶
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.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine runs scans. It is safe for concurrent use.
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 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
// DisableRecon turns off passive reconnaissance (WHOIS/DNS/subdomains). It is
// on by default; tests set this to avoid real network lookups.
DisableRecon bool
}
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.
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 ¶
Policy is the mode decision for one scan: the requested mode, the cap imposed by the environment and opt-in, and the effective mode.
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 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 ¶
NewVerifier returns a verifier using the system DNS resolver.
type Window ¶
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.