Add Decision Capsules, hybrid reachability, and evidence-linked VEX docs

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.
2025-12-11 14:15:07 +02:00
parent 0987cd6ac8
commit 1995883476
10 changed files with 982 additions and 65 deletions
--- a/docs/marketing/decision-capsules.md
+++ b/docs/marketing/decision-capsules.md
@@ -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
--- a/docs/marketing/evidence-linked-vex.md
+++ b/docs/marketing/evidence-linked-vex.md
@@ -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
--- a/docs/marketing/hybrid-reachability.md
+++ b/docs/marketing/hybrid-reachability.md
@@ -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