git.stella-ops.org/docs/training/epic-3500-faq.md

Epic 3500: Score Proofs & Reachability FAQ

Sprint: SPRINT_3500_0004_0004
Last Updated: 2025-12-20

This FAQ covers the most common questions about Score Proofs, Reachability Analysis, and Unknowns Management features introduced in Epic 3500.

---

Table of Contents

1. General Questions
2. Score Proofs
3. Reachability Analysis
4. Unknowns Queue
5. Integration & Deployment
6. Performance
7. Troubleshooting

---

General Questions

Q: What is Epic 3500?

A: Epic 3500 introduces three major capabilities to StellaOps:

1. Score Proofs: Cryptographically verifiable attestations proving that vulnerability scores are deterministic and reproducible
2. Reachability Analysis: Static analysis determining whether vulnerable code paths are actually reachable from your application
3. Unknowns Management: Tracking and triaging components that cannot be fully analyzed

Q: Do I need all three features?

A: The features work independently but provide the most value together:

• Score Proofs alone: Useful for compliance and audit trails
• Reachability alone: Useful for prioritizing remediation
• Together: Full attack surface context with cryptographic proof

Q: What's the minimum version required?

A: Epic 3500 features require:

• StellaOps Scanner v2.5.0+
• StellaOps CLI v2.5.0+
• .NET 10 runtime (for self-hosted deployments)

Q: Are these features available in air-gapped environments?

A: Yes. All Epic 3500 features support air-gap operation:

• Score Proofs can be generated and verified offline
• Reachability analysis requires no network connectivity
• Unknowns data persists locally

See the Air-Gap Operations Guide for details.

---

Score Proofs

Q: What exactly is a Score Proof?

A: A Score Proof is a DSSE-signed attestation bundle containing:

Score Proof Bundle
├── scan_manifest.json      # Content-addressed inputs (SBOM, feeds)
├── proof.dsse              # DSSE-signed attestation
├── merkle_proof.json       # Merkle tree proof for individual findings
└── replay_instructions.md  # How to reproduce the scan

The proof guarantees that given the same inputs, anyone can reproduce the exact same vulnerability scores.

Q: Why do I need Score Proofs?

A: Score Proofs solve several problems:

Problem	Solution
"Scanner gave different results yesterday"	Manifest captures exact inputs
"How do I prove to auditors this was the score?"	DSSE signatures provide non-repudiation
"Can I trust this third-party scan?"	Independent verification possible
"Which advisory version was used?"	All feed digests recorded

Q: How do I generate a Score Proof?

A: Enable proofs during scanning:

# CLI
stella scan --sbom ./sbom.json --generate-proof --output ./scan-with-proof/

# API
POST /api/v1/scans
{
  "sbomDigest": "sha256:abc...",
  "options": {
    "generateProof": true
  }
}

Q: How do I verify a Score Proof?

A: Use the verify command:

# Verify signature and Merkle root
stella proof verify ./scan-with-proof/proof.dsse

# Full replay verification (re-runs scan)
stella score replay ./scan-with-proof/ --verify

Q: Can I verify proofs without network access?

A: Yes. Verification only requires:

• The proof bundle
• A trusted public key
• Optionally, the original inputs (for replay)

See: Proof Verification Runbook

Q: What signing algorithms are supported?

A: Current support includes:

Algorithm	Status	Use Case
ECDSA P-256	✅ Supported	Default, widely compatible
ECDSA P-384	✅ Supported	Higher security
RSA-2048	✅ Supported	Legacy compatibility
Ed25519	✅ Supported	Modern, fast
PQC (ML-DSA)	🔜 Roadmap	Post-quantum ready

Q: How long are proofs valid?

A: Proofs don't expire, but their trust depends on:

• Key validity at signing time
• Certificate chain validity (if using X.509)
• Rekor timestamp (if transparency log enabled)

Best practice: Archive proofs with their verification materials.

Q: What's the overhead of generating proofs?

A: Typical overhead:

• Time: +5-15% scan duration
• Storage: +10-20KB per scan (proof bundle)
• CPU: Minimal (signing is fast)

For detailed benchmarks, see Performance Workbook.

---

Reachability Analysis

Q: What is reachability analysis?

A: Reachability analysis answers: "Can vulnerable code actually be executed?"

It analyzes your application's call graph to determine if vulnerable functions in dependencies are reachable from your entry points.

Q: What are the reachability verdicts?

A:

Verdict	Meaning	Action
REACHABLE_STATIC	Vulnerable code is on an executable path	Prioritize fix
POSSIBLY_REACHABLE	May be reachable under certain conditions	Review
NOT_REACHABLE	No path from entry points to vulnerable code	Lower priority
UNKNOWN	Analysis couldn't determine reachability	Manual review

Q: What's the difference from EPSS?

A:

Metric	What It Measures	Data Source
EPSS	Probability of exploitation in the wild	Threat intelligence
Reachability	Whether your code can trigger the vuln	Your application's call graph

They're complementary: EPSS tells you "how likely is exploitation globally", reachability tells you "can it affect me specifically".

Q: How do I enable reachability analysis?

A:

# CLI - analyze SBOM with reachability
stella scan --sbom ./sbom.json --reachability

# With call graph input
stella scan --sbom ./sbom.json --call-graph ./callgraph.json

# Generate call graph first
stella scan graph ./src --output ./callgraph.json

Q: What languages are supported for call graph analysis?

A:

Language	Support Level	Notes
Java	Full	Requires bytecode
JavaScript/TS	Full	Requires source
Python	Full	Requires source
Go	Full	Requires source or binary
C#	Partial	Basic support
C/C++	Limited	Best-effort

Q: What if my language isn't supported?

A: You can:

1. Provide a custom call graph in standard format
2. Use UNKNOWN verdict handling
3. Combine with other prioritization signals (EPSS, VEX)

Q: How accurate is reachability analysis?

A: Accuracy depends on several factors:

Factor	Impact
Call graph completeness	Higher completeness = better accuracy
Dynamic dispatch	May cause under-reporting (conservative)
Reflection/eval	May cause under-reporting
Language support	Full support = more accurate

StellaOps errs on the side of caution: if uncertain, it reports POSSIBLY_REACHABLE rather than false negatives.

Q: What's the performance impact?

A: Reachability analysis adds:

• Call graph generation: 10-60 seconds depending on codebase size
• Reachability computation: 1-10 seconds per scan
• Memory: Call graph size varies (typically 10-100MB)

Q: Can I cache call graphs?

A: Yes. If your code hasn't changed, reuse the call graph:

# Cache the call graph
stella scan graph ./src --output ./callgraph.json

# Reuse in subsequent scans
stella scan --sbom ./sbom.json --call-graph ./callgraph.json

---

Unknowns Queue

Q: What is the unknowns queue?

A: The unknowns queue tracks components that couldn't be fully analyzed:

• Packages without advisory mappings
• Unrecognized file formats
• Resolution failures
• Unsupported ecosystems

Q: Why should I care about unknowns?

A: Unknowns represent blind spots:

❌ 5% unknown = 5% of your attack surface is invisible

Unmanaged unknowns can hide critical vulnerabilities.

Q: How do I view unknowns?

A:

# List pending unknowns
stella unknowns list

# Get statistics
stella unknowns stats

# Export for analysis
stella unknowns list --format csv > unknowns.csv

Q: How do I resolve unknowns?

A: Common resolution paths:

Unknown Type	Resolution
Internal package	Mark as internal_package
Missing mapping	Submit CPE/PURL mapping
Feed delay	Update feeds, reprocess
Unsupported format	Convert to supported format

# Resolve as internal package
stella unknowns resolve <id> --resolution internal_package

# After feed update, reprocess
stella feeds update --all
stella unknowns reprocess

Q: What's a good unknowns rate?

A: Target metrics:

Metric	Good	Warning	Critical
Unknown package %	< 5%	5-10%	> 10%
Pending queue depth	< 50	50-100	> 100
Avg resolution time	< 7d	7-14d	> 14d

Q: Can I automate unknown handling?

A: Yes, using patterns:

# config/unknowns.yaml
internalPatterns:
  - "@mycompany/*"
  - "internal-*"
autoResolution:
  - match: "reason = NO_ADVISORY_MATCH AND ecosystem = internal"
    resolution: internal_package

---

Integration & Deployment

Q: How do I integrate with CI/CD?

A: Example GitHub Actions workflow:

- name: Scan with proofs and reachability
  run: |
    stella scan \
      --sbom ./sbom.json \
      --generate-proof \
      --reachability \
      --output ./results/
      
- name: Fail on reachable criticals
  run: |
    REACHABLE=$(stella query --filter "reachability=REACHABLE_STATIC AND severity=CRITICAL" --count)
    if [ "$REACHABLE" -gt 0 ]; then
      exit 1
    fi

Q: Can I use these features in GitLab CI?

A: Yes, same commands work in any CI system. See CI Integration Guide.

Q: What API endpoints are available?

A: Key endpoints:

Feature	Endpoint	Method
Generate proof	/api/v1/scans/{id}/proof	GET
Verify proof	/api/v1/proofs/verify	POST
Reachability	/api/v1/scans/{id}/reachability	GET
Unknowns	/api/v1/unknowns	GET/POST/DELETE

Full API reference: API Documentation

Q: How do I configure retention?

A: Configure in appsettings.json:

{
  "Retention": {
    "Proofs": {
      "DefaultDays": 365,
      "MaxDays": 1825
    },
    "Reachability": {
      "CacheHours": 24
    },
    "Unknowns": {
      "ArchiveAfterDays": 90
    }
  }
}

---

Performance

Q: What's the performance impact of enabling all features?

A: Typical combined overhead:

Feature	Time Overhead	Storage Overhead
Base scan	Baseline	Baseline
+ Proof generation	+5-15%	+20KB
+ Reachability	+50-200%	+50KB
+ All features	+60-220%	+70KB

Q: How do I optimize for large codebases?

A:

1. Cache call graphs for incremental scans
2. Use parallel processing for multi-repo scans
3. Limit reachability depth for very large graphs
4. Use deterministic mode only when needed

# Limit BFS depth for large graphs
stella scan --reachability --reachability-depth 10

Q: Are there size limits?

A:

Resource	Default Limit	Configurable
SBOM size	50MB	Yes
Call graph nodes	1M	Yes
Proof bundle size	10MB	Yes
Unknowns queue	10K items	Yes

---

Troubleshooting

Q: Score replay gives different results

A: Check:

1. Feed versions match (stella feeds status)
2. Algorithm version matches
3. No clock skew (UTC timestamps)
4. Same configuration settings

# Verify manifest
stella proof verify --manifest-only ./proof.dsse

Q: Reachability shows everything as UNKNOWN

A: This usually means:

1. Call graph wasn't generated
2. Language not supported
3. Source code not available

# Check call graph status
stella scan graph status ./callgraph.json

Q: Unknowns queue growing rapidly

A: Common causes:

1. Feed staleness: Update feeds
2. Internal packages: Configure internal patterns
3. New ecosystems: Check language support

# Diagnose
stella unknowns stats --by-reason

Q: Proof verification fails

A: Check:

1. Public key matches signing key
2. Certificate not expired
3. Bundle not corrupted

# Detailed verification
stella proof verify ./proof.dsse --verbose

Q: Where do I get more help?

A:

• Operations Runbooks
• Troubleshooting Guide
• Architecture Documentation
• Support: support@stellaops.example.com

---

Quick Reference

Commands Cheat Sheet

# Score Proofs
stella scan --generate-proof          # Generate proof
stella proof verify ./proof.dsse      # Verify proof
stella score replay ./bundle/         # Replay scan

# Reachability
stella scan graph ./src               # Generate call graph
stella scan --reachability            # Scan with reachability
stella reachability query --filter    # Query reachability data

# Unknowns
stella unknowns list                  # List unknowns
stella unknowns resolve <id>          # Resolve unknown
stella unknowns stats                 # Statistics

Configuration Quick Reference

{
  "ScoreProofs": {
    "Enabled": true,
    "SigningAlgorithm": "ECDSA-P256"
  },
  "Reachability": {
    "Enabled": true,
    "MaxDepth": 50,
    "CacheEnabled": true
  },
  "Unknowns": {
    "AutoResolveInternal": true,
    "InternalPatterns": ["@company/*"]
  }
}

---

Feedback? Submit issues or suggestions via the project's issue tracker.