git.stella-ops.org/docs/training/video-tutorial-scripts.md

# Video Tutorial Scripts

**Sprint:** SPRINT_3500_0004_0004  
**Format:** Tutorial scripts for screen recording

This document contains scripts for video tutorials covering Score Proofs, Reachability Analysis, and Unknowns Management.

---

## Video 1: Introduction to Score Proofs (5 min)

### Script

**[Opening - Logo/Title Card]**

> Welcome to StellaOps. In this tutorial, you'll learn how Score Proofs provide cryptographic guarantees that your vulnerability scores are reproducible and verifiable.

**[Screen: Terminal]**

> Let's start with a typical vulnerability scan. Here I have an SBOM for my application.

```bash
stella scan --sbom ./sbom.json
```

> The scan produces findings, but how do we know these results are accurate? Can we prove they're reproducible?

**[Screen: Terminal - enable proofs]**

> Let's run the same scan with proof generation enabled.

```bash
stella scan --sbom ./sbom.json --generate-proof --output ./scan-results/
```

> Notice the `--generate-proof` flag. StellaOps now creates a cryptographic attestation alongside the findings.

**[Screen: File browser showing proof bundle]**

> Here's what got generated:
> - `manifest.json` contains content-addressed references to every input
> - `proof.dsse` is the signed attestation
> - `findings.json` has the actual vulnerability results

**[Screen: Terminal - verify]**

> Anyone with this bundle can verify the proof:

```bash
stella proof verify ./scan-results/proof.dsse
```

> The signature is valid, and we can see exactly which inputs produced these results.

**[Screen: Terminal - replay]**

> We can even replay the scan to prove determinism:

```bash
stella score replay ./scan-results/ --verify
```

> Same inputs produce the exact same outputs. This is powerful for audits and compliance.

**[Closing]**

> That's Score Proofs in action. For more details, check the documentation or watch our deep-dive tutorials.

---

## Video 2: Understanding Reachability Analysis (7 min)

### Script

**[Opening]**

> Vulnerability scanners often overwhelm teams with alerts. Reachability analysis helps you focus on what actually matters.

**[Screen: Slide showing vulnerability count]**

> Imagine your scanner finds 200 vulnerabilities. Studies show 80-90% are unreachable—the vulnerable code path never executes in your application.

**[Screen: Terminal]**

> Let's see reachability in action. First, we generate a call graph:

```bash
stella scan graph ./src --output ./callgraph.json
```

> This analyzes your source code to map function calls.

**[Screen: Visualization of call graph]**

> The call graph shows which functions call which. Starting from your entry points, we can trace all possible execution paths.

**[Screen: Terminal - scan with reachability]**

> Now let's scan with reachability enabled:

```bash
stella scan --sbom ./sbom.json --call-graph ./callgraph.json --reachability
```

**[Screen: Results showing reachability verdicts]**

> Look at the results:
> - CVE-2024-1234: `REACHABLE_STATIC` - this IS on an executable path
> - CVE-2024-5678: `NOT_REACHABLE` - safely ignore this one
> - CVE-2024-9012: `POSSIBLY_REACHABLE` - needs review

**[Screen: Terminal - filter]**

> We can filter to only actionable items:

```bash
stella query --filter "reachability=REACHABLE_STATIC"
```

> From 200 findings, we're now focused on 20 that actually matter.

**[Screen: Diagram showing path]**

> For reachable vulnerabilities, we can see the exact path:

```bash
stella reachability explain --cve CVE-2024-1234
```

> `Main.java:15` calls `Service.java:42`, which calls the vulnerable function.

**[Closing]**

> Reachability analysis transforms alert fatigue into focused action. Enable it today.

---

## Video 3: Managing the Unknowns Queue (5 min)

### Script

**[Opening]**

> Sometimes StellaOps encounters packages it can't fully analyze. The Unknowns Queue helps you track and resolve these blind spots.

**[Screen: Terminal - scan with unknowns]**

> When we scan, some packages may be flagged as unknown:

```bash
stella scan --sbom ./sbom.json
# ...
# ⚠️ 12 unknowns detected
```

**[Screen: Terminal - list unknowns]**

> Let's see what's in the queue:

```bash
stella unknowns list
```

> We have:
> - `internal-auth-lib@1.0.0` - no advisory match
> - `custom-logger@2.1.0` - checksum miss
> - A couple more...

**[Screen: Terminal - show details]**

> Let's look at one in detail:

```bash
stella unknowns show UNK-001
```

> This is `internal-auth-lib`—it's our internal package, so of course there's no public advisory!

**[Screen: Terminal - resolve]**

> We can resolve it:

```bash
stella unknowns resolve UNK-001 --resolution internal_package --note "Our internal auth library"
```

> Now it won't keep appearing.

**[Screen: Terminal - patterns]**

> For bulk handling, configure patterns:

```bash
stella config set unknowns.internalPatterns '@mycompany/*,internal-*'
```

> All packages matching these patterns are auto-classified.

**[Screen: Terminal - stats]**

> Track your queue health:

```bash
stella unknowns stats
```

> Target: less than 5% unknown packages.

**[Closing]**

> Regular unknown management keeps your security coverage complete. Don't let blind spots accumulate.

---

## Video 4: Integrating with CI/CD (8 min)

### Script

**[Opening]**

> Let's add Score Proofs and Reachability to your CI/CD pipeline.

**[Screen: GitHub Actions YAML]**

> Here's a GitHub Actions workflow:

```yaml
name: Security Scan
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Generate SBOM
        run: syft . -o cyclonedx-json > sbom.json
      
      - name: Generate Call Graph
        run: stella scan graph ./src --output callgraph.json
      
      - name: Scan with Proofs and Reachability
        run: |
          stella scan \
            --sbom sbom.json \
            --call-graph callgraph.json \
            --generate-proof \
            --reachability \
            --output ./results/
      
      - name: Check for Reachable Criticals
        run: |
          COUNT=$(stella query \
            --input ./results/ \
            --filter "reachability=REACHABLE_STATIC AND severity=CRITICAL" \
            --count)
          if [ "$COUNT" -gt 0 ]; then
            echo "Found $COUNT reachable critical vulnerabilities"
            exit 1
          fi
      
      - name: Upload Proof Bundle
        uses: actions/upload-artifact@v4
        with:
          name: security-proof
          path: ./results/
```

**[Screen: Pipeline running]**

> Let's trigger the pipeline... and watch it run.

**[Screen: Pipeline success/failure]**

> The pipeline:
> 1. Generates an SBOM
> 2. Creates a call graph
> 3. Scans with proofs and reachability
> 4. Fails if reachable criticals exist

**[Screen: Artifacts]**

> The proof bundle is saved as an artifact for auditing.

**[Screen: PR comment]**

> You can even post results to PRs:

```yaml
- name: Comment Results
  run: |
    stella report --format markdown > report.md
    gh pr comment --body-file report.md
```

**[Closing]**

> Automated security with proof. Check out our GitLab and Jenkins templates too.

---

## Video 5: Air-Gap Operations (6 min)

### Script

**[Opening]**

> For classified or restricted environments, StellaOps works fully offline. Let's see how.

**[Screen: Diagram - Air-gapped setup]**

> In an air-gapped environment, there's no internet access. We use offline kits to bring in vulnerability data.

**[Screen: Terminal - connected side]**

> On a connected machine, prepare the offline kit:

```bash
stella offline-kit create \
  --include-feeds nvd,github,osv \
  --include-trust-bundle \
  --output ./offline-kit.tar.gz
```

**[Screen: USB/secure transfer]**

> Transfer this securely to the air-gapped environment.

**[Screen: Terminal - air-gapped side]**

> On the air-gapped machine, import:

```bash
stella offline-kit import ./offline-kit.tar.gz
```

**[Screen: Terminal - verify]**

> Verify the kit integrity:

```bash
stella offline-kit verify
```

> Signatures match—we can trust this data.

**[Screen: Terminal - scan]**

> Now scan as usual:

```bash
stella scan --sbom ./sbom.json --offline
```

> Results use the imported feeds. No network required.

**[Screen: Terminal - generate proof]**

> Proofs work offline too:

```bash
stella scan --sbom ./sbom.json --offline --generate-proof
```

**[Screen: Terminal - verify offline]**

> And verification:

```bash
stella proof verify ./proof.dsse --offline
```

> Everything works without connectivity.

**[Closing]**

> StellaOps is sovereign by design. Your security doesn't depend on cloud availability.

---

## Video 6: Deep Dive - Deterministic Replay (10 min)

### Script

**[Opening]**

> Score replay is a powerful auditing feature. Let's explore how it works under the hood.

**[Screen: Diagram - Replay architecture]**

> When you generate a proof, StellaOps captures:
> - Content-addressed SBOM (sha256 hash)
> - Feed snapshots at exact timestamps
> - Algorithm version
> - Configuration state

**[Screen: JSON manifest]**

> Here's a manifest:

```json
{
  "scanId": "scan-12345",
  "inputs": {
    "sbom": {
      "digest": "sha256:a1b2c3...",
      "format": "cyclonedx-1.6"
    },
    "feeds": {
      "nvd": {
        "digest": "sha256:d4e5f6...",
        "asOf": "2025-01-15T00:00:00Z"
      }
    }
  },
  "environment": {
    "algorithmVersion": "2.5.0"
  }
}
```

**[Screen: Terminal - replay]**

> To replay, StellaOps:
> 1. Retrieves inputs by their digests
> 2. Restores configuration
> 3. Re-runs the exact computation

```bash
stella score replay ./proof-bundle/ --verbose
```

**[Screen: Output comparison]**

> The output shows:
> - ✅ Finding 1 matches
> - ✅ Finding 2 matches
> - ✅ All scores identical
> - ✅ Merkle root matches

**[Screen: Diagram - Merkle tree]**

> Individual findings can be verified using Merkle proofs—without replaying the entire scan.

```bash
stella proof verify-finding --proof ./proof.dsse --finding-id F-001
```

**[Screen: Terminal - handling drift]**

> What if feeds have updated?

```bash
stella score replay ./proof-bundle/
# ⚠️ Feed digest mismatch: NVD
# Expected: sha256:d4e5f6...
# Current:  sha256:x7y8z9...
```

> Use feed freezing:

```bash
stella feeds freeze --from-manifest ./manifest.json
stella score replay ./proof-bundle/ --frozen
```

**[Closing]**

> Deterministic replay provides true auditability. Every score can be proven, every time.

---

## Recording Notes

### Equipment
- Screen recording: OBS Studio or Camtasia
- Resolution: 1920x1080
- Terminal font size: 16-18pt
- Use dark theme for terminal

### Preparation
- Clean terminal history
- Pre-stage all files
- Have backup recordings of long-running commands
- Test all commands before recording

### Post-Production
- Add chapter markers
- Include closed captions
- Export to MP4 (H.264) for compatibility
- Upload to internal video platform

### Duration Targets
- Introduction videos: 5-7 minutes
- Deep dives: 8-12 minutes
- Quick tips: 2-3 minutes

---

## Revision History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2025-12-20 | Agent | Initial scripts created |