git.stella-ops.org/docs/vex/consensus-overview.md

VEX Consensus Overview — Evidence-Linked Decisions

Status: Updated 2025-12-11 · Owners: Policy Guild, Scanner Guild, Signals Guild

Stella Ops isn't just another scanner—it's a different product category: deterministic, evidence-linked vulnerability decisions that survive auditors, regulators, and supply-chain propagation.

Context: Four Capabilities

The VEX Consensus Engine supports Explainable Policy (Lattice VEX)—one of four capabilities no competitor offers together:

1. Signed Reachability – Every reachability graph is sealed with DSSE.
2. Deterministic Replay – Scans run bit-for-bit identical from frozen feeds.
3. Explainable Policy (Lattice VEX) – Evidence-linked VEX decisions with explicit "Unknown" state handling.
4. Sovereign + Offline Operation – FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors.

All decisions are sealed in Decision Capsules for audit-grade reproducibility.

---

Purpose

The VEX Consensus Engine merges multiple evidence sources into a single, reproducible vulnerability status for each component-vulnerability pair. Unlike simple VEX aggregation that picks the "most authoritative" statement, Stella Ops applies lattice logic to combine all inputs deterministically.

Key differentiators:

• Evidence-linked decisions: Every VEX assertion includes pointers to the underlying proof
• Explicit "Unknown" state: Incomplete data is surfaced as under_investigation, never as false safety
• Deterministic consensus: Given the same inputs, the engine produces identical outputs
• Human-readable justifications: Every decision comes with an explainable trace

---

Inputs

The consensus engine ingests evidence from multiple sources:

Source Type	Description	Evidence Link
SBOM data	Component identities (PURLs), dependency relationships, layer provenance	sbom_hash, layer_digest
Advisory feeds	OSV, GHSA, NVD, CNVD, CNNVD, ENISA, JVN, BDU, vendor feeds	advisory_snapshot_id, feed_hash
Reachability evidence	Static call-graph analysis, runtime traces, entry-point proximity	reach_decision_id, graph_hash
VEX statements	Vendor VEX, internal VEX, third-party VEX	vex_statement_id, issuer_id
Waivers/Mitigations	Temporary exceptions, compensating controls	waiver_id, mitigation_id
Policy rules	Lattice configuration, threshold settings	policy_version, policy_hash

Each input is content-addressed and timestamped, enabling full traceability.

---

Lattice Logic

The consensus engine applies a partial order over vulnerability states:

UNKNOWN (under_investigation)
    < NOT_AFFECTED
    < AFFECTED
    < FIXED

Cross-product with confidence levels:

• High confidence: Strong evidence from multiple sources
• Medium confidence: Partial evidence or single authoritative source
• Low confidence: Weak evidence, pending investigation

Merge semantics:

• Monotonic joins: states can only progress "up" the lattice
• Conflict resolution: prioritized by source trust level and evidence strength
• "Unknown" preserved: if any critical input is missing, the decision stays under_investigation

See docs/reachability/lattice.md for the full scoring model.

---

Outputs

Decision Artifact

Each consensus decision produces:

{
  "vulnerability": "CVE-2025-1234",
  "component": "pkg:nuget/Example@1.2.3",
  "status": "not_affected|under_investigation|affected|fixed",
  "confidence": "high|medium|low",
  "justification": "component_not_present|vulnerable_code_not_present|inline_mitigations_already_exist|...",
  "evidence_refs": {
    "sbom": "sha256:...",
    "advisory_snapshot": "nvd-2025-12-01",
    "reachability": "reach:abc123",
    "vex_statements": ["vex:vendor-redhat-001", "vex:internal-002"],
    "mitigations": ["mit:waf-rule-xyz"]
  },
  "policy_version": "corp-policy@2025-12-01",
  "policy_hash": "sha256:...",
  "timestamp": "2025-12-11T00:00:00Z",
  "status_notes": "Reachability score 22 (Possible) with WAF rule mitigation.",
  "action_statement": "Monitor config ABC",
  "impact_statement": "Runtime probes observed 0 hits; static call graph absent."
}

Evidence Graph

Every decision artifact links to an evidence graph containing:

• SBOM component hash / PURL match
• Vulnerability record snapshot ID
• Reachability proof artifact (if applicable)
• Runtime observation proof (if available)
• Mitigation evidence

This enables proof-linked VEX—auditors can trace any decision back to its inputs.

---

Decision Capsules Integration

Consensus decisions are sealed into Decision Capsules along with:

• Exact SBOM used
• Exact vuln feed snapshots
• Reachability evidence (static + runtime)
• Policy version + lattice rules
• Derived VEX statements
• DSSE signatures over all of the above

Capsules enable:

• Bit-for-bit replay: stella replay capsule.yaml
• Offline verification: No network required
• Audit-grade evidence: Every decision is provable

---

Threshold and Confidence Handling

Confidence Level	Criteria	Default Action
High	Multiple corroborating sources, strong reachability evidence	Auto-apply decision
Medium	Single authoritative source or partial reachability evidence	Apply with advisory flag
Low	Weak evidence, conflicting sources	Mark under_investigation

Policy rules can override these defaults per environment.

---

VEX Propagation

Once consensus is reached, Stella Ops can generate downstream VEX statements for consumers:

• OpenVEX format: Standard VEX for interoperability
• CSAF VEX: For CSAF-compliant ecosystems
• Custom formats: Via export templates

Downstream consumers can automatically trust and ingest these VEX statements because they include:

• Proof pointers to the evidence graph
• Signatures from trusted issuers
• Replay bundle references

Key differentiator: Competitors export VEX formats; Stella provides a unified proof model that can be verified independently.

---

API Integration

# Evaluate consensus for a component-vuln pair
POST /v1/vex/consensus/evaluate
{
  "component": "pkg:nuget/Example@1.2.3",
  "vulnerabilities": ["CVE-2025-1234"],
  "policy": "corp-policy@2025-12-01"
}

# Get consensus decision with evidence
GET /v1/vex/consensus/{decision_id}?include_evidence=true

# Export VEX for downstream propagation
POST /v1/vex/export
{
  "format": "openvex|csaf",
  "decisions": ["decision:abc123"]
}

---

Open TODOs

• PLVL0102 schema integration (pending schema finalization)
• Issuer directory details for third-party VEX sources
• CSAF VEX export template
• CLI commands for consensus querying

---

Related Documentation

• docs/reachability/lattice.md — Reachability scoring model
• docs/vex/consensus-algorithm.md — Algorithm details
• docs/vex/consensus-api.md — API reference
• docs/vex/aggregation.md — VEX aggregation rules
• docs/vex/issuer-directory.md — Trusted VEX issuers