32 lines
2.0 KiB
Markdown
32 lines
2.0 KiB
Markdown
# 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)
|
|
|
|
1. **Ingest raw VEX** as immutable observations (append-only, provenance preserved).
|
|
2. **Normalize** observations into tuples used for correlation and UI display.
|
|
3. **Correlate** tuples into deterministic linksets (grouping without merge or precedence).
|
|
4. **Compute consensus (optional)** using issuer trust and lattice rules to produce an “effective” status and conflict summary.
|
|
5. **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`
|