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.

<!-- TODO: Review for separate approval - completed VEX consensus overview -->

## 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:

```json
{
  "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

```bash
# 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