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](#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.