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,5 +1,7 @@
|
||||
# 3 · Product Vision — **Stella Ops**
|
||||
|
||||
> 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.
|
||||
|
||||
## 1) Problem Statement & Goals
|
||||
|
||||
We ship containers. We need:
|
||||
@@ -369,11 +371,24 @@ opa eval -i gate-input.json -d policy/ -f pretty "data.stella.policy.allow"
|
||||
---
|
||||
|
||||
## 9) Moats
|
||||
|
||||
<!-- TODO: Review for separate approval - updated moats section -->
|
||||
**Four capabilities no competitor offers together:**
|
||||
|
||||
1. **Signed Reachability** – Every reachability graph is sealed with DSSE; optional edge-bundle attestations for runtime/init/contested paths.
|
||||
2. **Deterministic Replay** – Scans run bit-for-bit identical from frozen feeds and analyzer manifests.
|
||||
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 as first-class toggles.
|
||||
|
||||
**Decision Capsules:** Every scan result is sealed in a Decision Capsule—a content-addressed bundle containing exact SBOM, vuln feed snapshots, reachability evidence, policy version, derived VEX, and signatures. Auditors can re-run any capsule bit-for-bit to verify the outcome.
|
||||
|
||||
**Additional moat details:**
|
||||
- **Deterministic replay:** Hash-stable scans with frozen feeds and analyzer manifests; replay packs verifiable offline.
|
||||
- **Hybrid reachability attestations:** Graph-level DSSE always; selective edge-bundle DSSE for runtime/init/contested edges with Rekor caps.
|
||||
- **Lattice VEX engine:** Trust algebra across advisories, runtime, reachability, waivers; explainable paths.
|
||||
- **Hybrid reachability attestations:** Graph-level DSSE always; selective edge-bundle DSSE for runtime/init/contested edges with Rekor caps. Both static call-graph edges and runtime-derived edges can be attested.
|
||||
- **Lattice VEX engine (Evidence-Linked):** Trust algebra across advisories, runtime, reachability, waivers; explainable paths with proof-linked decisions. Unlike yes/no approaches, explicit "Unknown" state handling ensures incomplete data never leads to false safety.
|
||||
- **Crypto sovereignty:** FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors as first-class configuration.
|
||||
- **Proof graph:** DSSE + Rekor spanning SBOM, call-graph, VEX, replay manifests for chain-of-custody evidence.
|
||||
- **Proof graph:** DSSE + Rekor spanning SBOM, call-graph, VEX, Decision Capsules, replay manifests for chain-of-custody evidence.
|
||||
- **VEX Propagation:** Generate vulnerability status attestations downstream consumers can automatically trust and ingest—scalable VEX sharing across the supply chain.
|
||||
|
||||
See also: `docs/market/competitive-landscape.md` for vendor comparison and talking points.
|
||||
|
||||
|
||||
@@ -1,52 +1,59 @@
|
||||
# Stella Ops
|
||||
# Stella Ops
|
||||
|
||||
> Stella Ops is the sovereign, SBOM‑first security platform that proves every container decision with deterministic scans, explainable policy verdicts, and offline‑ready provenance.
|
||||
> 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.
|
||||
|
||||
- **Sovereign by design** – bring your own trust roots, vulnerability advisory sources, VEX sources, regional crypto, and Offline Update Kits that never phone home.
|
||||
- **Deterministic + replayable** – every scan can be reproduced bit‑for‑bit with DSSE + OpenVEX evidence.
|
||||
- **Actionable signal** – lattice logic ranks exploitability, and the policy engine lets you tailor VEX handling, muting, and expiration rules for your environment.
|
||||
<!-- TODO: Review for separate approval - updated value proposition -->
|
||||
Stella Ops delivers **four capabilities no competitor offers together**:
|
||||
|
||||
**Proof points:** SBOM dependency and vulnerability dependency cartographing work, deterministic replay manifests, lattice policy UI with OpenVEX, and post‑quantum trust packs ready for regulated sectors.
|
||||
1. **Signed Reachability** – Every reachability graph is sealed with DSSE; optional edge-bundle attestations for runtime/init/contested paths. Both static call-graph edges and runtime-derived edges can be attested—true hybrid reachability.
|
||||
2. **Deterministic Replay** – Scans run bit-for-bit identical from frozen feeds and analyzer manifests. Auditors and incident responders can re-run historical findings and trust the results weren't tampered with.
|
||||
3. **Explainable Policy (Lattice VEX)** – The lattice engine merges SBOM data, advisories, VEX statements, and waivers into a single verdict with human-readable justifications. Explicit "Unknown" state handling ensures incomplete data never leads to false safety.
|
||||
4. **Sovereign + Offline Operation** – FIPS, eIDAS, GOST, SM, or PQC profiles are first-class toggles. Offline Kits and regional crypto profiles keep every decision inside your perimeter—air-gapped verification works by default.
|
||||
|
||||
**Proof points:** Decision Capsules (sealed evidence bundles), SBOM cartographing, deterministic replay manifests, lattice policy UI with OpenVEX, evidence-linked VEX decisions, and post‑quantum trust packs ready for regulated sectors.
|
||||
|
||||
## Choose Your Path
|
||||
|
||||
| If you want to… | Open this | Read time |
|
||||
|-----------------|-----------|-----------|
|
||||
| Understand the promise and pain we solve | `overview.md` | ≈ 2 min |
|
||||
| Run a first scan and see the CLI | `quickstart.md` | ≈ 5 min |
|
||||
| Browse key capabilities at a glance | `key-features.md` | ≈ 3 min |
|
||||
| Check architecture, road to production, or evaluate fit | See “Dig deeper” below | ≤ 30 min curated set |
|
||||
| Understand the promise and pain we solve | `overview.md` | ≈ 2 min |
|
||||
| Run a first scan and see the CLI | `quickstart.md` | ≈ 5 min |
|
||||
| Browse key capabilities at a glance | `key-features.md` | ≈ 3 min |
|
||||
| Check architecture, road to production, or evaluate fit | See "Dig deeper" below | ≤ 30 min curated set |
|
||||
|
||||
## Explore the Essentials
|
||||
|
||||
1. **Value in context** – [Overview](overview.md) compresses the “Why” + “What” stories and shows how Stella Ops stands apart.
|
||||
1. **Value in context** – [Overview](overview.md) compresses the "Why" + "What" stories and shows how Stella Ops stands apart.
|
||||
2. **Try it fast** – [Quickstart](quickstart.md) walks through fetching the signed bundles, configuring `.env`, and verifying the first scan.
|
||||
3. **Feature confidence** – [Key Features](key-features.md) gives five capability cards covering Delta SBOM, VEX-first policy, Sovereign crypto, Deterministic replay, and Transparent quotas.
|
||||
3. **Feature confidence** – [Key Features](key-features.md) gives nine capability cards covering Decision Capsules, Delta SBOM, VEX-first policy, Sovereign crypto, Deterministic replay, and more.
|
||||
4. **Up-next checkpoints** – [Evaluation checklist](evaluate/checklist.md) helps teams plan Day-0 to Day-30 adoption milestones.
|
||||
5. **Be dev-ready** – [Developer Quickstart](onboarding/dev-quickstart.md) (29-Nov-2025 advisory) walks through the core repos, determinism tests, attestations, and starter issues for a mid-level .NET engineer.
|
||||
|
||||
## Key capabilities that define Stella Ops
|
||||
## Key capabilities that define Stella Ops
|
||||
|
||||
<!-- TODO: Review for separate approval - updated capabilities table -->
|
||||
| Capability | What ships | Why it matters |
|
||||
|------------|------------|----------------|
|
||||
| **Decision Capsules** | Every scan result is sealed in a content-addressed bundle containing SBOM, vuln feed snapshots, reachability evidence, policy version, derived VEX, and signatures. | Auditors can re-run any capsule bit-for-bit to verify the outcome—audit-grade evidence bundles. |
|
||||
| **Deterministic Δ‑SBOM & replay bundles** | Layer-aware cache + replay manifests keep scans reproducible even months later. | Auditors can re-run any verdict with identical inputs, proving integrity without SaaS dependencies. |
|
||||
| **Pristine advisory mirrors** | OSV, GHSA, NVD, CNVD, CNNVD, ENISA, JVN, BDU, etc. are mirrored as immutable, per-source snapshots—never merged. | Policy (via `scanner.*` / `SCANNER__*`) can trust, down-rank, or ignore sources without rewriting upstream data. |
|
||||
| **Lattice VEX engine** | OpenVEX, waivers, mitigations, and configs flow through deterministic lattice logic. | Every block/allow decision is explainable, replayable, and environment-specific. |
|
||||
| **Context fabric** | Static reachability now, optional runtime/eBPF probes at GA so build + runtime signals share one verdict. | Prioritisation spans first-party code, base images, and live telemetry. |
|
||||
| **Lattice VEX engine (Evidence-Linked)** | OpenVEX, waivers, mitigations, and configs flow through deterministic lattice logic with proof-linked decisions. | Every block/allow decision is explainable, replayable, evidence-linked, and environment-specific. Explicit "Unknown" state handling ensures incomplete data never leads to false safety. |
|
||||
| **Hybrid Reachability** | Static call-graph analysis + optional runtime/eBPF probes; both edge types can be attested with DSSE. | Build + runtime signals share one verdict; prioritisation spans first-party code, base images, and live telemetry. |
|
||||
| **Transparency log + trust credits** | Cosign/DSSE bundles push to a Rekor-compatible log; the trust-credit ledger records who accepted a risk. | Compliance teams get provenance plus accountable ownership trails. |
|
||||
| **Sovereign crypto profiles** | Swap in FIPS, eIDAS, GOST, SM, or PQ-ready providers without code changes. | Meets regional crypto rules while keeping attestations verifiable. |
|
||||
| **Offline-first operations** | Offline Kit packages the pristine feeds, plug-ins, and configs; import CLI verifies everything locally. | Air-gapped clouds get the same security posture as connected sites. |
|
||||
| **VEX Propagation** | Generate vulnerability status attestations your downstream consumers can automatically trust and ingest. | Scalable VEX sharing across the supply chain—competitors export VEX formats; Stella provides a unified proof model that can be verified independently. |
|
||||
| **Enterprise readiness** | Transparent quotas, LDAP/AD SSO, restart-time plug-in SDK, generous free tier. | Large teams keep their workflows without surrendering control to SaaS platforms. |
|
||||
|
||||
## Where Stella Ops differs from incumbents
|
||||
## Where Stella Ops differs from incumbents
|
||||
|
||||
| Vendor | Where they stop | Stella Ops difference |
|
||||
| Vendor | Where they stop | Stella Ops difference |
|
||||
|--------|-----------------|-----------------------|
|
||||
| **Trivy / Syft** | SBOM generation as a CLI add-on; policy left to other products. | SBOM + VEX are the system of record with deterministic replay and signed evidence. |
|
||||
| **Snyk Container** | Static reachability bounded to first-party code. | Lattice links code, base images, cluster policies, and optional runtime probes so the entire stack shares one score. |
|
||||
| **JFrog Xray** | Contextual scoring lives behind a closed service. | Policies, DSSE bundles, and transparency logs are open, auditable, and portable. |
|
||||
| **Docker Scout** | Provenance remains inside Docker’s ecosystem. | Any OCI provenance is ingested, signed with your crypto profile, and replayed offline. |
|
||||
| **Wiz / runtime sensors** | Runtime telemetry is separate from build-time SBOM/VEX evidence. | Optional runtime probes feed the same deterministic lattice so build- and run-time context stay consistent. |
|
||||
| **Trivy / Syft** | SBOM generation as a CLI add-on; policy left to other products. | SBOM + VEX are the system of record with deterministic replay, Decision Capsules, and signed evidence. |
|
||||
| **Snyk Container** | Static reachability bounded to first-party code. | Hybrid reachability links code, base images, cluster policies, and optional runtime probes so the entire stack shares one score. |
|
||||
| **JFrog Xray** | Contextual scoring lives behind a closed service. | Policies, DSSE bundles, Decision Capsules, and transparency logs are open, auditable, and portable. |
|
||||
| **Docker Scout** | Provenance remains inside Docker's ecosystem. | Any OCI provenance is ingested, signed with your crypto profile, and replayed offline with full evidence. |
|
||||
| **Wiz / runtime sensors** | Runtime telemetry is separate from build-time SBOM/VEX evidence. | Optional runtime probes feed the same deterministic lattice so build- and run-time context stay consistent; all evidence sealed in Decision Capsules. |
|
||||
|
||||
## Dig Deeper (curated reading)
|
||||
|
||||
@@ -63,4 +70,4 @@ Need more? The full documentation tree – ADRs, per‑module operations, schema
|
||||
|
||||
> **Configuration note:** Feature exposure stays governed by `StellaOps.Scanner.WebService` (`scanner.*` / `SCANNER__*`) settings. See [modules/scanner/architecture.md](modules/scanner/architecture.md) and [modules/scanner/design/surface-env.md](modules/scanner/design/surface-env.md) for the authoritative schema; the docs remain pristine while configuration decides what surfaces for each deployment.
|
||||
|
||||
© 2025 Stella Ops contributors – AGPL‑3.0‑or‑later
|
||||
© 2025 Stella Ops contributors – AGPL‑3.0‑or‑later
|
||||
|
||||
@@ -1,41 +1,49 @@
|
||||
# Key Features – Capability Cards
|
||||
|
||||
Each card is a fast read pairing the headline capability with the evidence that backs it and why it matters day to day.
|
||||
> 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.
|
||||
|
||||
Each card below pairs the headline capability with the evidence that backs it and why it matters day to day.
|
||||
|
||||
<!-- TODO: Review for separate approval - added Decision Capsules as feature 0 -->
|
||||
## 0. Decision Capsules — Audit-Grade Evidence Bundles (2025-12)
|
||||
- **What it is:** Every scan result is sealed in a **Decision Capsule**—a content-addressed bundle containing all inputs, outputs, and evidence needed to reproduce and verify the vulnerability decision.
|
||||
- **Evidence:** Each capsule includes: exact SBOM (and source provenance if available), exact vuln feed snapshots (or IDs to frozen snapshots), reachability evidence (static artifacts + runtime traces if any), policy version + lattice rules, derived VEX statements, and signatures over all of the above.
|
||||
- **Why it matters:** Auditors can re-run any capsule bit-for-bit to verify the outcome. This is the heart of audit-grade assurance—every decision becomes a provable, replayable fact.
|
||||
|
||||
## 1. Delta SBOM Engine
|
||||
- **What it is:** Layer-aware ingestion keeps the SBOM catalog content-addressed; rescans only fetch new layers and update dependency/vulnerability cartographs.
|
||||
- **Evidence:** Deterministic Replay Manifest (SRM) captures the exact analyzer inputs/outputs per layer.
|
||||
- **Why it matters:** Warm scans drop below one second, so CI/CD pipelines stay fast even under the free-tier quota.
|
||||
|
||||
## 2. Lattice Policy + OpenVEX
|
||||
- **What it is:** Policy engine merges SBOM, advisories, VEX, and waivers through lattice logic that prioritises exploitability.
|
||||
- **Evidence:** OpenVEX is treated as first-class input; the policy UI renders explain traces, while custom rule packs let teams automate muting, expirations, and non-VEX alert logic.
|
||||
- **Why it matters:** Teams can distinguish exploitable risk from noise, tune the experience beyond VEX statements, and prove why a deployment was blocked or allowed.
|
||||
## 2. Lattice Policy + OpenVEX (Evidence-Linked)
|
||||
- **What it is:** Policy engine merges SBOM, advisories, VEX, and waivers through lattice logic that prioritises exploitability. Every VEX assertion includes pointers to an internal evidence graph.
|
||||
- **Evidence:** OpenVEX is treated as first-class input; the policy UI renders explain traces with proof-linked decisions. Custom rule packs let teams automate muting, expirations, and non-VEX alert logic.
|
||||
- **Why it matters:** Teams can distinguish exploitable risk from noise, tune the experience beyond VEX statements, and prove why a deployment was blocked or allowed. Unlike simplistic yes/no approaches, the lattice model explicitly handles an "Unknown" state, ensuring incomplete data doesn't lead to false safety.
|
||||
|
||||
## 3. Sovereign Crypto Profiles
|
||||
- **What it is:** Bring-your-own trust bundles that switch signing algorithms (FIPS, eIDAS, GOST, SM) without code changes.
|
||||
- **Evidence:** Crypto profiles travel with Offline Update Kits and post-quantum trust packs, keeping signatures verifiable in regulated sectors.
|
||||
- **Why it matters:** You meet regional crypto requirements while keeping provenance attestations consistent across tenants.
|
||||
|
||||
## 4. Deterministic Replay & Evidence Bundles
|
||||
- **What it is:** Every scan produces a DSSE + SRM bundle that can be replayed with `stella replay`.
|
||||
## 4. Deterministic Replay & Evidence Bundles — The Heart of Audit-Grade Assurance
|
||||
- **What it is:** Every scan produces a DSSE + SRM bundle that can be replayed with `stella replay srm.yaml`.
|
||||
- **Evidence:** Replay manifests capture analyzer versions, lattice state, and attestations in content-addressed storage for audit trails.
|
||||
- **Why it matters:** Auditors and incident responders can re-run a historical scan and trust the findings were not tampered with.
|
||||
- **Why it matters:** A CVE found 6 months ago can be re-verified today by running `stella replay srm.yaml`, yielding an identical result—an audit trail no other scanner provides. This is why Stella decisions survive auditors, regulators, and supply-chain propagation.
|
||||
|
||||
## 5. Transparent Quotas & Offline Operations
|
||||
- **What it is:** Redis-backed counters surface `{{ quota_token }}` scans/day via headers, UI banners, and `/quota` API; Offline Update Kits mirror feeds.
|
||||
- **Evidence:** Quota tokens verify locally using bundled public keys, and Offline Update Kits include mirrored advisories, SBOM feeds, and VEX sources.
|
||||
- **Why it matters:** You stay within predictable limits, avoid surprise throttling, and operate entirely offline when needed.
|
||||
|
||||
## 6. Signed Reachability Proofs (Hybrid)
|
||||
- **What it is:** Every reachability graph is sealed with a graph-level DSSE and optional edge-bundle DSSEs for runtime/init/contested edges; Rekor-backed when enabled.
|
||||
## 6. Signed Reachability Proofs — Hybrid Static + Runtime Attestations
|
||||
- **What it is:** Every reachability graph is sealed with a graph-level DSSE and optional edge-bundle DSSEs for runtime/init/contested edges; Rekor-backed when enabled. Both static call-graph edges and runtime-derived edges can be attested—true hybrid reachability.
|
||||
- **Evidence:** CAS layout `cas://reachability/graphs/{hash}` + `{hash}.dsse`; edge bundles capped and sorted; quarantine/dispute uses per-edge revocation. See `docs/reachability/hybrid-attestation.md`.
|
||||
- **Why it matters:** You can prove (or contest) exactly why a vuln is reachable, replay results offline, and avoid flooding transparency logs.
|
||||
- **Why it matters:** You can prove (or contest) exactly why a vuln is reachable, replay results offline, and avoid flooding transparency logs. Hybrid analysis combining static call-graph analysis with runtime process tracing provides confidence across build and runtime contexts.
|
||||
|
||||
## 7. Competitive Moats (2025-11 refresh)
|
||||
- **What it is:** Deterministic replay, lattice VEX, sovereign crypto profiles, proof graph, and hybrid reachability attestations held as first-class product pillars.
|
||||
## 7. Competitive Moats — Four Capabilities (2025-12 refresh)
|
||||
- **What it is:** Four capabilities no competitor offers together: (1) Signed Reachability, (2) Deterministic Replay, (3) Explainable Policy (Lattice VEX), (4) Sovereign + Offline Operation. Plus Decision Capsules for audit-grade evidence bundles.
|
||||
- **Evidence:** `docs/market/competitive-landscape.md` distils a 15-vendor comparison; `03_VISION.md` lists moats; `docs/reachability/lead.md` details the reachability proof moat.
|
||||
- **Why it matters:** Clear differentiation guides roadmap and sales; keeps us focused on replayable, sovereign, and explainable security.
|
||||
- **Why it matters:** Clear differentiation guides roadmap and sales; keeps us focused on replayable, sovereign, evidence-linked, and explainable security.
|
||||
|
||||
## 8. Deterministic Task Packs (2025-11)
|
||||
- **What it is:** TaskRunner executes declarative Task Packs with plan-hash binding, approvals, sealed-mode enforcement, and DSSE evidence bundles.
|
||||
|
||||
170
docs/marketing/decision-capsules.md
Normal file
170
docs/marketing/decision-capsules.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Decision Capsules — Audit-Grade Evidence Bundles
|
||||
|
||||
> Status: Marketing Bridge Document · December 2025
|
||||
> Audience: Technical buyers, security architects, compliance teams
|
||||
|
||||
<!-- TODO: Review for separate approval - new marketing bridge doc -->
|
||||
|
||||
## Executive Summary
|
||||
|
||||
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.
|
||||
|
||||
**Decision Capsules** are the mechanism that makes this possible: content-addressed bundles that seal every scan result with all inputs, outputs, and evidence needed to reproduce and verify vulnerability decisions. This is the heart of audit-grade assurance—every decision becomes a provable, replayable fact.
|
||||
|
||||
**Key message**: "Prove every fix, audit every finding."
|
||||
|
||||
---
|
||||
|
||||
## What is a Decision Capsule?
|
||||
|
||||
A Decision Capsule is a signed, immutable bundle containing:
|
||||
|
||||
| Component | Description | Purpose |
|
||||
|-----------|-------------|---------|
|
||||
| **Exact SBOM** | The precise software bill of materials used for the scan | Reproducibility |
|
||||
| **Vuln feed snapshots** | Frozen advisory data (NVD, OSV, GHSA, etc.) at scan time | Consistency |
|
||||
| **Reachability evidence** | Static call-graph artifacts + runtime traces | Proof of analysis |
|
||||
| **Policy version** | Lattice rules and threshold configuration | Explainability |
|
||||
| **Derived VEX** | The vulnerability status decision with justification | Outcome |
|
||||
| **DSSE signatures** | Cryptographic signatures over all contents | Integrity |
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Decision Capsule │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────┐ ┌─────────────┐ ┌──────────────────┐ │
|
||||
│ │ SBOM │ │ Vuln Feeds │ │ Reachability │ │
|
||||
│ │ (exact) │ │ (snapshots) │ │ Evidence │ │
|
||||
│ └─────────┘ └─────────────┘ └──────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │
|
||||
│ │ Policy Ver │ │ Derived VEX │ │ DSSE Signatures │ │
|
||||
│ │ + Lattice │ │ + Justify. │ │ (integrity) │ │
|
||||
│ └─────────────┘ └─────────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why Decision Capsules Matter
|
||||
|
||||
### For Security Teams
|
||||
- **Reproduce any finding**: Re-run a scan from 6 months ago with identical results
|
||||
- **Trust the evidence**: Every decision has cryptographic proof
|
||||
- **Explain to stakeholders**: Clear justification for every block/allow decision
|
||||
|
||||
### For Compliance Teams
|
||||
- **Audit-ready artifacts**: Evidence bundles meet regulatory requirements
|
||||
- **Chain of custody**: Full provenance from scan to decision
|
||||
- **Tamper-evident**: Any modification breaks the signature
|
||||
|
||||
### For Developers
|
||||
- **No "works on my machine"**: Reproducible results across environments
|
||||
- **Fast debugging**: Trace exactly why a vulnerability was flagged
|
||||
- **CI/CD integration**: Capsules fit into existing pipelines
|
||||
|
||||
---
|
||||
|
||||
## Competitive Differentiation
|
||||
|
||||
| Capability | Stella Ops | Competitors |
|
||||
|------------|------------|-------------|
|
||||
| **Sealed evidence** | Decision Capsules with DSSE signatures | Scan reports (mutable) |
|
||||
| **Reproducibility** | Bit-for-bit replay from frozen feeds | "Re-scan" with current data |
|
||||
| **Evidence linking** | Every VEX decision has proof pointers | VEX statements without proof |
|
||||
| **Offline verification** | Full verification without network | Requires SaaS connection |
|
||||
|
||||
**Battlecard one-liner**: "Prove every fix, audit every finding—Decision Capsules seal evidence so you can replay scans bit-for-bit."
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Capsule Format
|
||||
|
||||
```yaml
|
||||
apiVersion: capsule.stellaops.dev/v1
|
||||
metadata:
|
||||
id: "cap-2025-12-11-abc123"
|
||||
timestamp: "2025-12-11T14:30:00Z"
|
||||
scan_id: "scan-xyz789"
|
||||
inputs:
|
||||
sbom:
|
||||
format: "cyclonedx@1.6"
|
||||
digest: "sha256:..."
|
||||
feeds:
|
||||
- name: "nvd"
|
||||
snapshot: "2025-12-11"
|
||||
digest: "sha256:..."
|
||||
- name: "osv"
|
||||
snapshot: "2025-12-11"
|
||||
digest: "sha256:..."
|
||||
policy:
|
||||
version: "corp-policy@2025-12-01"
|
||||
digest: "sha256:..."
|
||||
reachability:
|
||||
graph_hash: "blake3:..."
|
||||
edge_bundles: ["bundle:001", "bundle:002"]
|
||||
outputs:
|
||||
vex:
|
||||
format: "openvex"
|
||||
digest: "sha256:..."
|
||||
findings:
|
||||
digest: "sha256:..."
|
||||
signatures:
|
||||
- scheme: "DSSE"
|
||||
profile: "FIPS-140-3"
|
||||
signer: "build-ca@corp"
|
||||
```
|
||||
|
||||
### CLI Commands
|
||||
|
||||
```bash
|
||||
# Create a capsule during scan
|
||||
stella scan --image reg/app@sha256:... --capsule-out capsule.yaml
|
||||
|
||||
# Replay a capsule
|
||||
stella replay capsule.yaml --assert-digest sha256:...
|
||||
|
||||
# Verify capsule integrity
|
||||
stella capsule verify capsule.yaml
|
||||
|
||||
# Extract evidence for audit
|
||||
stella capsule export capsule.yaml --format audit-bundle
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Four Capabilities
|
||||
|
||||
Decision Capsules connect all four capabilities:
|
||||
|
||||
1. **Signed Reachability** → Reachability evidence sealed in capsule
|
||||
2. **Deterministic Replay** → Capsule enables bit-for-bit replay
|
||||
3. **Explainable Policy** → Policy version + derived VEX in capsule
|
||||
4. **Sovereign Offline** → Capsule verifiable without network
|
||||
|
||||
---
|
||||
|
||||
## Customer Scenarios
|
||||
|
||||
### Scenario 1: Regulatory Audit
|
||||
"Show me the evidence for this CVE decision from 6 months ago."
|
||||
→ Replay the Decision Capsule, get identical results, provide the signed evidence bundle.
|
||||
|
||||
### Scenario 2: Incident Response
|
||||
"This vulnerability was marked not_affected—prove it."
|
||||
→ Extract the reachability evidence from the capsule showing the vulnerable code path is not reachable.
|
||||
|
||||
### Scenario 3: Supply Chain Attestation
|
||||
"Provide proof that this image was scanned and passed policy."
|
||||
→ Share the Decision Capsule; downstream consumers can verify the signature independently.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `docs/key-features.md` — Feature overview
|
||||
- `docs/03_VISION.md` — Product vision and moats
|
||||
- `docs/reachability/lattice.md` — Reachability scoring
|
||||
- `docs/vex/consensus-overview.md` — VEX consensus engine
|
||||
228
docs/marketing/evidence-linked-vex.md
Normal file
228
docs/marketing/evidence-linked-vex.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# Evidence-Linked VEX — Proof-Backed Vulnerability Decisions
|
||||
|
||||
> Status: Marketing Bridge Document · December 2025
|
||||
> Audience: Technical buyers, security architects, compliance teams
|
||||
|
||||
<!-- TODO: Review for separate approval - new marketing bridge doc -->
|
||||
|
||||
## Executive Summary
|
||||
|
||||
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.
|
||||
|
||||
**Evidence-Linked VEX** is how those decisions are structured: every vulnerability status assertion includes pointers to the underlying proof. Unlike traditional VEX that simply states "not_affected" without explanation, Stella Ops provides a complete evidence graph connecting the decision to its inputs.
|
||||
|
||||
**Key message**: "VEX you can prove."
|
||||
|
||||
---
|
||||
|
||||
## What is Evidence-Linked VEX?
|
||||
|
||||
Every VEX decision in Stella Ops links to an **evidence graph** containing:
|
||||
|
||||
| Evidence Type | Description | Link Format |
|
||||
|---------------|-------------|-------------|
|
||||
| **SBOM match** | Component identity confirmation | `sbom_hash`, `purl` |
|
||||
| **Vuln snapshot** | Exact advisory data at decision time | `advisory_snapshot_id` |
|
||||
| **Reachability proof** | Static/runtime analysis artifacts | `reach_decision_id`, `graph_hash` |
|
||||
| **Runtime observation** | Process traces, method hits | `runtime_trace_id` |
|
||||
| **Mitigation evidence** | WAF rules, config flags, patches | `mitigation_id` |
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────┐
|
||||
│ VEX Decision: NOT_AFFECTED │
|
||||
├────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ "CVE-2025-1234 does not affect pkg:nuget/Example@1.2.3" │
|
||||
│ │
|
||||
│ Evidence Graph: │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ SBOM Match │───▶│ Vuln Record │───▶│ Reach Proof │ │
|
||||
│ │ sha256:abc │ │ nvd-snap-01 │ │ graph:xyz │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────┐ │
|
||||
│ │ Runtime Obs │ │
|
||||
│ │ trace:456 │ │
|
||||
│ └─────────────┘ │
|
||||
└────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why Evidence-Linked VEX Matters
|
||||
|
||||
### The Problem with Traditional VEX
|
||||
|
||||
Traditional VEX statements are **assertions without proof**:
|
||||
|
||||
```json
|
||||
{
|
||||
"vulnerability": "CVE-2025-1234",
|
||||
"status": "not_affected",
|
||||
"justification": "vulnerable_code_not_present"
|
||||
}
|
||||
```
|
||||
|
||||
Questions this doesn't answer:
|
||||
- How do you know the vulnerable code isn't present?
|
||||
- What analysis was performed?
|
||||
- Can this decision be independently verified?
|
||||
- What happens when the advisory changes?
|
||||
|
||||
### The Evidence-Linked Solution
|
||||
|
||||
Stella Ops VEX includes **proof pointers**:
|
||||
|
||||
```json
|
||||
{
|
||||
"vulnerability": "CVE-2025-1234",
|
||||
"status": "not_affected",
|
||||
"justification": "vulnerable_code_not_present",
|
||||
"evidence_refs": {
|
||||
"sbom": "sha256:abc123...",
|
||||
"advisory_snapshot": "nvd-2025-12-01",
|
||||
"reachability": {
|
||||
"decision_id": "reach:xyz789",
|
||||
"graph_hash": "blake3:...",
|
||||
"score": 22,
|
||||
"state": "POSSIBLE"
|
||||
},
|
||||
"mitigations": ["mit:waf-rule-123"]
|
||||
},
|
||||
"replay_bundle": "capsule:2025-12-11-abc"
|
||||
}
|
||||
```
|
||||
|
||||
This enables:
|
||||
- **Independent verification**: Anyone can follow the proof chain
|
||||
- **Deterministic replay**: Re-run the exact analysis
|
||||
- **Audit compliance**: Evidence meets regulatory requirements
|
||||
|
||||
---
|
||||
|
||||
## Explicit "Unknown" State Handling
|
||||
|
||||
A key differentiator: Stella Ops explicitly handles **incomplete data**.
|
||||
|
||||
| Traditional Approach | Stella Ops Approach |
|
||||
|---------------------|---------------------|
|
||||
| Binary: affected/not_affected | Three states: affected/not_affected/under_investigation |
|
||||
| Missing data → assume safe | Missing data → mark "Unknown" |
|
||||
| False negatives possible | Incomplete data surfaced explicitly |
|
||||
|
||||
**Why this matters**: Incomplete data never leads to false safety. If reachability analysis is inconclusive, the decision stays `under_investigation` until sufficient evidence is gathered.
|
||||
|
||||
---
|
||||
|
||||
## Competitive Differentiation
|
||||
|
||||
| Capability | Stella Ops | Competitors |
|
||||
|------------|------------|-------------|
|
||||
| **VEX output** | Evidence-linked with proof graph | Simple VEX statements |
|
||||
| **Verification** | Independent proof chain verification | Trust the vendor |
|
||||
| **Unknown handling** | Explicit `under_investigation` state | Binary yes/no |
|
||||
| **Replay** | Bit-for-bit from Decision Capsules | Not possible |
|
||||
|
||||
**Battlecard one-liner**: "Competitors export VEX formats; Stella provides VEX you can prove."
|
||||
|
||||
---
|
||||
|
||||
## Evidence Graph Structure
|
||||
|
||||
### Full Evidence Chain
|
||||
|
||||
```
|
||||
Component (PURL)
|
||||
│
|
||||
├──▶ SBOM Document
|
||||
│ └── digest: sha256:...
|
||||
│
|
||||
├──▶ Vulnerability Record
|
||||
│ ├── source: NVD
|
||||
│ ├── snapshot_id: nvd-2025-12-01
|
||||
│ └── digest: sha256:...
|
||||
│
|
||||
├──▶ Reachability Analysis
|
||||
│ ├── static_graph: blake3:...
|
||||
│ ├── runtime_traces: [trace:001, trace:002]
|
||||
│ ├── score: 22 (POSSIBLE)
|
||||
│ └── evidence: [edge:abc, edge:def]
|
||||
│
|
||||
├──▶ Mitigations
|
||||
│ ├── waf_rule: rule:xyz
|
||||
│ └── config_flag: flag:disabled
|
||||
│
|
||||
└──▶ Policy Decision
|
||||
├── version: corp-policy@2025-12-01
|
||||
├── digest: sha256:...
|
||||
└── threshold: score < 25 → not_affected
|
||||
```
|
||||
|
||||
### Evidence Types
|
||||
|
||||
| Evidence Kind | Confidence Impact | Source |
|
||||
|---------------|-------------------|--------|
|
||||
| `StaticCallEdge` | +30 base score | IL/bytecode analysis |
|
||||
| `RuntimeMethodHit` | +60 base score | EventPipe/JFR |
|
||||
| `UserInputSource` | +80 base score | Taint analysis |
|
||||
| `WafRulePresent` | -20 mitigation | WAF connector |
|
||||
| `PatchLevel` | -40 mitigation | Patch diff |
|
||||
|
||||
---
|
||||
|
||||
## VEX Propagation
|
||||
|
||||
Evidence-Linked VEX enables **scalable supply chain sharing**:
|
||||
|
||||
1. **Generate**: Create evidence-linked VEX from scan results
|
||||
2. **Sign**: Apply DSSE signatures with your trust root
|
||||
3. **Share**: Propagate to downstream consumers
|
||||
4. **Verify**: Consumers verify independently using proof pointers
|
||||
|
||||
```bash
|
||||
# Generate evidence-linked VEX
|
||||
stella vex generate --scan scan-123 --format openvex --include-evidence
|
||||
|
||||
# Export for downstream
|
||||
stella vex export --decisions "decision:abc123" --bundle evidence-bundle.tar
|
||||
|
||||
# Downstream verification
|
||||
stella vex verify evidence-bundle.tar --trust-root downstream-ca
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Four Capabilities
|
||||
|
||||
Evidence-Linked VEX connects to the four capabilities:
|
||||
|
||||
1. **Signed Reachability** → Reachability proof in evidence graph
|
||||
2. **Deterministic Replay** → Evidence reproducible via Decision Capsules
|
||||
3. **Explainable Policy** → Policy version and thresholds traced
|
||||
4. **Sovereign Offline** → Evidence verifiable without network
|
||||
|
||||
---
|
||||
|
||||
## Customer Scenarios
|
||||
|
||||
### Scenario 1: Vendor VEX Verification
|
||||
"The vendor says this CVE doesn't affect us—can we trust it?"
|
||||
→ Check their evidence graph; verify the reachability analysis matches your deployment.
|
||||
|
||||
### Scenario 2: Compliance Audit
|
||||
"Prove this CVE was properly analyzed."
|
||||
→ Show the evidence chain from SBOM → advisory → reachability → decision.
|
||||
|
||||
### Scenario 3: Supply Chain Propagation
|
||||
"Pass our VEX decisions to downstream consumers."
|
||||
→ Export evidence-linked VEX; consumers can independently verify.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `docs/vex/consensus-overview.md` — VEX consensus engine
|
||||
- `docs/reachability/lattice.md` — Reachability scoring model
|
||||
- `docs/marketing/decision-capsules.md` — Decision Capsules overview
|
||||
- `docs/marketing/hybrid-reachability.md` — Hybrid analysis
|
||||
239
docs/marketing/hybrid-reachability.md
Normal file
239
docs/marketing/hybrid-reachability.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Hybrid Reachability — Static + Runtime Analysis
|
||||
|
||||
> Status: Marketing Bridge Document · December 2025
|
||||
> Audience: Technical buyers, security architects, compliance teams
|
||||
|
||||
<!-- TODO: Review for separate approval - new marketing bridge doc -->
|
||||
|
||||
## Executive Summary
|
||||
|
||||
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.
|
||||
|
||||
**Hybrid Reachability** is how we achieve accurate impact analysis: combining static call-graph analysis with runtime process tracing to determine whether vulnerable code is actually reachable. Both edge types are separately attestable with DSSE signatures, providing true hybrid analysis with cryptographic proof.
|
||||
|
||||
**Key message**: "True hybrid reachability—static and runtime signals share one verdict."
|
||||
|
||||
---
|
||||
|
||||
## What is Hybrid Reachability?
|
||||
|
||||
Traditional reachability analysis uses either:
|
||||
- **Static analysis**: Examines code without executing it (call graphs, data flow)
|
||||
- **Runtime analysis**: Observes actual execution (method hits, stack traces)
|
||||
|
||||
Stella Ops uses **both** and reconciles them into a unified reachability decision:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Hybrid Reachability │
|
||||
├────────────────────────┬────────────────────────────────────┤
|
||||
│ Static Analysis │ Runtime Analysis │
|
||||
├────────────────────────┼────────────────────────────────────┤
|
||||
│ • IL/bytecode walkers │ • .NET EventPipe │
|
||||
│ • ASP.NET routing │ • JVM JFR │
|
||||
│ • Call-graph edges │ • Node inspector │
|
||||
│ • Entry-point prox. │ • Go/Rust probes │
|
||||
├────────────────────────┴────────────────────────────────────┤
|
||||
│ │
|
||||
│ Lattice Engine │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ Merge signals → Score → VEX status │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ DSSE Attestation (Graph + Edges) │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why Hybrid Matters
|
||||
|
||||
### Limitations of Static-Only Analysis
|
||||
|
||||
| Issue | Description | Impact |
|
||||
|-------|-------------|--------|
|
||||
| **Over-reporting** | Reports paths that never execute | Alert fatigue |
|
||||
| **Dynamic dispatch** | Misses reflection, DI, runtime binding | False negatives |
|
||||
| **Framework magic** | ASP.NET/Spring routing not fully modeled | Incomplete coverage |
|
||||
| **Configuration** | Doesn't account for runtime config | Context-blind |
|
||||
|
||||
### Limitations of Runtime-Only Analysis
|
||||
|
||||
| Issue | Description | Impact |
|
||||
|-------|-------------|--------|
|
||||
| **Coverage gaps** | Only sees executed paths | Misses rare paths |
|
||||
| **Environment-specific** | Results vary by test coverage | Non-deterministic |
|
||||
| **No proactive detection** | Requires traffic to observe | Reactive, not preventive |
|
||||
| **Attack surface** | May miss dormant vulnerabilities | Security risk |
|
||||
|
||||
### Hybrid Solution
|
||||
|
||||
| Signal Type | Strength | Weakness | Hybrid Benefit |
|
||||
|-------------|----------|----------|----------------|
|
||||
| Static | Comprehensive coverage | Over-reports | Runtime filters false positives |
|
||||
| Runtime | Ground truth | Incomplete | Static catches unexercised paths |
|
||||
|
||||
**Result**: Higher confidence with lower false positive/negative rates.
|
||||
|
||||
---
|
||||
|
||||
## Reachability Lattice
|
||||
|
||||
Stella Ops uses a **confidence lattice** with explicit states:
|
||||
|
||||
```
|
||||
UNOBSERVED (0–9)
|
||||
< POSSIBLE (10–29)
|
||||
< STATIC_PATH (30–59)
|
||||
< DYNAMIC_SEEN (60–79)
|
||||
< DYNAMIC_USER_TAINTED (80–99)
|
||||
< EXPLOIT_CONSTRAINTS_REMOVED (100)
|
||||
```
|
||||
|
||||
| State | Evidence Required | VEX Mapping |
|
||||
|-------|-------------------|-------------|
|
||||
| UNOBSERVED | None | under_investigation |
|
||||
| POSSIBLE | Lockfile-only | under_investigation |
|
||||
| STATIC_PATH | Static call-graph edge | under_investigation |
|
||||
| DYNAMIC_SEEN | Runtime method hit | affected |
|
||||
| DYNAMIC_USER_TAINTED | User input reaches vuln | affected |
|
||||
| EXPLOIT_CONSTRAINTS_REMOVED | Full exploit chain | affected |
|
||||
|
||||
**Key feature**: The `under_investigation` state explicitly handles incomplete data—Stella never marks something "safe" without sufficient evidence.
|
||||
|
||||
---
|
||||
|
||||
## Attestation Model
|
||||
|
||||
Both static and runtime edges are attestable:
|
||||
|
||||
### Graph-Level Attestation (Required)
|
||||
|
||||
```yaml
|
||||
level: 0
|
||||
payload: richgraph-v1
|
||||
signature: DSSE
|
||||
storage: cas://reachability/graphs/{blake3}
|
||||
rekor: always
|
||||
```
|
||||
|
||||
### Edge-Bundle Attestation (Selective)
|
||||
|
||||
```yaml
|
||||
level: 1
|
||||
payload: edge-bundle (≤512 edges)
|
||||
criteria:
|
||||
- source: runtime
|
||||
- source: init_array/constructors
|
||||
- status: contested/quarantined
|
||||
signature: DSSE
|
||||
storage: cas://reachability/edges/{graph_hash}/{bundle_id}
|
||||
rekor: configurable
|
||||
```
|
||||
|
||||
This enables:
|
||||
- **Prove specific paths**: Attest individual runtime-observed edges
|
||||
- **Dispute resolution**: Quarantine/revoke specific edges
|
||||
- **Offline verification**: Verify without network access
|
||||
|
||||
---
|
||||
|
||||
## Competitive Differentiation
|
||||
|
||||
| Capability | Stella Ops | Competitors |
|
||||
|------------|------------|-------------|
|
||||
| **Analysis type** | Hybrid (static + runtime) | Usually one or the other |
|
||||
| **Attestation** | DSSE for both edge types | None or graph-only |
|
||||
| **Unknown handling** | Explicit `under_investigation` | Binary yes/no |
|
||||
| **Edge-level proof** | Selective edge-bundle DSSE | Not available |
|
||||
|
||||
**Battlecard one-liner**: "Static analysis sees code paths; runtime sees execution. Stella sees both—and proves it."
|
||||
|
||||
---
|
||||
|
||||
## Signal Sources
|
||||
|
||||
### Static Analysis Signals
|
||||
|
||||
| Signal | Source | Evidence Kind |
|
||||
|--------|--------|---------------|
|
||||
| Call-graph edges | Roslyn/IL walkers | `StaticCallEdge` |
|
||||
| Entry-point proximity | Framework routing models | `StaticEntryPointProximity` |
|
||||
| Package declarations | Lockfile/manifest | `StaticPackageDeclaredOnly` |
|
||||
|
||||
### Runtime Analysis Signals
|
||||
|
||||
| Signal | Source | Evidence Kind |
|
||||
|--------|--------|---------------|
|
||||
| Method hits | .NET EventPipe | `RuntimeMethodHit` |
|
||||
| Stack samples | JVM JFR | `RuntimeStackSample` |
|
||||
| HTTP routes | ASP.NET/Spring routing | `RuntimeHttpRouteHit` |
|
||||
| User input | Taint analysis | `UserInputSource` |
|
||||
|
||||
### Mitigation Signals
|
||||
|
||||
| Signal | Source | Effect |
|
||||
|--------|--------|--------|
|
||||
| WAF rules | WAF connectors | Score reduction |
|
||||
| Config flags | Config snapshot | Score reduction |
|
||||
| Network isolation | Container policy | Score reduction |
|
||||
|
||||
---
|
||||
|
||||
## Integration with Four Capabilities
|
||||
|
||||
Hybrid Reachability is **Capability #1** of four:
|
||||
|
||||
1. **Signed Reachability** ← This document
|
||||
2. **Deterministic Replay** → Reachability evidence in Decision Capsules
|
||||
3. **Explainable Policy** → Reachability feeds the lattice VEX engine
|
||||
4. **Sovereign Offline** → All analysis verifiable without network
|
||||
|
||||
---
|
||||
|
||||
## Customer Scenarios
|
||||
|
||||
### Scenario 1: False Positive Reduction
|
||||
"We're drowning in vulnerability alerts."
|
||||
→ Hybrid analysis shows 70% of reported CVEs have no reachable path; focus on the 30% that matter.
|
||||
|
||||
### Scenario 2: Runtime Validation
|
||||
"Static analysis says this is reachable—is it really?"
|
||||
→ Runtime probes observed 0 hits over 30 days; downgrade to `under_investigation`.
|
||||
|
||||
### Scenario 3: Audit Proof
|
||||
"Prove the vulnerable code path is not reachable."
|
||||
→ Show the signed reachability graph with static call-graph (no path) + runtime traces (no hits).
|
||||
|
||||
### Scenario 4: Contested Edge
|
||||
"We disagree with this reachability finding."
|
||||
→ Mark the edge as disputed; policy excludes it; recompute reachability; surface the delta.
|
||||
|
||||
---
|
||||
|
||||
## CLI Integration
|
||||
|
||||
```bash
|
||||
# Scan with hybrid reachability
|
||||
stella scan --image reg/app@sha256:... --reachability hybrid
|
||||
|
||||
# Verify reachability graph
|
||||
stella graph verify --graph blake3:abc123
|
||||
|
||||
# Show reachability decision for a CVE
|
||||
stella reach show --cve CVE-2025-1234 --component pkg:nuget/Example@1.2.3
|
||||
|
||||
# Export edge bundles for audit
|
||||
stella reach export --graph blake3:abc123 --bundles-only
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `docs/reachability/hybrid-attestation.md` — Attestation technical details
|
||||
- `docs/reachability/lattice.md` — Scoring model
|
||||
- `docs/marketing/decision-capsules.md` — Decision Capsules overview
|
||||
- `docs/marketing/evidence-linked-vex.md` — Evidence-linked VEX
|
||||
16
docs/moat.md
16
docs/moat.md
@@ -1,13 +1,23 @@
|
||||
# StellaOps Moat Track — Spec Outline v0.3
|
||||
# StellaOps Moat Track — Spec Outline v0.4
|
||||
|
||||
> 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 - updated moat introduction -->
|
||||
**Four capabilities no competitor offers together:**
|
||||
|
||||
1. **Signed Reachability** – Every reachability graph is sealed with DSSE; optional edge-bundle attestations for runtime/init/contested paths. Both static call-graph edges and runtime-derived edges can be attested—true hybrid reachability.
|
||||
2. **Deterministic Replay** – Scans run bit-for-bit identical from frozen feeds and analyzer manifests. Decision Capsules seal all evidence for audit-grade reproducibility.
|
||||
3. **Explainable Policy (Lattice VEX)** – The lattice engine merges SBOM data, advisories, VEX statements, and waivers into a single verdict with human-readable justifications. Evidence-linked VEX decisions with explicit "Unknown" state handling.
|
||||
4. **Sovereign + Offline Operation** – FIPS, eIDAS, GOST, SM, or PQC profiles are first-class toggles. Offline Kits and regional crypto profiles keep every decision inside your perimeter.
|
||||
|
||||
**Scope of this doc:**
|
||||
(1) Deterministic Replayable Scans (SRM), (2) Policy Engine & Lattice UI, (3) Sovereign Readiness (CryptoProfile + RootPack), (4) Attestation Observability Graph (AOG), (5) Procurement‑Grade Trust Statement, (6) Third‑Party Proof Channel, (7) Zastava differential SBOM + AI scheduler.
|
||||
(1) Decision Capsules, (2) Deterministic Replayable Scans (SRM), (3) Policy Engine & Lattice UI, (4) Sovereign Readiness (CryptoProfile + RootPack), (5) Attestation Observability Graph (AOG), (6) Procurement‑Grade Trust Statement, (7) Third‑Party Proof Channel, (8) Zastava differential SBOM + AI scheduler.
|
||||
|
||||
Cross‑cutting principles: offline‑first, cryptographic determinism, evidence‑bound decisions, regional crypto compliance, minimal operational friction.
|
||||
|
||||
---
|
||||
|
||||
## 0) Shared Concepts (applies to all 7)
|
||||
## 0) Shared Concepts (applies to all 8)
|
||||
|
||||
* **Artifact identity:** digest-first (OCI image digest, file sha256).
|
||||
* **Canonicalization:** all structured payloads (SBOM, SRM, Trust Statement JSON, VEX) are normalized via Canonical JSON (RFC‑8785‑like) prior to hashing/signing.
|
||||
|
||||
@@ -1,10 +1,25 @@
|
||||
# Hybrid Reachability Attestation (Graph + Edge-Bundle)
|
||||
|
||||
> Decision date: 2025-11-23 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild
|
||||
> Decision date: 2025-12-11 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild
|
||||
|
||||
<!-- TODO: Review for separate approval - updated hybrid attestation introduction -->
|
||||
## 0. Context: Four Capabilities
|
||||
|
||||
This document supports **Signed Reachability**—one of four capabilities no competitor offers together:
|
||||
|
||||
1. **Signed Reachability** – Every reachability graph is sealed with DSSE; optional edge-bundle attestations for runtime/init/contested paths. Both static call-graph edges and runtime-derived edges can be attested—true hybrid reachability.
|
||||
2. **Deterministic Replay** – Scans run bit-for-bit identical from frozen feeds and analyzer manifests.
|
||||
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 as first-class toggles.
|
||||
|
||||
All evidence is sealed in **Decision Capsules** for audit-grade reproducibility.
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose
|
||||
- Guarantee replayable, signed reachability evidence with **graph-level DSSE** for every scan while enabling **selective edge-level DSSE bundles** when finer provenance or dispute handling is required.
|
||||
- Keep CI/offline bundles lean (graph-first), but allow auditors/regulators to quarantine or prove individual edges without regenerating whole graphs.
|
||||
- Support **hybrid reachability** by attesting both static call-graph edges and runtime-derived edges.
|
||||
|
||||
## 2. Attestation levels
|
||||
- **Level 0 (Graph DSSE) — Required**
|
||||
@@ -24,6 +39,7 @@
|
||||
- Always emit Level 0 graph + manifest.
|
||||
- When criteria match, emit Level 1 bundles; include `bundle_reason` (e.g., `runtime-hit`, `init-root`, `third-party`, `disputed`).
|
||||
- Canonicalise JSON (sorted keys/arrays) before hashing; BLAKE3 as graph hash, SHA-256 inside bundles.
|
||||
- For hybrid reachability: tag edges with `source: static` or `source: runtime` to distinguish call-graph derived vs. runtime-observed edges.
|
||||
- **Attestor/Signer**
|
||||
- Apply DSSE for both levels; respect sovereign crypto modes (FIPS/GOST/SM/PQC) from environment.
|
||||
- Rekor: push graph envelope digests; push edge-bundle digests only when `rekor_publish=true` (policy/default for high-risk bundles).
|
||||
@@ -35,7 +51,7 @@
|
||||
- **Policy**
|
||||
- Default trust path: graph DSSE + CAS object.
|
||||
- When an edge is quarantined/contested, drop it from consideration if an edge-bundle DSSE marks it `revoked=true` or if the Unknowns registry lists it with policy quarantine flag.
|
||||
- For “evidence-required” rules, require either (a) graph DSSE + policy_hash match **or** (b) edge-bundle DSSE that covers the vulnerable path edges.
|
||||
- For "evidence-required" rules, require either (a) graph DSSE + policy_hash match **or** (b) edge-bundle DSSE that covers the vulnerable path edges.
|
||||
- **Replay/Bench/CLI**
|
||||
- `stella graph verify` should accept `--graph {hash}` and optional `--edge-bundles` to validate deeper provenance offline.
|
||||
|
||||
@@ -43,13 +59,32 @@
|
||||
- **Happy path**: verify graph DSSE → verify Rekor inclusion (or mirror) → hash graph body → match `graph_hash` in policy/replay manifest → accept.
|
||||
- **Dispute/quarantine**: mark specific `edge_id` as `revoked` in an edge-bundle DSSE; Policy/Signals exclude it, recompute reachability, and surface delta in explainers.
|
||||
- **Offline**: retain graph DSSE and selected edge-bundles inside replay pack; Rekor proofs cached when available.
|
||||
- **Sovereign Verification Mode**: Even with no internet, all signatures and transparency proofs can be locally verified using Offline Update Kits.
|
||||
|
||||
## 6. Performance & storage guardrails
|
||||
- Default: only graph DSSE is mandatory; edge-bundles capped at 512 edges per envelope and emitted only on criteria above.
|
||||
- Rekor flood control: cap edge-bundle Rekor submissions per graph (config `reachability.edgeBundles.maxRekorPublishes`, default 5). Others stay CAS-only.
|
||||
- Determinism: bundle ordering = stable sort by `(bundle_reason, edge_id)`; hash before signing.
|
||||
|
||||
## 7. Open decisions (tracked in Sprint 0401 tasks 53–56)
|
||||
## 7. Hybrid Reachability Details
|
||||
|
||||
<!-- TODO: Review for separate approval - added hybrid reachability details -->
|
||||
Stella Ops provides **true hybrid reachability** by combining:
|
||||
|
||||
| Signal Type | Source | Attestation |
|
||||
|-------------|--------|-------------|
|
||||
| Static call-graph edges | IL/bytecode analysis, framework routing models, entry-point proximity | Graph DSSE (Level 0) |
|
||||
| Runtime-observed edges | EventPipe, JFR, Node inspector, Go/Rust probes | Edge-bundle DSSE (Level 1) with `source: runtime` |
|
||||
|
||||
**Why hybrid matters:**
|
||||
- Static analysis catches code paths that may not execute during observed runtime
|
||||
- Runtime analysis catches dynamic dispatch, reflection, and framework-injected paths
|
||||
- Combining both provides confidence across build and runtime contexts
|
||||
- Each edge type is separately attestable for audit and dispute resolution
|
||||
|
||||
**Evidence linking:** Each edge in the graph or bundle includes `evidenceRefs` pointing to the underlying proof artifacts (static analysis artifacts, runtime traces), enabling **evidence-linked VEX decisions**.
|
||||
|
||||
## 8. Open decisions (tracked in Sprint 0401 tasks 53–56)
|
||||
- Rekor publish defaults per deployment tier (regulated vs standard).
|
||||
- CLI UX for selective bundle verification.
|
||||
- Bench coverage for edge-bundle verification time/size.
|
||||
|
||||
@@ -1,15 +1,20 @@
|
||||
# Reachability Lattice & Scoring Model
|
||||
|
||||
> **Status:** Draft – mirrors the November 2025 advisory on confidence-based reachability.
|
||||
> **Status:** Draft – mirrors the December 2025 advisory on confidence-based reachability.
|
||||
> **Owners:** Scanner Guild · Policy 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.
|
||||
|
||||
This document defines the confidence lattice, evidence types, mitigation scoring, and policy gates used to turn static/runtime signals into reproducible reachability decisions and VEX statuses.
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
Classic “reachable: true/false” answers are too brittle. Stella Ops models reachability as an **ordered lattice** with explicit states and scores. Each analyzer/runtime probe emits `Evidence` documents; mitigations add `Mitigation` entries. The lattice engine joins both inputs into a `ReachDecision`:
|
||||
<!-- TODO: Review for separate approval - updated lattice overview -->
|
||||
**Key differentiator:** Unlike simplistic yes/no reachability approaches, the Stella Ops lattice model explicitly handles an **"Unknown"** (under_investigation) state, ensuring incomplete data doesn't lead to false safety. Every VEX decision is evidence-linked with proof pointers to the underlying reachability evidence.
|
||||
|
||||
Classic "reachable: true/false" answers are too brittle. Stella Ops models reachability as an **ordered lattice** with explicit states and scores. Each analyzer/runtime probe emits `Evidence` documents; mitigations add `Mitigation` entries. The lattice engine joins both inputs into a `ReachDecision`:
|
||||
|
||||
```
|
||||
UNOBSERVED (0–9)
|
||||
@@ -75,10 +80,10 @@ public sealed record ReachDecision(
|
||||
|
||||
| Evidence class | Base score contribution |
|
||||
|--------------------------|-------------------------|
|
||||
| Static path (call graph) | ≥ 30 |
|
||||
| Runtime hit | ≥ 60 |
|
||||
| User-tainted flow | ≥ 80 |
|
||||
| “Constraints removed” | = 100 |
|
||||
| Static path (call graph) | ≥ 30 |
|
||||
| Runtime hit | ≥ 60 |
|
||||
| User-tainted flow | ≥ 80 |
|
||||
| "Constraints removed" | = 100 |
|
||||
| Lockfile-only evidence | 10 (if no other signals)|
|
||||
|
||||
Mitigations subtract up to 40 points (configurable):
|
||||
@@ -106,11 +111,11 @@ Default thresholds (edit in `reachability.policy.yml`):
|
||||
|
||||
VEX mapping:
|
||||
|
||||
* **not_affected**: score ≤ 25 or mitigations dominate (score reduced below threshold).
|
||||
* **affected**: score ≥ 60 (dynamic evidence without sufficient mitigation).
|
||||
* **under_investigation**: everything between.
|
||||
* **not_affected**: score ≤ 25 or mitigations dominate (score reduced below threshold).
|
||||
* **affected**: score ≥ 60 (dynamic evidence without sufficient mitigation).
|
||||
* **under_investigation**: everything between. **This explicit "Unknown" state is a key differentiator**—incomplete data never leads to false safety.
|
||||
|
||||
Each decision records `reachability.policy.version`, analyzer versions, policy hash, and config snapshot so downstream verifiers can replay the exact logic.
|
||||
Each decision records `reachability.policy.version`, analyzer versions, policy hash, and config snapshot so downstream verifiers can replay the exact logic. All decisions are sealed in Decision Capsules for audit-grade reproducibility.
|
||||
|
||||
---
|
||||
|
||||
@@ -125,7 +130,7 @@ Each decision records `reachability.policy.version`, analyzer versions, policy h
|
||||
| Mitigations | WAF connectors, patch diff, kill switches | `MitigationKind.*` via `Mitigation` records |
|
||||
| Trust | Vendor VEX statements, manual overrides | `VendorVexNotAffected/Affected`, `ManualOverride` |
|
||||
|
||||
Each evidence object **must** log `Source`, timestamps, and references (function IDs, config hashes) so auditors can trace it in the event graph.
|
||||
Each evidence object **must** log `Source`, timestamps, and references (function IDs, config hashes) so auditors can trace it in the event graph. This enables **evidence-linked VEX decisions** where every assertion includes pointers to the underlying proof.
|
||||
|
||||
---
|
||||
|
||||
@@ -185,7 +190,20 @@ See `src/Scanner/StellaOps.Scanner.WebService/Reachability/Runtime/DotNetRuntime
|
||||
|
||||
---
|
||||
|
||||
## 9. Roadmap
|
||||
## 9. Hybrid Reachability
|
||||
|
||||
<!-- TODO: Review for separate approval - added hybrid reachability section -->
|
||||
Stella Ops combines **static call-graph analysis** with **runtime process tracing** for true hybrid reachability:
|
||||
|
||||
- **Static analysis** provides call-graph edges from IL/bytecode analysis, framework routing models, and entry-point proximity calculations.
|
||||
- **Runtime analysis** provides observed method hits, stack samples, and HTTP route hits from live or shadow traffic.
|
||||
- **Hybrid reconciliation** merges both signal types, with each edge type attestable via DSSE. See `docs/reachability/hybrid-attestation.md` for the attestation model.
|
||||
|
||||
This hybrid approach ensures that both build-time and run-time context contribute to the same verdict, avoiding the blind spots of purely static or purely runtime analysis.
|
||||
|
||||
---
|
||||
|
||||
## 10. Roadmap
|
||||
|
||||
| Task | Description |
|
||||
|------|-------------|
|
||||
@@ -195,4 +213,3 @@ See `src/Scanner/StellaOps.Scanner.WebService/Reachability/Runtime/DotNetRuntime
|
||||
| `REACH-POLICY-402-026` | Expose reachability gates in Policy DSL & CLI (edit/lint/test). |
|
||||
|
||||
Keep this doc updated as the lattice evolves or new signals/mitigations are added.
|
||||
*** End Patch
|
||||
|
||||
@@ -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