stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity

Add Decision Capsules, hybrid reachability, and evidence-linked VEX docs
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
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
2025-12-11 14:15:07 +02:00
parent 0987cd6ac8
commit 1995883476
10 changed files with 982 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/03_VISION.md
View File

@@ -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.

53
docs/README.md
View File

@@ -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

36
docs/key-features.md
View File

@@ -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
View 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
View 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
View 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
View File

@@ -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.

41
docs/reachability/hybrid-attestation.md
View File

@@ -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.

43
docs/reachability/lattice.md
View File

@@ -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

200
docs/vex/consensus-overview.md
View File

@@ -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