Documentation
¶
Overview ¶
Package enginecompare produces an honest differential between two vulnerability detection engines run over the SAME SBOM: which (component, CVE) pairs each engine found, and specifically what the candidate (the owned Synapse engine) found that a baseline competitor (e.g. Grype) missed, and vice versa. It computes no pass/fail verdict and invents no ground truth — it reports the set difference of two real runs, so a "Synapse matched or beat Grype here" claim is always backed by an actual comparison, never asserted.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Divergence ¶
Divergence is one (component, CVE) pair found by one engine and not the other.
type EngineFindingSet ¶
type EngineFindingSet struct {
Name string
InputIdentity InputIdentity
Findings []vulnerability.RawFinding
}
EngineFindingSet is one precomputed engine's findings for a shared immutable input. It carries no oracle truth.
type InputIdentity ¶
type InputIdentity struct {
CatalogRevision string `json:"catalog_revision"`
CatalogDigest string `json:"catalog_digest"`
TargetDigest string `json:"target_digest"`
SBOMDigest string `json:"sbom_digest"`
}
InputIdentity binds a comparison to one immutable catalog target and SBOM input.
func (InputIdentity) Validate ¶
func (identity InputIdentity) Validate() error
Validate verifies that a comparison input is fully content-addressed.
type MultiReport ¶
type MultiReport struct {
DiagnosticOnly bool `json:"diagnostic_only"`
CandidateName string `json:"candidate_name"`
InputIdentity InputIdentity `json:"input_identity"`
Comparisons []Report `json:"comparisons"`
}
MultiReport independently compares a candidate with every supplied baseline. It is diagnostic only and deliberately contains no oracle or gate verdict.
func CompareMany ¶
func CompareMany(candidate EngineFindingSet, baselines []EngineFindingSet) (MultiReport, error)
CompareMany compares the candidate independently with every named baseline using the same canonical-ID semantics as Compare. Names are required and unique, and every finding set must bind the same immutable input.
type Report ¶
type Report struct {
BaselineName string `json:"baseline_name"`
CandidateName string `json:"candidate_name"`
ComponentCount int `json:"component_count"`
BaselinePairs int `json:"baseline_pairs"`
CandidatePairs int `json:"candidate_pairs"`
Both int `json:"both"`
CandidateOnly []Divergence `json:"candidate_only"`
BaselineOnly []Divergence `json:"baseline_only"`
// CandidateMatchesBaselineRecall is true when the candidate found EVERY (component, CVE) the baseline did
// (BaselineOnly is empty) FOR THIS run and input. It is a statement about this comparison, not a universal
// claim, and it is false the moment the baseline surfaces one pair the candidate missed.
CandidateMatchesBaselineRecall bool `json:"candidate_matches_baseline_recall"`
}
Report is the differential of two engines over one SBOM. CandidateOnly is what the owned engine found that the baseline missed (extra coverage); BaselineOnly is what the baseline found that the owned engine missed (a recall gap to investigate). Both counts are of DISTINCT (component, CVE) pairs, so multiple advisories for the same pair collapse to one.
func Compare ¶
func Compare(baselineName, candidateName string, baseline, candidate []vulnerability.RawFinding) Report
Compare computes the differential of two already-produced finding sets. It is pure (no I/O), so a CI job that has both engines' outputs can reduce them deterministically.
func Run ¶
func Run(ctx context.Context, baseline, candidate ports.DetectionSource, doc *sbom.SBOM) (Report, error)
Run scans doc with both engines and compares them. Errors from either engine abort (a partial scan would produce a misleading differential). Both engines must implement the shared DetectionSource port, so the owned engine and any competitor adapter (e.g. Grype) can be compared without special-casing either.
Source Files