# StellaOps Release Notes: Score Proofs & Reachability

**Epic:** 3500 - Score Proofs and Deterministic Replay  
**Release Version:** 1.0.0  
**Release Date:** 2025-12-20

---

## Overview

This release introduces **Score Proofs** and **Reachability Analysis**, two transformative features that bring cryptographic verifiability and intelligent prioritization to vulnerability scanning. Together, these features enable organizations to prove compliance, reduce alert fatigue, and focus on vulnerabilities that actually matter.

---

## Feature Highlights

### Score Proofs: Verifiable Vulnerability Scores

Score Proofs provide cryptographic evidence that vulnerability scores can be independently verified and reproduced.

**Key Capabilities:**

| Feature | Description |
|---------|-------------|
| **Scan Manifests** | Content-addressed records of all scan inputs (SBOM, advisories, VEX, call graphs) |
| **Proof Bundles** | DSSE-signed bundles with attestations for audit compliance |
| **Deterministic Replay** | Re-execute scans with original inputs to verify results |
| **Proof Ledger** | Append-only chain for tamper-evident audit trails |
| **Transparency Integration** | Optional anchoring to Sigstore Rekor for public verifiability |

**Use Cases:**
- Audit compliance (SOC 2, PCI DSS, HIPAA)
- Dispute resolution with vendors
- Regulatory evidence collection
- CI/CD pipeline traceability

### Reachability Analysis: Focus on What Matters

Reachability Analysis determines whether vulnerable code is actually invoked during program execution.

**Key Capabilities:**

| Feature | Description |
|---------|-------------|
| **Call Graph Integration** | Upload and analyze application call graphs |
| **BFS Path Finding** | Efficient breadth-first search from entrypoints to vulnerabilities |
| **Confidence Scoring** | Quantified certainty (0-1) based on path quality |
| **Explain Queries** | Detailed explanations of why code is (or isn't) reachable |
| **Runtime Evidence** | Optional runtime traces for proven reachability |

**Reachability Statuses:**

| Status | Meaning | Typical Action |
|--------|---------|---------------|
| `UNREACHABLE` | No path exists | Safe to deprioritize |
| `POSSIBLY_REACHABLE` | Path with heuristic edges | Review |
| `REACHABLE_STATIC` | Statically proven path | Prioritize fix |
| `REACHABLE_PROVEN` | Runtime confirmed | Fix immediately |
| `UNKNOWN` | Insufficient data | Improve call graph |

**Impact:** Typically reduces actionable vulnerabilities by 80-90%.

### Unknowns Registry: Track Your Blind Spots

The Unknowns Registry tracks components that cannot be fully analyzed.

**Key Capabilities:**

| Feature | Description |
|---------|-------------|
| **2-Factor Ranking** | Priority based on vulnerability potential × impact potential |
| **Category Classification** | unmapped_purl, checksum_miss, language_gap, etc. |
| **Triage Workflows** | Escalate, resolve, or suppress with documentation |
| **Bulk Operations** | Process multiple unknowns efficiently |

---

## New CLI Commands

### Score Commands

```bash
stella score compute    # Compute vulnerability scores
stella score replay     # Replay scan with original inputs
stella score show       # Display score details
stella score diff       # Compare scores between scans
stella score manifest   # Show scan manifest
stella score inputs     # List manifest inputs
```

### Proof Commands

```bash
stella proof verify     # Verify proof integrity
stella proof download   # Download proof bundle
stella proof export     # Export proof bundle
stella proof inspect    # Inspect proof contents
stella proof status     # Check proof status
stella proof list       # List proofs for workspace
stella proof anchor     # Anchor proof to transparency log
```

### Reachability Commands

```bash
stella reachability compute     # Trigger reachability analysis
stella reachability findings    # List reachability findings
stella reachability explain     # Explain specific verdict
stella reachability explain-all # Export all explanations
stella reachability summary     # Show summary statistics
```

### Call Graph Commands

```bash
stella scan graph upload      # Upload call graph
stella scan graph summary     # Show call graph summary
stella scan graph entrypoints # List detected entrypoints
stella scan graph validate    # Validate call graph
stella scan graph export      # Export call graph
stella scan graph visualize   # Generate visualization
```

### Unknowns Commands

```bash
stella unknowns list        # List unknowns
stella unknowns show        # Show unknown details
stella unknowns summary     # Show summary statistics
stella unknowns escalate    # Escalate for review
stella unknowns resolve     # Mark as resolved
stella unknowns suppress    # Suppress with justification
stella unknowns bulk-triage # Bulk triage operations
stella unknowns export      # Export unknowns data
```

---

## New API Endpoints

### Score Proofs API

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/scans/{scanId}/score/compute` | Compute scores |
| POST | `/api/v1/scans/{scanId}/score/replay` | Replay computation |
| GET | `/api/v1/scans/{scanId}/score/manifest` | Get scan manifest |
| GET | `/api/v1/scans/{scanId}/proofs` | List proofs |
| POST | `/api/v1/scans/{scanId}/proofs/verify` | Verify proof |
| GET | `/api/v1/scans/{scanId}/proofs/download` | Download bundle |

### Reachability API

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/scans/{scanId}/reachability/compute` | Trigger analysis |
| GET | `/api/v1/scans/{scanId}/reachability/findings` | Get findings |
| GET | `/api/v1/scans/{scanId}/reachability/explain` | Explain verdict |
| POST | `/api/v1/scans/{scanId}/callgraph` | Upload call graph |
| GET | `/api/v1/scans/{scanId}/callgraph/summary` | Graph summary |
| GET | `/api/v1/scans/{scanId}/callgraph/entrypoints` | List entrypoints |

### Unknowns API

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/unknowns` | List unknowns |
| GET | `/api/v1/unknowns/{id}` | Get unknown details |
| POST | `/api/v1/unknowns/{id}/escalate` | Escalate unknown |
| POST | `/api/v1/unknowns/{id}/resolve` | Resolve unknown |
| POST | `/api/v1/unknowns/{id}/suppress` | Suppress unknown |
| POST | `/api/v1/unknowns/bulk` | Bulk operations |

---

## Configuration Changes

### New Settings

```json
{
  "scanner": {
    "proofs": {
      "enabled": true,
      "mode": "full",
      "transparency": "rekor",
      "ledger": {
        "maxChainDepth": 10000,
        "pruneAfterDays": 365
      }
    },
    "reachability": {
      "enabled": true,
      "maxDepth": 10,
      "indirectResolution": "conservative",
      "timeout": "300s",
      "parallelBfs": true
    },
    "unknowns": {
      "enabled": true,
      "autoSuppress": false,
      "triageSla": {
        "critical": "24h",
        "high": "72h",
        "medium": "168h"
      }
    }
  }
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `STELLA_PROOF_MODE` | Proof generation mode | `full` |
| `STELLA_REACHABILITY_ENABLED` | Enable reachability | `true` |
| `STELLA_REACHABILITY_MAX_DEPTH` | Max BFS depth | `10` |
| `STELLA_UNKNOWNS_AUTO_SUPPRESS` | Auto-suppress low priority | `false` |

---

## Database Changes

### New Tables

| Table | Purpose |
|-------|---------|
| `scan_manifests` | Stores scan manifest JSON |
| `proof_ledger` | Append-only proof chain |
| `proof_attestations` | DSSE attestation storage |
| `call_graphs` | Call graph metadata |
| `call_graph_nodes` | Graph nodes (partitioned) |
| `call_graph_edges` | Graph edges (partitioned) |
| `reachability_results` | Computed reachability |
| `reachability_paths` | Path details |
| `unknowns_registry` | Unknown components |
| `unknowns_history` | Resolution history |

### Migration Notes

- Run migrations before upgrading: `stella db migrate`
- New tables use time-based partitioning
- Estimated migration time: 5-10 minutes (varies by data volume)

---

## Breaking Changes

### None

This release has no breaking changes. All existing APIs, configurations, and workflows continue to work as before.

---

## Known Limitations

### Score Proofs

| Limitation | Workaround |
|------------|------------|
| Large SBOM export may timeout | Use streaming export or exclude inputs |
| Transparency log requires network | Use offline mode with local ledger |

### Reachability

| Limitation | Workaround |
|------------|------------|
| Reflection detection is heuristic | Add reflection hints configuration |
| Very large graphs (>1M nodes) may timeout | Partition analysis by artifact |
| Some languages have limited call graph support | Supplement with runtime traces |

### Unknowns

| Limitation | Workaround |
|------------|------------|
| Auto-scoring may not reflect context | Manual escalation with severity override |
| Bulk triage limited to 1000 items | Batch operations |

---

## Upgrade Instructions

### From Previous Version

1. **Backup database**
   ```bash
   stella db backup --output backup-$(date +%Y%m%d).sql
   ```

2. **Run migrations**
   ```bash
   stella db migrate
   ```

3. **Update configuration** (optional)
   ```bash
   stella config set scanner.proofs.enabled true
   stella config set scanner.reachability.enabled true
   ```

4. **Verify installation**
   ```bash
   stella status
   stella scan run --image test-image:latest --dry-run
   ```

### Fresh Installation

Follow the [Installation Guide](../21_INSTALL_GUIDE.md).

---

## Performance Expectations

### Score Proofs

| Operation | Typical Duration |
|-----------|------------------|
| Manifest generation | <1 second |
| Proof signing | <2 seconds |
| Bundle export (no inputs) | <5 seconds |
| Bundle export (with inputs) | 10-60 seconds |
| Replay computation | Same as original scan |

### Reachability

| Graph Size | Typical Duration |
|------------|------------------|
| <10K nodes | <30 seconds |
| 10K-100K nodes | 30s - 3 minutes |
| 100K-1M nodes | 3-15 minutes |
| >1M nodes | 15+ minutes |

### Storage

| Component | Typical Size |
|-----------|--------------|
| Scan manifest | 50-100 KB |
| Proof bundle (no inputs) | 100-200 KB |
| Proof bundle (with inputs) | 10-500 MB |
| Call graph (per 10K nodes) | ~5 MB |

---

## Documentation

### New Documentation

- [Score Proofs Concept Guide](../training/score-proofs-concept-guide.md)
- [Reachability Concept Guide](../training/reachability-concept-guide.md)
- [Unknowns Management Guide](../training/unknowns-management-guide.md)
- [Score Proofs CLI Reference](../cli/score-proofs-cli-reference.md)
- [Reachability CLI Reference](../cli/reachability-cli-reference.md)
- [Unknowns CLI Reference](../cli/unknowns-cli-reference.md)
- [API Reference](../api/score-proofs-reachability-api-reference.md)
- [Score Proofs Runbook](../operations/score-proofs-runbook.md)
- [Reachability Runbook](../operations/reachability-runbook.md)
- [Unknowns Queue Runbook](../operations/unknowns-queue-runbook.md)
- [Air-Gap Runbook](../airgap/score-proofs-reachability-airgap-runbook.md)
- [FAQ](../training/faq.md)
- [Troubleshooting Guide](../training/troubleshooting-guide.md)

### Updated Documentation

- [High-Level Architecture](../07_HIGH_LEVEL_ARCHITECTURE.md) - Added sections 4A, 4B, 4C

---

## Support

For issues or questions:
- Documentation: `docs/` directory
- Issue Tracker: Internal issue tracker
- Emergency: On-call security team

---

**Release Manager:** Agent  
**Sprint:** 3500.0004.0004  
**Last Updated:** 2025-12-20