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
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
|
||||
Reference in New Issue
Block a user