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.
This commit is contained in:
StellaOps Bot
@@ -1,6 +1,43 @@
|
||||
# Archived: VEX Observations & Linksets
|
||||
|
||||
This document was consolidated during docs cleanup.
|
||||
|
||||
- Canonical guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- Module dossiers: `docs/modules/excititor/architecture.md`, `docs/modules/vex-lens/architecture.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/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- `docs/modules/excititor/architecture.md`
|
||||
- `docs/modules/vex-lens/architecture.md`
|
||||
|
||||
@@ -1,6 +1,37 @@
|
||||
# Archived: VEX Consensus Algorithm
|
||||
# VEX Consensus Algorithm (Deterministic)
|
||||
|
||||
This document was consolidated during docs cleanup.
|
||||
This document describes the consensus computation at a high level. It is not an API contract; see `docs/vex/consensus-json.md` and `docs/vex/consensus-api.md` for payload and endpoint details.
|
||||
|
||||
- Canonical guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- Module dossier: `docs/modules/vex-lens/architecture.md`
|
||||
## Inputs
|
||||
|
||||
- Normalized VEX tuples (status, justification, scope, timestamp, source digest)
|
||||
- Issuer trust registry (tiers, weights, verification state)
|
||||
- Optional policy precedence rules for how to treat conflicts
|
||||
|
||||
## Grouping and Ordering
|
||||
|
||||
1. Group tuples by correlation key (typically `(artifactId/productKey, vulnerabilityId)` per tenant).
|
||||
2. Apply a stable sort for evaluation, commonly:
|
||||
- Most recent statement first (timestamp)
|
||||
- Higher trust tier/weight first
|
||||
- Higher verification confidence first
|
||||
|
||||
Ordering must be deterministic for identical inputs.
|
||||
|
||||
## Lattice Join
|
||||
|
||||
Consensus uses a lattice-style join to avoid false safety:
|
||||
|
||||
- Model states with an explicit uncertainty ordering (e.g., `unknown` and `under_investigation` remain meaningful outcomes).
|
||||
- Preserve conflicts when competing issuers disagree at comparable precedence.
|
||||
|
||||
The output includes:
|
||||
|
||||
- Effective status
|
||||
- Confidence/weight summary
|
||||
- References to source statements (digests)
|
||||
- Conflict list (who disagrees and how)
|
||||
|
||||
## References
|
||||
|
||||
- `docs/modules/vex-lens/architecture.md`
|
||||
|
||||
@@ -1,6 +1,23 @@
|
||||
# Archived: VEX Consensus API
|
||||
# VEX Consensus API (Contract Overview)
|
||||
|
||||
This document was consolidated during docs cleanup.
|
||||
This document provides a high-level overview of consensus endpoints. The gateway and module dossiers define the authoritative routing, auth, and schema details.
|
||||
|
||||
- Canonical guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- Module dossier: `docs/modules/vex-lens/architecture.md`
|
||||
## Common Headers
|
||||
|
||||
- `Authorization: Bearer <token>` (or DPoP where configured)
|
||||
- `X-StellaOps-Tenant: <tenantId>` (required)
|
||||
|
||||
## Typical Endpoints
|
||||
|
||||
- `GET /v1/vex/consensus?artifact=...&advisory=...` — returns a single consensus record (plus conflicts).
|
||||
- `GET /v1/vex/conflicts` — list outstanding conflicts with summary metadata.
|
||||
- `GET /v1/vex/consensus/export` — deterministic JSONL export for Offline Kit / Export Center bundles.
|
||||
- `POST /v1/vex/trust/weights` — tenant-admin update of trust tiers/weights (when enabled).
|
||||
|
||||
## Output Shape
|
||||
|
||||
See `docs/vex/consensus-json.md` for the record payload reference.
|
||||
|
||||
## References
|
||||
|
||||
- `docs/modules/vex-lens/architecture.md`
|
||||
|
||||
@@ -1,6 +1,23 @@
|
||||
# Archived: VEX Consensus Console Integration
|
||||
# VEX Consensus in the Console
|
||||
|
||||
This document was consolidated during docs cleanup.
|
||||
This document describes how the Console should surface VEX evidence and consensus to keep triage explainable.
|
||||
|
||||
- Canonical guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- Console guide: `docs/15_UI_GUIDE.md`
|
||||
## What the Console Should Show
|
||||
|
||||
- Effective VEX status (`affected`, `not_affected`, `under_investigation`, `fixed`) with confidence/tier label.
|
||||
- Provenance for each source statement: issuer identity, signature verification state, timestamps, and digests.
|
||||
- Conflicts as first-class facts (what disagrees, at what trust tier), not hidden UI logic.
|
||||
- Snapshot identity and staleness budgets when operating against Offline Kit snapshots.
|
||||
|
||||
## Evidence Linking
|
||||
|
||||
Every displayed fact should link back to:
|
||||
|
||||
- The raw VEX observation(s)
|
||||
- Linkset correlation view (what was grouped and why)
|
||||
- The policy explanation that consumed the evidence (when shown in triage)
|
||||
|
||||
## References
|
||||
|
||||
- Operator guide: `docs/15_UI_GUIDE.md`
|
||||
- VEX conceptual guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
|
||||
@@ -1,6 +1,47 @@
|
||||
# Archived: VEX Consensus JSON
|
||||
# VEX Consensus JSON (Payload Reference)
|
||||
|
||||
This document was consolidated during docs cleanup.
|
||||
This document describes the *shape* of consensus records returned by consensus APIs and exported in Offline Kit snapshots. Field names and structure may vary slightly by gateway serialization, but the semantic contract is stable.
|
||||
|
||||
- Canonical guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- Module dossier: `docs/modules/vex-lens/architecture.md`
|
||||
## Consensus Record (Conceptual)
|
||||
|
||||
```json
|
||||
{
|
||||
"artifact": "pkg:rpm/redhat/openssl@3.0.9",
|
||||
"advisory": "CVE-2025-13579",
|
||||
"status": "not_affected",
|
||||
"confidence": 0.92,
|
||||
"issued_at": "2025-08-30T12:05:00Z",
|
||||
"consensus_digest": "sha256:…",
|
||||
"derived_from": [
|
||||
{
|
||||
"source_digest": "sha256:…",
|
||||
"issuer": "vendor:redhat",
|
||||
"status": "not_affected",
|
||||
"timestamp": "2025-08-30T12:00:00Z",
|
||||
"trust": { "tier": "vendor", "weight": 1.0 },
|
||||
"verification": { "signature": "verified" }
|
||||
}
|
||||
],
|
||||
"conflicts": [
|
||||
{
|
||||
"source_digest": "sha256:…",
|
||||
"issuer": "vendor:upstream",
|
||||
"status": "affected",
|
||||
"timestamp": "2025-08-29T00:00:00Z",
|
||||
"trust": { "tier": "vendor", "weight": 0.8 }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Determinism Rules
|
||||
|
||||
- Timestamps are UTC ISO-8601.
|
||||
- Arrays (`derived_from`, `conflicts`) are in a stable order (typically the evaluation sort order).
|
||||
- `consensus_digest` is computed over canonical, deterministic JSON bytes for the record (or over an equivalent canonical projection).
|
||||
|
||||
## Related Docs
|
||||
|
||||
- Algorithm overview: `docs/vex/consensus-algorithm.md`
|
||||
- Endpoints: `docs/vex/consensus-api.md`
|
||||
- Module details: `docs/modules/vex-lens/architecture.md`
|
||||
|
||||
@@ -1,6 +1,31 @@
|
||||
# Archived: VEX Consensus Overview
|
||||
# VEX Evidence and Consensus (Detailed)
|
||||
|
||||
This document was consolidated during docs cleanup.
|
||||
This document complements `docs/16_VEX_CONSENSUS_GUIDE.md` with implementation-oriented detail: what objects exist, how evidence is correlated without rewriting sources, and what “consensus” means in practice.
|
||||
|
||||
- Canonical guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- Module dossiers: `docs/modules/excititor/architecture.md`, `docs/modules/vex-lens/architecture.md`
|
||||
## Pipeline (Evidence First)
|
||||
|
||||
1. **Ingest raw VEX** as immutable observations (append-only, provenance preserved).
|
||||
2. **Normalize** observations into tuples used for correlation and UI display.
|
||||
3. **Correlate** tuples into deterministic linksets (grouping without merge or precedence).
|
||||
4. **Compute consensus (optional)** using issuer trust and lattice rules to produce an “effective” status and conflict summary.
|
||||
5. **Expose evidence** to Policy Engine, Console, and Vulnerability Explorer; include in Offline Kit snapshots.
|
||||
|
||||
## Core Objects
|
||||
|
||||
- **Raw observation:** upstream OpenVEX/CSAF/CycloneDX payload stored losslessly with provenance (issuer/provider, receive time, signature verification, content digest).
|
||||
- **Normalized tuple:** extracted fields used for correlation and decisioning, typically `(vulnerabilityId, productKey, status, justification?, scope?, timestamp, sourceDigest)`.
|
||||
- **Linkset:** a correlation group tying multiple tuples to the same conceptual `(vulnerabilityId, productKey)` without collapsing disagreements.
|
||||
- **Consensus record:** a deterministic summary for a linkset: effective status, confidence/weight, and conflict list (still referencing raw evidence).
|
||||
|
||||
## Determinism Guarantees
|
||||
|
||||
- Canonical UTF-8 JSON bytes are hashed to compute stable digests for raw observations.
|
||||
- Linkset IDs are derived from canonical, sorted key material.
|
||||
- Consensus outputs are stable for identical inputs: ordering, timestamps, and digests are deterministic.
|
||||
|
||||
## Where This Lives
|
||||
|
||||
- Ingestion, raw store, and linksets: `docs/modules/excititor/architecture.md`
|
||||
- Consensus and issuer trust: `docs/modules/vex-lens/architecture.md`
|
||||
- Console/operator view: `docs/15_UI_GUIDE.md`
|
||||
- Triage model: `docs/20_VULNERABILITY_EXPLORER_GUIDE.md`
|
||||
|
||||
@@ -1,6 +1,25 @@
|
||||
# Archived: Vulnerability Explorer Integration
|
||||
# VEX Integration with Vulnerability Explorer
|
||||
|
||||
This document was consolidated during docs cleanup.
|
||||
The Vulnerability Explorer and triage surfaces treat VEX as first-class evidence: operator decisions should be explainable, replayable, and linked to provenance.
|
||||
|
||||
- Canonical guide: `docs/20_VULNERABILITY_EXPLORER_GUIDE.md`
|
||||
- VEX guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
## Triage View Expectations
|
||||
|
||||
- Show effective VEX status alongside policy outcome and reachability/impact signals.
|
||||
- Make conflicts visible and navigable (issuer list, trust tiers, verification state).
|
||||
- Provide deep links from the triage view into VEX evidence (raw observations/linksets) and to policy explain traces.
|
||||
|
||||
## Filtering and Lanes
|
||||
|
||||
VEX evidence commonly affects:
|
||||
|
||||
- Default lane placement (e.g., `MUTED_VEX` vs `ACTIVE`)
|
||||
- Whether a finding is actionable, needs exception, or can be shipped
|
||||
- Staleness warnings for offline snapshots
|
||||
|
||||
The Explorer must remain “quiet by default, never silent”: VEX-based suppression should be reversible and auditable, not a destructive delete.
|
||||
|
||||
## References
|
||||
|
||||
- `docs/20_VULNERABILITY_EXPLORER_GUIDE.md`
|
||||
- `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- `docs/modules/vuln-explorer/architecture.md`
|
||||
|
||||
@@ -1,6 +1,33 @@
|
||||
# Archived: VEX Issuer Directory
|
||||
# VEX Issuer Directory and Trust
|
||||
|
||||
This document was consolidated during docs cleanup.
|
||||
Issuer trust is a first-class input to VEX decisioning. The issuer directory defines *who* a statement is from, *how* it is verified, and *how* policy should weigh it.
|
||||
|
||||
- Canonical guide: `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- Related: `docs/modules/excititor/architecture.md`, `docs/modules/vex-lens/architecture.md`
|
||||
## Issuer Identity
|
||||
|
||||
An issuer can be identified by:
|
||||
|
||||
- Stable provider IDs (connector/provider identifiers)
|
||||
- Cryptographic identity (certificate chain, key identifiers, transparency inclusion proof) when available
|
||||
|
||||
Tenants may define allowlists for acceptable issuer identities and/or map issuers into trust tiers.
|
||||
|
||||
## Trust Tiers and Weights
|
||||
|
||||
Trust is commonly expressed as:
|
||||
|
||||
- **Tier label** (e.g., vendor, distro, internal, untrusted)
|
||||
- **Weight/confidence** used by consensus/policy to break ties and set posture
|
||||
- **Verification requirements** (e.g., signature required for `not_affected` gating)
|
||||
|
||||
## Offline Trust
|
||||
|
||||
Offline deployments must be able to verify issuer identity without network access:
|
||||
|
||||
- Trust roots and allowlists are bundled in the Offline Kit
|
||||
- Signature verification and transparency proofs are evaluated against bundled material
|
||||
|
||||
## References
|
||||
|
||||
- `docs/16_VEX_CONSENSUS_GUIDE.md`
|
||||
- `docs/modules/excititor/architecture.md`
|
||||
- `docs/modules/vex-lens/architecture.md`
|
||||
|
||||
Reference in New Issue
Block a user