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:

# 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:

# 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:

# 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

   {
     "id": "F-001",
     "cve": "CVE-2024-1234",
     "severity": "HIGH",
     "reachabilityVerdict": "REACHABLE_STATIC",
     "reachabilityConfidence": 0.95,
     "proofDigest": "sha256:abc..."
   }
   

Configuration Changes

1. New Configuration Section

   {
     "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

# 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

# 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

# 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
• Reachability Analysis Guide
• Unknowns Management Guide
• FAQ
• Troubleshooting Guide

Operations Runbooks:

• Score Replay Runbook
• Proof Verification Runbook
• Reachability Runbook
• Unknowns Queue Runbook
• Air-Gap Operations Runbook

CLI Reference:

• Score Proofs CLI
• Reachability CLI
• Unknowns CLI

API Reference:

• Score Proofs API

---

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

---

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
• Documentation: 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