stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
491e8836535ab3daa30eff7a77f76f5b00331a74
git.stella-ops.org/docs/16_VEX_CONSENSUS_GUIDE.md
master 491e883653 Add tests for SBOM generation determinism across multiple formats 
- Created `StellaOps.TestKit.Tests` project for unit tests related to determinism.
- Implemented `DeterminismManifestTests` to validate deterministic output for canonical bytes and strings, file read/write operations, and error handling for invalid schema versions.
- Added `SbomDeterminismTests` to ensure identical inputs produce consistent SBOMs across SPDX 3.0.1 and CycloneDX 1.6/1.7 formats, including parallel execution tests.
- Updated project references in `StellaOps.Integration.Determinism` to include the new determinism testing library.
2025-12-24 00:36:14 +02:00

4.9 KiB
Raw Blame History

VEX Consensus and Issuer Trust

This document consolidates the VEX concepts StellaOps relies on: ingesting upstream VEX without rewriting it, correlating evidence across sources, and producing a deterministic, explainable "effective" status for a component-vulnerability pair.

Scope

  • VEX ingestion and provenance (what is stored and why)
  • Correlation (linksets) versus consensus (effective status)
  • Issuer trust and offline operation

This is not an API reference; module dossiers define concrete schemas and endpoints.

Vocabulary (Minimal)

  • VEX statement: a claim about vulnerability status for a product/component (for example: affected, fixed, not_affected, under_investigation).
  • Observation: an immutable record of a single upstream VEX document as received (including provenance and raw payload).
  • Linkset: a deterministic correlation group that ties together statements that refer to the same (vulnerabilityId, productKey) across providers.
  • Consensus decision (effective VEX): the platform's deterministic result after policy rules evaluate available VEX/advisory/reachability evidence.

Observation Model (Link, Not Merge)

StellaOps treats upstream VEX as append-only evidence.

An observation records:

  • Provenance: tenant, provider/issuer identity, receive timestamps (UTC), signature status, and content hash.
  • Raw payload: stored losslessly so auditors and operators can retrieve exactly what was ingested.
  • Derived tuples: extracted (vulnerabilityId, productKey, status, justification?, version hints, references) used for correlation and UI presentation.

An observation is never mutated. If upstream publishes a revision, StellaOps stores a new observation and records a supersedes relationship.

Linksets (Correlation Without Consensus)

Linksets exist to make multi-source evidence explainable without collapsing it:

  • Group statements that likely refer to the same product-vulnerability pair.
  • Preserve conflicts (status disagreements, justification divergence, version range clashes) as first-class facts.
  • Provide stable IDs generated from canonical, sorted inputs (deterministic hashing).

Linksets do not invent consensus; they only align evidence so downstream layers (Policy/Console/Exports) can explain what is known and what disagrees.

Consensus (Effective Status)

The effective VEX status is computed by policy evaluation using:

  • Correlated VEX evidence (observations + linksets)
  • Advisory evidence (observations/linksets from Concelier)
  • Optional reachability and other signals

Key properties:

  • Deterministic: the same inputs yield the same output.
  • Explainable: the decision includes an explanation trace and evidence references.
  • Uncertainty-aware: when critical evidence is missing or conflicts are unresolved, the result can remain under_investigation instead of implying safety.

Aggregation-Only Guardrails (AOC)

To avoid hidden rewriting of upstream data, the platform enforces:

  • Raw-first storage: upstream payloads are stored as received; normalized projections are derived but do not replace raw data.
  • No merge of sources: each provider's statements remain independently addressable.
  • Provenance is mandatory: missing provenance or unverifiable signatures are surfaced as ingestion failures or warnings (policy-driven).
  • Idempotent writes: identical content hashes do not create duplicate observations.
  • Deterministic outputs: stable ordering and canonical hashing for linksets and exports.

Issuer Directory and Trust

Issuer trust is a first-class input:

  • Issuers are identified by stable provider IDs and, where applicable, cryptographic identity (certificate chain, key id, transparency proof).
  • The issuer directory defines which issuers are trusted per tenant/environment and how they are weighted/accepted by policy.
  • Offline sites carry required trust material (roots and allowlists) inside the Offline Kit so verification does not require network access.

Console Integration

The Console uses these concepts to keep VEX explainable:

  • VEX views show provider provenance, signature/issuer status, and snapshot timestamps.
  • Conflicts are displayed as conflicts (what disagrees and why), not silently resolved in the UI.
  • The effective VEX status shown in triage views links back to underlying observations/linksets and the policy explanation.

See docs/15_UI_GUIDE.md for the operator workflow perspective.

Offline / Air-Gap Operation

  • VEX observations/linksets are included in Offline Kit snapshots with content hashes and timestamps.
  • Verification workflows (signatures, issuer trust) must work offline using bundled trust roots and manifests.
  • The Console should surface snapshot identity and staleness budgets when operating offline.

Related Docs

  • docs/modules/excititor/architecture.md
  • docs/modules/vex-lens/architecture.md
  • docs/07_HIGH_LEVEL_ARCHITECTURE.md
  • docs/24_OFFLINE_KIT.md