491e883653
- 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.
96 lines
4.9 KiB
Markdown
96 lines
4.9 KiB
Markdown
# 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`
|