master
7b5bdcf4d3
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# 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
|
||
|
||
1. Group tuples by `(artifactId, advisoryKey)`.
|
||
2. Sort statements by `timestamp` then trust tier (critical → low) then confidence.
|
||
3. Apply lattice join:
|
||
- States: `unknown < under_investigation < not_affected | affected < fixed`.
|
||
- Conflicts triggered when competing issuers disagree at the same precedence level.
|
||
4. Generate consensus record with fields:
|
||
```json
|
||
{
|
||
"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:..."
|
||
}
|
||
```
|
||
5. 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.
|