7503c19b8f
- Implemented comprehensive tests for verdict artifact generation to ensure deterministic outputs across various scenarios, including identical inputs, parallel execution, and change ordering. - Created helper methods for generating sample verdict inputs and computing canonical hashes. - Added tests to validate the stability of canonical hashes, proof spine ordering, and summary statistics. - Introduced a new PowerShell script to update SHA256 sums for files, ensuring accurate hash generation and file integrity checks.
44 lines
1.7 KiB
Markdown
44 lines
1.7 KiB
Markdown
# VEX Observations and Linksets
|
|
|
|
This document describes how StellaOps stores and correlates VEX without rewriting upstream sources.
|
|
|
|
## Observations (Append-Only Evidence)
|
|
|
|
An observation is the immutable record of a VEX document *as received*.
|
|
|
|
Recorded fields typically include:
|
|
|
|
- **Provenance:** tenant, provider/issuer identity, retrieved/received timestamps (UTC), signature verification status, trust metadata, and content digest.
|
|
- **Raw payload:** stored losslessly to support audit and offline verification.
|
|
- **Derived indexes:** extracted identifiers and tuples used to correlate evidence (without replacing the raw payload).
|
|
|
|
If upstream republishes a VEX document, the new version is stored as a new observation with a `supersedes` relationship.
|
|
|
|
## Normalization (Projection Only)
|
|
|
|
Normalization produces tuples used by downstream layers:
|
|
|
|
- `(vulnerabilityId, productKey)` keys for correlation
|
|
- VEX status and justification
|
|
- Optional scope and validity windows
|
|
|
|
Normalization is a projection; it does not delete, mutate, or merge upstream evidence.
|
|
|
|
## Linksets (Correlation Without Precedence)
|
|
|
|
Linksets group tuples that refer to the same conceptual product-vulnerability pair.
|
|
|
|
Properties:
|
|
|
|
- **Deterministic:** linkset identifiers are derived from canonical, sorted key material.
|
|
- **Conflict-preserving:** disagreements remain visible (status, scope, justification, issuer identity).
|
|
- **Provenance-linked:** every item in a linkset references its source observation digest and issuer metadata.
|
|
|
|
Downstream consumers (Policy/Console/Exports) use linksets to explain what disagrees and why.
|
|
|
|
## References
|
|
|
|
- `docs/16_VEX_CONSENSUS_GUIDE.md`
|
|
- `docs/modules/excititor/architecture.md`
|
|
- `docs/modules/vex-lens/architecture.md`
|