docs(sprint-3500.0004.0004): Complete documentation handoff

Sprint 3500.0004.0004 (Documentation & Handoff) - COMPLETE Training Materials (T5 DONE): - epic-3500-faq.md: Comprehensive FAQ for Score Proofs/Reachability - video-tutorial-scripts.md: 6 video tutorial scripts - Training guides already existed from prior work Release Notes (T6 DONE): - v2.5.0-release-notes.md: Full release notes with breaking changes, upgrade instructions, and performance benchmarks OpenAPI Specs (T7 DONE): - Scanner OpenAPI already comprehensive with ProofSpines, Unknowns, CallGraphs, Reachability endpoints and schemas Handoff Checklist (T8 DONE): - epic-3500-handoff-checklist.md: Complete handoff documentation including sign-off tracking, escalation paths, monitoring config All 8/8 tasks complete. Sprint DONE. Epic 3500 documentation deliverables complete.
2025-12-20 22:38:19 +02:00
parent 4b3db9ca85
commit 80b8254763
12 changed files with 4761 additions and 32 deletions
--- a/docs/training/epic-3500-faq.md
+++ b/docs/training/epic-3500-faq.md
@@ -0,0 +1,543 @@
+# 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](#general-questions)
+2. [Score Proofs](#score-proofs)
+3. [Reachability Analysis](#reachability-analysis)
+4. [Unknowns Queue](#unknowns-queue)
+5. [Integration & Deployment](#integration--deployment)
+6. [Performance](#performance)
+7. [Troubleshooting](#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](../operations/airgap-operations-runbook.md) 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:
+
+```bash
+# 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:
+
+```bash
+# 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](../operations/proof-verification-runbook.md)
+
+### 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](../12_PERFORMANCE_WORKBOOK.md).
+
+---
+
+## 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:**
+
+```bash
+# 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:
+
+```bash
+# 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:**
+
+```bash
+# 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 |
+
+```bash
+# 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:
+
+```yaml
+# 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:
+
+```yaml
+- 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](../ci/).
+
+### 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](../api/)
+
+### Q: How do I configure retention?
+
+**A:** Configure in `appsettings.json`:
+
+```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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Detailed verification
+stella proof verify ./proof.dsse --verbose
+```
+
+### Q: Where do I get more help?
+
+**A:**
+- [Operations Runbooks](../operations/)
+- [Troubleshooting Guide](troubleshooting-guide.md)
+- [Architecture Documentation](../07_HIGH_LEVEL_ARCHITECTURE.md)
+- Support: support@stellaops.example.com
+
+---
+
+## Quick Reference
+
+### Commands Cheat Sheet
+
+```bash
+# 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
+
+```json
+{
+  "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.