git.stella-ops.org/docs/releases/v2.5.0-release-notes.md

# StellaOps v2.5.0 Release Notes

**Release Date:** 2025-12-20  
**Epic:** 3500 - Score Proofs & Reachability Analysis

---

## Highlights

This release introduces three major capabilities that transform vulnerability management from alert enumeration to actionable intelligence:

🔐 **Score Proofs** - Cryptographic attestations proving vulnerability scores are deterministic and reproducible

🎯 **Reachability Analysis** - Static analysis determining whether vulnerable code is actually reachable

📋 **Unknowns Management** - Systematic tracking of components that cannot be fully analyzed

---

## New Features

### Score Proofs

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

**Key Capabilities:**
- **Deterministic Scoring**: Same inputs always produce identical outputs
- **DSSE Attestations**: Cryptographically signed proof bundles
- **Merkle Tree Verification**: Individual finding verification without full replay
- **Audit Trail**: Complete provenance from inputs to findings
- **Optional Transparency Logging**: Integration with Sigstore Rekor

**CLI Commands:**
```bash
# Generate scan with proof
stella scan --sbom ./sbom.json --generate-proof

# Verify a proof
stella proof verify ./proof.dsse

# Replay a scan
stella score replay ./bundle/ --verify

# Inspect proof contents
stella proof inspect ./proof.dsse
```

**API Endpoints:**
- `GET /api/v1/scans/{id}/proof` - Retrieve proof bundle
- `POST /api/v1/proofs/verify` - Verify a proof
- `POST /api/v1/scans/{id}/replay` - Replay a scan

### Reachability Analysis

Reachability Analysis determines whether vulnerable code paths can actually be executed in your application.

**Key Capabilities:**
- **Call Graph Generation**: Static analysis of source code
- **BFS Path Tracing**: Efficient reachability computation
- **Confidence Scoring**: Graduated verdict levels
- **Path Explanation**: Exact call chain from entry to vulnerability
- **Multi-Language Support**: Java, JavaScript, Python, Go, C#

**Reachability Verdicts:**
| Verdict | Meaning | Recommended Action |
|---------|---------|-------------------|
| `REACHABLE_STATIC` | Code path exists | Prioritize fix |
| `POSSIBLY_REACHABLE` | May be reachable | Review manually |
| `NOT_REACHABLE` | No execution path | Lower priority |
| `UNKNOWN` | Cannot determine | Manual analysis |

**CLI Commands:**
```bash
# Generate call graph
stella scan graph ./src --output ./callgraph.json

# Scan with reachability
stella scan --sbom ./sbom.json --call-graph ./callgraph.json --reachability

# Query reachability results
stella reachability query --filter "verdict=REACHABLE_STATIC"

# Explain a path
stella reachability explain --cve CVE-2024-1234
```

**API Endpoints:**
- `POST /api/v1/callgraphs` - Upload call graph
- `GET /api/v1/scans/{id}/reachability` - Get reachability results
- `GET /api/v1/reachability/{id}/explain` - Get path explanation

### Unknowns Queue Management

The Unknowns Queue systematically tracks components that cannot be fully analyzed.

**Key Capabilities:**
- **Categorized Tracking**: Package, vulnerability, and format unknowns
- **Triage Workflows**: PENDING → TRIAGING → RESOLVED states
- **Bulk Operations**: Efficient handling of large backlogs
- **Pattern Matching**: Auto-classify internal packages
- **Metrics & Alerting**: Monitor coverage gaps

**CLI Commands:**
```bash
# List unknowns
stella unknowns list --state pending

# View details
stella unknowns show <unknown-id>

# Resolve an unknown
stella unknowns resolve <id> --resolution internal_package

# Bulk operations
stella unknowns bulk-resolve --filter "ecosystem=internal"

# Statistics
stella unknowns stats --by-reason
```

**API Endpoints:**
- `GET /api/v1/unknowns` - List unknowns
- `GET /api/v1/unknowns/{id}` - Get unknown details
- `POST /api/v1/unknowns/{id}/resolve` - Resolve unknown
- `GET /api/v1/unknowns/stats` - Queue statistics

---

## Breaking Changes

### API Changes

1. **Scan Response Schema Updated**
   - New `proof` field when `generateProof=true`
   - New `reachability` field when reachability enabled
   - `findings` now includes `reachabilityVerdict` property

2. **Finding Schema Enhanced**
   ```json
   {
     "id": "F-001",
     "cve": "CVE-2024-1234",
     "severity": "HIGH",
     "reachabilityVerdict": "REACHABLE_STATIC",
     "reachabilityConfidence": 0.95,
     "proofDigest": "sha256:abc..."
   }
   ```

### Configuration Changes

1. **New Configuration Section**
   ```json
   {
     "ScoreProofs": {
       "Enabled": true,
       "SigningKeyId": "default",
       "TransparencyLogEnabled": false
     },
     "Reachability": {
       "Enabled": true,
       "MaxDepth": 50,
       "CacheEnabled": true
     },
     "Unknowns": {
       "AutoResolveInternal": false,
       "InternalPatterns": []
     }
   }
   ```

### Deprecated Features

- `stella scan --legacy-output` - Use standard output format
- API v0 endpoints - Migrate to v1

---

## Known Limitations

1. **Reachability Languages**
   - C/C++ support is limited (best-effort static analysis)
   - Reflection/dynamic dispatch may cause under-reporting
   - Very large codebases (>1M nodes) may require depth limiting

2. **Score Proofs**
   - HSM signing requires compatible hardware
   - Post-quantum algorithms not yet available (roadmap)
   - Rekor integration requires network for transparency logging

3. **Unknowns**
   - Historical unknowns from previous versions not auto-migrated
   - Pattern matching is case-sensitive

---

## Upgrade Instructions

### Prerequisites

- StellaOps v2.4.x or later
- .NET 10 runtime
- PostgreSQL 15+ (for new schema features)

### Database Migration

```bash
# Backup database first
pg_dump stellaops > backup_pre_v2.5.sql

# Run migrations
stella db migrate --version 2.5.0

# Verify migration
stella db verify
```

### Configuration Migration

```bash
# Export current config
stella config export > config_backup.json

# Upgrade configuration schema
stella config upgrade --to 2.5.0

# Review and adjust new settings
stella config validate
```

### Post-Upgrade Verification

```bash
# Verify installation
stella version --all

# Test core functionality
stella diagnose --quick

# Run smoke tests
stella test smoke
```

---

## Performance Benchmarks

Measured on reference hardware (8 cores, 32GB RAM):

| Operation | v2.4.0 | v2.5.0 | Change |
|-----------|--------|--------|--------|
| Base scan | 100ms | 105ms | +5% |
| Scan + Proof | N/A | 115ms | New |
| Scan + Reachability | N/A | 250ms | New |
| Scan + Both | N/A | 280ms | New |
| Call graph (10K nodes) | N/A | 3.2s | New |
| Call graph (100K nodes) | N/A | 45s | New |

Memory overhead:
- Score Proofs: +50MB peak
- Reachability: +200MB peak (varies with graph size)

---

## Documentation

New and updated documentation:

**Training Materials:**
- [Score Proofs Concept Guide](docs/training/score-proofs-concept-guide.md)
- [Reachability Analysis Guide](docs/training/reachability-concept-guide.md)
- [Unknowns Management Guide](docs/training/unknowns-management-guide.md)
- [FAQ](docs/training/faq.md)
- [Troubleshooting Guide](docs/training/troubleshooting-guide.md)

**Operations Runbooks:**
- [Score Replay Runbook](docs/operations/score-replay-runbook.md)
- [Proof Verification Runbook](docs/operations/proof-verification-runbook.md)
- [Reachability Runbook](docs/operations/reachability-runbook.md)
- [Unknowns Queue Runbook](docs/operations/unknowns-queue-runbook.md)
- [Air-Gap Operations Runbook](docs/operations/airgap-operations-runbook.md)

**CLI Reference:**
- [Score Proofs CLI](docs/cli/score-proofs-cli-reference.md)
- [Reachability CLI](docs/cli/reachability-cli-reference.md)
- [Unknowns CLI](docs/cli/unknowns-cli-reference.md)

**API Reference:**
- [Score Proofs API](docs/api/score-proofs-reachability-api-reference.md)

---

## Security Considerations

### Signing Keys

- Score Proofs require a configured signing key
- Support for HSM-backed keys (PKCS#11)
- Key rotation procedures documented in operations runbooks

### Trust Model

- Proofs are only as trustworthy as the signing key
- Certificate chain validation supported
- Optional transparency logging for public auditability

### Air-Gap Support

- All features work fully offline
- Offline kit includes feeds, trust bundles, and signing keys
- See [Air-Gap Operations](docs/operations/airgap-operations-runbook.md)

---

## Contributors

This release was developed as part of Epic 3500:

- Sprint 3500.0001.0001 - Determinism Foundations
- Sprint 3500.0002.0001 - Proof Chain
- Sprint 3500.0003.0001 - Reachability MVP
- Sprint 3500.0004.0001 - CLI Integration
- Sprint 3500.0004.0002 - UI Components
- Sprint 3500.0004.0003 - Integration Tests
- Sprint 3500.0004.0004 - Documentation & Handoff

---

## Feedback

We welcome feedback on these new features:

- GitHub Issues: [StellaOps Issues](https://github.com/stellaops/stellaops/issues)
- Documentation: [docs/](docs/)
- Security: security@stellaops.example.com

---

## Next Release Preview

Planned for v2.6.0:
- Post-quantum cryptography support (ML-DSA)
- Enhanced dynamic dispatch handling
- Reachability caching improvements
- UI dashboard for unknowns management