git.stella-ops.org/docs/releases/release-notes-score-proofs-reachability.md

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

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

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

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

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

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

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

   stella db backup --output backup-$(date +%Y%m%d).sql
   

2. Run migrations

   stella db migrate
   

3. Update configuration (optional)

   stella config set scanner.proofs.enabled true
   stella config set scanner.reachability.enabled true
   

4. Verify installation

   stella status
   stella scan run --image test-image:latest --dry-run
   

Fresh Installation

Follow the Installation Guide.

---

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
• Reachability Concept Guide
• Unknowns Management Guide
• Score Proofs CLI Reference
• Reachability CLI Reference
• Unknowns CLI Reference
• API Reference
• Score Proofs Runbook
• Reachability Runbook
• Unknowns Queue Runbook
• Air-Gap Runbook
• FAQ
• Troubleshooting Guide

Updated Documentation

• High-Level Architecture - 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