VEX Consensus Lens architecture

Based on Epic 7 – VEX Consensus Lens; consolidates trust modelling, consensus computation, and API contracts.

1) Purpose

Compute a deterministic, reproducible consensus view over multiple VEX statements for each (artifact, advisory) tuple while preserving conflicts and provenance. Output is consumed by Policy Engine, Vulnerability Explorer, Advisory AI, and Console overlays.

2) Inputs

vex_normalized tuples emitted by Excititor (status, justification, scope, timestamp, content hash).
Issuer trust registry (vex_issuer_registry) providing trust tier, confidence, authority scope.
Optional runtime context (Zastava exposure) and policy precedence rules.

3) Core algorithm

Group tuples by (artifactId, advisoryKey).
Sort statements by timestamp then trust tier (critical → low) then confidence.
Apply lattice join:
- States: unknown < under_investigation < not_affected | affected < fixed.
- Conflicts triggered when competing issuers disagree at the same precedence level.

Generate consensus record with fields:

{
  "artifact": "pkg:rpm/redhat/openssl@3.0.9",
  "advisory": "CVE-2025-13579",
  "status": "not_affected",
  "confidence": 0.92,
  "derived_from": ["vex_raw:openvex:VEX-2025-00001:v2", "vex_raw:csaf:RHSA-2025:1234:v1"],
  "conflicts": [{"issuer":"vendor:upstream","status":"affected"}],
  "issued_at": "2025-08-30T12:05:00Z",
  "consensus_digest": "sha256:..."
}

Persist consensus and emit vex.consensus.updated DSSE event.

Conflicts remain visible through conflicts array; Policy Engine can decide suppression strategy based on trust weights.

4) APIs

GET /v1/vex/consensus?artifact=...&advisory=... — returns consensus record and conflict list.
GET /v1/vex/conflicts — list outstanding conflicts with severity, trust delta, and time since disagreement.
POST /v1/vex/trust/weights — (admin) update trust tiers/confidence (requires Authority scopes); updates propagate to recomputation jobs.
GET /v1/vex/consensus/export — stream deterministic JSONL for Offline Kit / Export Center mirror bundles.

All responses include provenance fields (consensus_digest, derived_from, DSSE signature references) for audit.

5) Storage

vex_consensus collection keyed by (tenant, artifactId, advisoryKey) with current consensus, metadata, conflict summary, and digests.
vex_consensus_history append-only history to support replay and audit.
vex_conflict_queue for unresolved conflicts requiring manual review.

6) Recompute strategy

Incremental updates triggered by Excititor deltas, trust registry changes, or policy precedence updates.
Recompute jobs run via Orchestrator; deterministic ordering ensures identical results for the same input set.
Jobs produce SRM-style manifests for recomputation verification.

7) Observability

Metrics: vex_consensus_conflicts_total, vex_consensus_latency_seconds, vex_consensus_recompute_seconds{reason}.
Logs: include artifactId, advisoryKey, issuer, status, trustTier.
Traces: consensus.group, consensus.join, consensus.persist spans.

8) Offline & export

Bundle format: consensus.jsonl, conflicts.jsonl, manifest.json, signatures/. Each record references raw statement digests and trust metadata.
Export Center uses the bundle for mirror profiles; CLI supports stella vex consensus export mirroring the API.

3.5 KiB Raw Permalink Blame History Unescape Escape