git.stella-ops.org/docs/modules/vex-lens

StellaOps VEX Consensus Lens

VEX Lens produces a deterministic, provenance-rich consensus view of VEX statements so downstream policy and exploration surfaces can trust what “affected” or “not affected” means per artifact. It separates raw ingestion (Excititor) from adjudication, weighs issuers cryptographically, and keeps conflicts transparent for auditors and tooling.

Scope & responsibilities

• Normalise OpenVEX, CSAF VEX, and CycloneDX VEX documents from Excititor into lens-ready tuples without violating the Aggregation-Only Contract.
• Apply issuer weights, signature verification results, freshness decay, and policy overrides to compute consensus and confidence for each (artifact, advisory) pair.
• Emit consensus snapshots, conflict summaries, and DSSE attestations consumed by Policy Engine, Vulnerability Explorer, Advisory AI, and Task Runner workflows.
• Provide simulation/export APIs and Offline Kit bundles so tenants can rehearse policy changes and mirror consensus data in air-gapped environments.

Architecture snapshot (Sprint 30 groundwork)

• StellaOps.VexLens service & workers — orchestrate normalisation, trust weighting, lattice join, and persistence into vex_consensus, vex_consensus_history, and vex_conflict_queue collections.
• Issuer Directory integration — maintains publisher metadata, keys, and trust tiers that feed weighting engines and revocation workflows.
• Consensus APIs — /v1/vex/consensus, /v1/vex/conflicts, /v1/vex/trust/weights, and export streams with DSSE manifests for Offline Kit + Export Center.
• Explainability traces — capture derived-from chains, conflicting issuers, and trust deltas to power UI drilldowns and CLI audits.
• Recompute orchestration — Orchestrator jobs trigger recompute on Excititor deltas, issuer updates, or policy knob changes with deterministic ordering and SRM manifests.

Provenance-aware trust weighting (new)

• Connector metadata contract. Excititor connectors now emit vex.provenance.* fields (provider id/name/kind, trust.weight, trust.tier, human-readable trust.note, cosign.*, and ordered pgp.fingerprints). VEX Lens must ingest these keys verbatim so the trust engine can reason about issuer pedigree without hitting external registries for every statement.
• Weight calculation. Lens uses the supplied trust.weight as the baseline score, then multiplies by freshness decay and justification scope multipliers. Missing weights default to the Issuer Directory profile, but connector-provided values take precedence so Ubuntu/SUSE mirror feeds can tune their relative influence.
• Integrity hints. Presence of vex.provenance.cosign.* or pgp.fingerprints toggles signature-policy shortcuts: if Lens sees a statement whose provenance indicates cosign keyless mode plus Rekor URI, it can skip redundant issuer lookups and apply the “cryptographically verified” confidence tier immediately.
• Policy exposure. Consensus APIs surface the original provenance payload inside each sources[] entry so Policy Engine, Advisory AI, and Console can explain why a lower-tier issuer lost a conflict (e.g., different trust.tier or missing fingerprints). See the updated payload reference in docs/vex/consensus-json.md.

Current workstreams (Q4 2025)

• VEXLENS-30-001..004 — build normalisation pipeline, product mapping library, and trust weighting engine (in progress; dependencies captured in src/VexLens/StellaOps.VexLens/TASKS.md).
• VEXLENS-30-005..007 — expose consensus APIs and export flows, aligning docs with future /docs/vex/consensus-*.md deliverables.
• DOCS-VEX-30-001..004 — broader documentation set (overview, algorithm, API) tracked in docs/TASKS.md; update this README again once those artefacts merge.

Latest updates (2025-11-30)

• Docs refresh per docs/implplan/SPRINT_0332_0001_0001_docs_modules_vex_lens.md; added observability runbook stub and TASKS mirror.
• Observability assets: runbooks/observability.md and runbooks/dashboards/vex-lens-observability.json (offline import).

Integrations & dependencies

• Excititor supplies signature-verified VEX observations and issuer hints.
• Policy Engine consumes consensus verdicts for suppression/waiver logic and exposes trust controls to operators.
• Vulnerability Explorer & Advisory AI render consensus badges, conflicts, and rationale in investigative workflows.
• Orchestrator & Scheduler run backfills, recomputes, and incident routing driven by Lens change streams.
• Notify / Task Runner receive conflict and override events for operator actions once notification bridges ship.

Data & observability

• Collections: vex_consensus, vex_consensus_history, vex_conflict_queue, plus issuer registry tables managed with tenant isolation and deterministic indexes.
• Metrics: vex_consensus_conflicts_total, vex_consensus_latency_seconds, vex_consensus_recompute_seconds{reason}, signature failure counters.
• Traces/logs: consensus.group, consensus.join, consensus.persist spans with correlation IDs and issuer details; structured logs capture trust adjustments and reconciliation outcomes.
• Offline bundles include consensus.jsonl, conflicts.jsonl, manifest + DSSE signatures, enabling mirror deployments and replay validation.

Key docs & references

• architecture.md — implementation-ready blueprint covering inputs, algorithm, APIs, storage, observability, and exports.
• implementation_plan.md — phased delivery roadmap and acceptance criteria.
• ../../vex/aggregation.md — Aggregation-Only Contract boundaries for VEX ingestion and downstream consumers.
• Sprint tracking in docs/implplan/SPRINT_0332_0001_0001_docs_modules_vex_lens.md; module engineering tasks in src/VexLens/StellaOps.VexLens/TASKS.md; doc TASKS mirror in docs/modules/vex-lens/TASKS.md.

Epic alignment

• Epic 7 — VEX Consensus Lens: deterministic VEX adjudication, issuer directory, consensus exports.
• Related epics: Issuer Directory (keys & trust), Vulnerability Explorer overlays, Policy trust tuning.