Add Decision Capsules, hybrid reachability, and evidence-linked VEX docs
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Introduces new marketing bridge documents for Decision Capsules, Hybrid Reachability, and Evidence-Linked VEX. Updates product vision, README, key features, moat, reachability, and VEX consensus docs to reflect four differentiating capabilities: signed reachability (hybrid static/runtime), deterministic replay, explainable policy with evidence-linked VEX, and sovereign/offline operation. All scan decisions are now described as sealed, reproducible, and audit-grade, with explicit handling of 'Unknown' states and hybrid reachability evidence.
This commit is contained in:
Vladimir Moushkov
@@ -1,15 +1,203 @@
|
||||
# VEX Consensus Overview — Draft Skeleton (2025-12-05 UTC)
|
||||
# VEX Consensus Overview — Evidence-Linked Decisions
|
||||
|
||||
Status: draft placeholder. Inputs pending: PLVL0102 schema snapshot, issuer directory details.
|
||||
> 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
|
||||
- Explain why consensus exists and what assurances it provides (AOC scope).
|
||||
|
||||
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
|
||||
- Evidence sources (attestations, SBOM edges) — to be confirmed.
|
||||
|
||||
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 artifacts; confidence/threshold handling.
|
||||
|
||||
### 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
|
||||
- Fill concrete schema references and examples once PLVL0102 arrives.
|
||||
|
||||
- [ ] 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
|
||||
|
||||
Reference in New Issue
Block a user