engine

package
v0.30.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNoAuditor indicates no auditor supports a request.
	ErrNoAuditor = errors.New("no auditor available")
	// ErrNoMatcher indicates no matcher supports a request.
	ErrNoMatcher = errors.New("no matcher available")
)

Functions

func DeduplicateFindings

func DeduplicateFindings(findings []model.Finding) []model.Finding

DeduplicateFindings removes duplicate package/vulnerability findings, keeping the highest-priority source.

func Evaluates added in v0.30.0

func Evaluates(requirement plugin.Requirement) bool

Evaluates reports whether this host can vouch for requirement at all. A token it cannot evaluate is never satisfied, whatever the target.

func SingleGraphContainer

func SingleGraphContainer(g *model.Graph, manifest model.ManifestMetadata) *model.GraphContainer

SingleGraphContainer wraps a single graph entry.

Types

type BaselineEvaluation added in v0.20.0

type BaselineEvaluation struct {
	Path      string
	Entries   int
	Automatic bool
}

BaselineEvaluation identifies the baseline used during policy evaluation.

type ComponentOptions

type ComponentOptions = registry.ComponentOptions

ComponentOptions records Bomly-owned registry behavior for a component.

type ConsolidatedGraphResult

type ConsolidatedGraphResult struct {
	ExecutionTarget plugin.ExecutionTarget
	Graph           *model.Graph
	Subprojects     []plugin.ConsolidatedSubproject
}

ConsolidatedGraphResult describes a merged view above per-subproject graph results.

type DetailProgressReporter

type DetailProgressReporter interface {
	Detail(label, detail string)
}

DetailProgressReporter is optionally implemented by progress renderers that can show the current subproject or detector without expanding the public coarse progress contract.

type DetectorDiscoveryPlan

type DetectorDiscoveryPlan = registry.DetectorDiscoveryPlan

DetectorDiscoveryPlan describes how one detector participates in runtime planning.

type Engine

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

Engine orchestrates detector and auditor execution.

func NewEngine

func NewEngine(registry *Registry) *Engine

NewEngine creates a scan engine with the provided registry.

func (*Engine) Analyze

Analyze runs registered analyzers against the graph and returns the reachability-annotated graph. Each call is a transaction over its own AnalyzeRequest.Clone, committed only on success, exactly as Match's are. Unlike Audit, Analyze does NOT error when zero analyzers apply — reachability is opt-in and a request with no applicable analyzers is a normal outcome.

func (*Engine) Audit

Audit selects auditors by priority and aggregates their findings.

func (*Engine) Match

func (e *Engine) Match(ctx context.Context, req plugin.MatchRequest) (MatchResult, error)

Match runs registered matchers against the graph and returns the enriched graph.

Each call is a transaction over a snapshot (dev-docs/ARCHITECTURE.md, Scan Pipeline): every Ready, Applicable and Match call receives its own MatchRequest.Clone, so a matcher never holds the host's graph, registry or target. Only a successful Match is committed -- its Registry if it returned one, otherwise its PackageUpdates merged into the canonical registry -- and a failed or cancelled one leaves the canonical state exactly as the previous matcher left it. Changes a matcher makes to the graph or target are never committed, as they never were for a managed plugin, whose request crosses the wire as a copy.

type ExplainRequest

type ExplainRequest struct {
	Query    string
	Pipeline PipelineRequest
}

ExplainRequest defines input for an explain pipeline run.

type ExplainResult

type ExplainResult struct {
	PipelineResult
	Targets             []ExplainTarget
	FocusedConsolidated plugin.ConsolidatedGraph
	FocusedGraph        *model.Graph
}

ExplainResult contains full and focused explain pipeline output.

type ExplainTarget

type ExplainTarget struct {
	Manifest     plugin.ConsolidatedManifest
	Dependency   *model.DependencyNode
	Paths        []explain.Path
	Findings     []model.Finding
	FocusedGraph *model.Graph
}

ExplainTarget contains one selected manifest where the queried dependency exists.

type MatchResult

type MatchResult struct {
	Registry                    *model.PackageRegistry
	MatcherStats                []plugin.MatcherStats
	VulnerabilitiesConsolidated int
}

MatchResult contains aggregate matcher output after the engine runs all selected matchers for a pipeline stage.

type Pipeline

type Pipeline struct {
	Registry *Registry
	Logger   *zap.Logger
	// contains filtered or unexported fields
}

Pipeline orchestrates a full scan through a sequence of typed stages: detect (resolve + consolidate) -> match -> analyze -> audit.

func NewPipeline

func NewPipeline(registry *Registry, logger *zap.Logger) *Pipeline

NewPipeline creates a pipeline backed by the given registry.

func (*Pipeline) Run

Run executes the full pipeline and returns a consolidated result.

func (*Pipeline) RunAuditGraph

func (p *Pipeline) RunAuditGraph(ctx context.Context, graph *model.Graph, registry *model.PackageRegistry, req PipelineRequest) (plugin.AuditResult, []PipelineWarning)

RunAuditGraph evaluates policy for graph using req's configured auditors.

func (*Pipeline) RunExplain

func (p *Pipeline) RunExplain(ctx context.Context, req ExplainRequest) (ExplainResult, error)

RunExplain resolves, enriches, and optionally audits selected manifests for an explain query.

func (*Pipeline) RunPreAudit

func (p *Pipeline) RunPreAudit(ctx context.Context, req PipelineRequest) (PipelineResult, error)

RunPreAudit executes the pipeline through enrichment and analysis, stopping before policy evaluation.

type PipelineRequest

type PipelineRequest struct {
	ProjectPath                string
	ExecutionTarget            plugin.ExecutionTarget
	Subprojects                []plugin.Subproject
	EnrichEnabled              bool
	MatchEnabled               bool
	AuditEnabled               bool
	AnalyzeReachabilityEnabled bool
	ScopeFilter                model.Scope
	AuditorFilter              plugin.AuditorFilter
	MatcherFilter              plugin.MatcherFilter
	AnalyzerFilter             plugin.AnalyzerFilter
	DetectorFilter             plugin.DetectorFilter
	FailOn                     []model.FailOnConstraint
	AllowVulnerabilityIDs      []string
	AllowLicenses              []string
	DenyLicenses               []string
	LicenseExemptPackages      []string
	DenyPackages               []string
	DenyGroups                 []string
	ProtectedPackages          []string
	TyposquatThreshold         float64
	TyposquatMode              string
	WarnOnly                   bool
	DependencyDetailChanges    []model.DependencyDetailTransition
	FindingPolicyResolvers     []model.FindingPolicyResolver
	BaselineEvaluation         *BaselineEvaluation
	BaselineGraph              *model.Graph
	InstallFirst               bool
	InstallArgs                []string
	CoreVersion                string
	Stderr                     io.Writer
	Verbose                    bool
	Progress                   ProgressReporter
}

PipelineRequest defines input for a full pipeline run.

type PipelineResult

type PipelineResult struct {
	ResolveResults []plugin.DetectionResult
	Consolidated   plugin.ConsolidatedGraph
	Graph          *model.Graph
	Registry       *model.PackageRegistry
	Findings       []model.Finding
	RiskScores     []model.RiskScore
	// DetectorWarnings are every non-fatal detection problem in one list:
	// resolution failures and detector fallbacks the engine observed, plus the
	// package-manager warnings detectors reported alongside their graphs. Each
	// carries a type, so consumers that care only about degraded coverage filter
	// on DetectorWarning.DegradesCoverage rather than on the list being empty.
	DetectorWarnings []plugin.DetectorWarning
	AuditWarnings    []PipelineWarning
	MatchWarnings    []PipelineWarning
	AnalyzeWarnings  []PipelineWarning
	MatcherStats     []plugin.MatcherStats
	AuditorRuns      []string
	AnalyzerRuns     []string
	AuditorFindings  map[string]int
	AnalyzerStats    map[string]plugin.ReachabilityStats
	PartialErrors    error
}

PipelineResult contains the full output of a pipeline run.

type PipelineStage added in v0.30.0

type PipelineStage string

PipelineStage names one stage of the fixed pipeline.

const (
	StageDetect  PipelineStage = "detect"
	StageMatch   PipelineStage = "match"
	StageAnalyze PipelineStage = "analyze"
	StageAudit   PipelineStage = "audit"
)

The stages, in the order the pipeline runs them.

type PipelineWarning

type PipelineWarning struct {
	Source  string // detector, auditor, or matcher name
	Message string // human-readable warning text
}

PipelineWarning is a structured warning captured during a pipeline stage.

func PipelineWarningsFromError

func PipelineWarningsFromError(err error, prefix string) []PipelineWarning

PipelineWarningsFromError converts a (possibly joined) error into structured pipeline warnings. It extracts the source name from error messages that follow the pattern "<prefix> <name>: <message>" (e.g. "auditor osv: not ready").

type PreflightError added in v0.30.0

type PreflightError struct {
	Issues []PreflightIssue
}

PreflightError reports explicitly selected components the plan can never run. It is returned before any stage starts.

func (*PreflightError) Error added in v0.30.0

func (e *PreflightError) Error() string

Error lists every issue, so one run reports all of them.

type PreflightIssue added in v0.30.0

type PreflightIssue struct {
	Kind        plugin.PluginKind
	Component   string
	Stage       PipelineStage
	Requirement plugin.Requirement
	// Explicit reports whether the user's selection is why the component is
	// in the plan; see selectedExplicitly.
	Explicit bool
	// Satisfy says what is missing and what would supply it.
	Satisfy string
}

PreflightIssue is one declared requirement the host cannot vouch for at the stage the component runs in.

func (PreflightIssue) String added in v0.30.0

func (i PreflightIssue) String() string

String renders the issue as one actionable sentence.

type ProgressReporter

type ProgressReporter interface {
	StartStage(label string, total int)
	AdvanceStage(label string, completed, total int)
	CompleteStage(label string, total int)
}

ProgressReporter receives coarse pipeline progress events.

type Registry

type Registry struct {
	*registry.Registry
}

Registry wraps the shared registry with scan-specific registration helpers.

func NewRegistry

func NewRegistry(configs RegistryConfigs, logger zap.Logger) *Registry

NewRegistry creates an empty scan registry.

func (*Registry) Filter

func (r *Registry) Filter(filter RegistryFilter) *Registry

Filter returns a copy of the registry filtered by the supplied detector, auditor, matcher, and ecosystem selections.

type RegistryConfigs

type RegistryConfigs = registry.Configs

RegistryConfigs holds built-in registry wiring options resolved by the CLI layer.

type RegistryFilter

type RegistryFilter = registry.Filter

RegistryFilter narrows a registry down to the runtime-relevant selections.

Directories

Path Synopsis
Package diff runs two engine pipelines and classifies their audit deltas.
Package diff runs two engine pipelines and classifies their audit deltas.
Package scan exposes the command-facing scan pipeline API.
Package scan exposes the command-facing scan pipeline API.

Jump to

Keyboard shortcuts

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