2.0 KiB
2.0 KiB
VEX Evidence and Consensus (Detailed)
This document complements docs/VEX_CONSENSUS_GUIDE.md with implementation-oriented detail: what objects exist, how evidence is correlated without rewriting sources, and what "consensus" means in practice.
Pipeline (Evidence First)
- Ingest raw VEX as immutable observations (append-only, provenance preserved).
- Normalize observations into tuples used for correlation and UI display.
- Correlate tuples into deterministic linksets (grouping without merge or precedence).
- Compute consensus (optional) using issuer trust and lattice rules to produce an “effective” status and conflict summary.
- Expose evidence to Policy Engine, Console, and Vulnerability Explorer; include in Offline Kit snapshots.
Core Objects
- Raw observation: upstream OpenVEX/CSAF/CycloneDX payload stored losslessly with provenance (issuer/provider, receive time, signature verification, content digest).
- Normalized tuple: extracted fields used for correlation and decisioning, typically
(vulnerabilityId, productKey, status, justification?, scope?, timestamp, sourceDigest). - Linkset: a correlation group tying multiple tuples to the same conceptual
(vulnerabilityId, productKey)without collapsing disagreements. - Consensus record: a deterministic summary for a linkset: effective status, confidence/weight, and conflict list (still referencing raw evidence).
Determinism Guarantees
- Canonical UTF-8 JSON bytes are hashed to compute stable digests for raw observations.
- Linkset IDs are derived from canonical, sorted key material.
- Consensus outputs are stable for identical inputs: ordering, timestamps, and digests are deterministic.
Where This Lives
- Ingestion, raw store, and linksets:
docs/modules/excititor/architecture.md - Consensus and issuer trust:
docs/modules/vex-lens/architecture.md - Console/operator view:
docs/UI_GUIDE.md - Triage model:
docs/VULNERABILITY_EXPLORER_GUIDE.md