Documentation
¶
Overview ¶
Package engine orchestrates a run: it expands a Saga into scan jobs (controllers × components), executes them with bounded parallelism, and aggregates each control's results. Content-hash caching and the full describe→publish pipeline build on this.
Index ¶
- type Engine
- type Option
- type PlannedJob
- type Prioritizer
- type Registry
- func (r *Registry) Controller(name string) (plugin.Controller, bool)
- func (r *Registry) Controllers() []plugin.Controller
- func (r *Registry) RegisterController(c plugin.Controller)
- func (r *Registry) RegisterScanner(s plugin.Scanner)
- func (r *Registry) Scanner(name string) (plugin.Scanner, bool)
- func (r *Registry) Scanners() []plugin.Scanner
- type Result
- type Stats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine plans and runs scans against a registry of controllers and scanners.
func New ¶
New creates an Engine over the given registry. By default it runs up to NumCPU jobs concurrently.
func (*Engine) Plan ¶
func (e *Engine) Plan(model saga.Model) ([]PlannedJob, error)
Plan expands the model into scan jobs. Only registered controllers that are enabled (project-level for project-scoped controllers, per-component for component-scoped ones) are planned. Controllers are visited in name order for determinism.
type Option ¶
type Option func(*Engine)
Option configures an Engine.
func WithCache ¶
WithCache enables result caching: a cache hit for a job's key reuses the stored report instead of re-scanning. A nil cache disables caching (the default).
func WithConcurrency ¶
WithConcurrency sets the maximum number of scan jobs running at once. Values < 1 are ignored (the default is used).
func WithPrioritization ¶ added in v0.5.0
func WithPrioritization(p Prioritizer) Option
WithPrioritization stamps each finding with a priority band computed by p. Priority is applied per run (never cached), since it depends on the component's current classification.
type PlannedJob ¶
type PlannedJob struct {
Control string
Job plugin.ScanJob
Exposure saga.Exposure
Criticality saga.Criticality
}
PlannedJob is a scan job tagged with the control that produced it and the risk classification of the component it targets (empty for project-scoped controls).
type Prioritizer ¶ added in v0.5.0
type Prioritizer func(control string, exposure saga.Exposure, criticality saga.Criticality, res sarif.Result) string
Prioritizer computes a finding's priority band from its control and its component's risk classification. Injected via WithPrioritization so the engine stays decoupled from the prioritization matrices and per-control severity floors; nil disables priority stamping.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds the controllers and scanners available to the engine, keyed by name.
func (*Registry) Controller ¶
func (r *Registry) Controller(name string) (plugin.Controller, bool)
Controller returns the named controller, if registered.
func (*Registry) Controllers ¶ added in v0.18.0
func (r *Registry) Controllers() []plugin.Controller
Controllers returns all registered controllers, sorted by Info().Name for stable output.
func (*Registry) RegisterController ¶
func (r *Registry) RegisterController(c plugin.Controller)
RegisterController adds a controller, keyed by its Info().Name.
func (*Registry) RegisterScanner ¶
RegisterScanner adds a scanner, keyed by its Info().Name.
type Result ¶
type Result struct {
Controls map[string]plugin.ControlResult
Stats Stats
// ScanErrors records, per control, what stopped it completing — a missing scanner binary, a
// tool that exited badly, a plan that couldn't be built. A control listed here checked less
// than it was asked to, so its absence of findings is not evidence of absence, and callers
// that treat an empty report as "clean" would be wrong.
ScanErrors map[string][]string
}
Result is the outcome of a run: one aggregated ControlResult per control, plus run statistics.
type Stats ¶
type Stats struct {
Jobs int
Scans int
CacheHits int
// Deduped counts jobs that reused an identical scan already running/completed in this run
// (in-run singleflight), rather than scanning or hitting the persistent cache.
Deduped int
// Concurrency is the maximum number of scan jobs run in parallel for this run (the
// effective value after applying WithConcurrency or the NumCPU default).
Concurrency int
}
Stats summarizes execution, including cache effectiveness.
Source Files