git.stella-ops.org/docs/modules/vex-lens/guides/aggregation.md

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/VEX_CONSENSUS_GUIDE.md
• docs/modules/excititor/architecture.md
• docs/modules/vex-lens/architecture.md