Documentation
¶
Overview ¶
Package vex holds the OpenVEX domain vocabulary (the closed justification enum, shared by the VEX export and the AI vex-justification judgment) AND the consume-side parser + product-to-finding matcher (document.go: Parse, Statement.Suppresses, Statement.MatchesFinding) shared by the post-scan VEX apply and the in-scan .vex consumer. Pure: parsing + matching only, no I/O beyond the passed-in bytes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func StatementDigest ¶ added in v0.2.0
StatementDigest is a stable content hash of a Statement, with products sorted so ordering never changes the digest. Re-importing an identical assertion is therefore idempotent (same digest), while any change to the advisory, status, justification, or product set yields a distinct digest (a new, separately-retained row).
Types ¶
type Document ¶
Document is the subset of an OpenVEX 0.2 document Synapse CONSUMES: each statement asserts a status for a vulnerability against one or more products. It is the shared parse + match core for BOTH the post-scan VEX apply (usecase/vex) and the in-scan .vex consumption (the SCA pipeline), so the two can never drift.
func Parse ¶
Parse decodes an OpenVEX document. It errors on invalid JSON or a non-OpenVEX / empty document, so a caller never silently treats junk as an empty policy.
func ParseAny ¶ added in v0.2.0
ParseAny decodes either a CSAF 2.x document (detected by document.csaf_version) or an OpenVEX document (everything else, validated by Parse). It lets one consume path accept whichever format a supplier ships.
func ParseCSAF ¶ added in v0.2.0
ParseCSAF decodes a CSAF 2.x document into the shared VEX Document. It errors on invalid JSON, a non-CSAF document, a duplicate product-id definition, a contradictory status (within a vulnerability or across two entries for the same CVE, at the resolved match-target level), or a reference to an undefined product, so a caller never treats junk or a self-contradicting assertion as a suppression policy. Each emit-eligible product_status id becomes one Statement.
type OpenVexJustification ¶
type OpenVexJustification string
OpenVexJustification is the CLOSED set of OpenVEX justifications for a not_affected status (per the OpenVEX spec). A justification is a STRUCTURED choice, never free prose – so it can ride in a judgment claim (R8).
const ( // ComponentNotPresent: the vulnerable component is not in the product at all. ComponentNotPresent OpenVexJustification = "component_not_present" // VulnerableCodeNotPresent: the component is present but the vulnerable code is not included. VulnerableCodeNotPresent OpenVexJustification = "vulnerable_code_not_present" // VulnerableCodeNotInExecutePath: the vulnerable code is present but never on an executed path. VulnerableCodeNotInExecutePath OpenVexJustification = "vulnerable_code_not_in_execute_path" // VulnerableCodeCannotBeControlled: the vulnerable code executes but an adversary cannot control the inputs. VulnerableCodeCannotBeControlled OpenVexJustification = "vulnerable_code_cannot_be_controlled_by_adversary" // InlineMitigationsAlreadyExist: a compensating control already neutralizes the vulnerability. InlineMitigationsAlreadyExist OpenVexJustification = "inline_mitigations_already_exist" )
func (OpenVexJustification) Valid ¶
func (j OpenVexJustification) Valid() bool
Valid reports whether j is one of the five OpenVEX not_affected justifications (fail-closed).
type Statement ¶
type Statement struct {
Vulnerability string // advisory id, e.g. "CVE-2024-1234"
Products []string // product ids, e.g. "pkg:npm/foo@1.0.0" or "foo@1.0.0"
Status string // OpenVEX status: not_affected | fixed | affected | under_investigation
Justification string
}
Statement is one VEX assertion.
func (Statement) MatchesFinding ¶
MatchesFinding reports whether this statement targets the given finding, identified by its advisory id + component + version (as parsed from the finding's dedup key). A product matches when its component equals the finding's (directly or by PURL name) and its version is absent (matches all versions) or equal.
func (Statement) Suppresses ¶
Suppresses reports whether this statement's status asserts "no action needed" (not_affected or fixed) – the two statuses that remove a finding from the actionable set.
type StoredStatement ¶ added in v0.2.0
type StoredStatement struct {
Advisory string // Statement.Vulnerability, denormalized for querying/audit
Digest string // stable content digest of the Statement, for idempotent persistence
Statement Statement // the faithful assertion, re-applied verbatim (same match semantics as import)
Actor string // the identity that ingested it
IngestedAt time.Time // when it was ingested (UTC)
}
StoredStatement is one persisted VEX assertion for an engagement, retained so it can be RE-APPLIED after a rescan overwrites the engagement's findings back to open. A raw apply-and-forget import would be lost on the next scan; persisting the assertion lets the pipeline re-evaluate it against the fresh finding set. It carries the faithful Statement plus provenance (who ingested it, when).
func NewStoredStatement ¶ added in v0.2.0
func NewStoredStatement(s Statement, actor string, at time.Time) StoredStatement
NewStoredStatement builds a StoredStatement with its digest computed and its ingest time normalized to UTC.
Source Files