git.stella-ops.org/docs/marketing/decision-capsules.md

# 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