stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
43e2af88f621a3a015293b86e03e302ba92ab752
git.stella-ops.org/docs/vex/aggregation.md
StellaOps Bot 7503c19b8f Add determinism tests for verdict artifact generation and update SHA256 sums script 
- 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.
2025-12-24 02:17:34 +02:00

1.7 KiB
Raw Blame History

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