# Smart-Diff Air-Gap Workflows

**Sprint:** SPRINT_3500_0001_0001  
**Task:** SDIFF-MASTER-0006 - Document air-gap workflows for smart-diff

## Overview

Smart-Diff can operate in fully air-gapped environments using offline bundles. This document describes the workflows for running smart-diff analysis without network connectivity.

## Prerequisites

1. **Offline Kit** - Downloaded and verified (`stellaops offline kit download`)
2. **Feed Snapshots** - Pre-staged vulnerability feeds
3. **SBOM Cache** - Pre-generated SBOMs for target artifacts

## Workflow 1: Offline Smart-Diff Analysis

### Step 1: Prepare Offline Bundle

On a connected machine:

```bash
# Download offline kit with feeds
stellaops offline kit download \
  --output /path/to/offline-bundle \
  --include-feeds nvd,osv,epss \
  --feed-date 2025-01-15

# Include SBOMs for known artifacts
stellaops offline sbom generate \
  --artifact registry.example.com/app:v1 \
  --artifact registry.example.com/app:v2 \
  --output /path/to/offline-bundle/sboms

# Package for transfer
stellaops offline kit package \
  --input /path/to/offline-bundle \
  --output stellaops-offline-2025-01-15.tar.gz \
  --sign
```

### Step 2: Transfer to Air-Gapped Environment

Transfer the bundle using approved media:
- USB drive (scanned and approved)
- Optical media (DVD/Blu-ray)
- Data diode

### Step 3: Import Bundle

On the air-gapped machine:

```bash
# Verify bundle signature
stellaops offline kit verify \
  --input stellaops-offline-2025-01-15.tar.gz \
  --public-key /path/to/signing-key.pub

# Extract and configure
stellaops offline kit import \
  --input stellaops-offline-2025-01-15.tar.gz \
  --data-dir /opt/stellaops/data
```

### Step 4: Run Smart-Diff

```bash
# Set offline mode
export STELLAOPS_OFFLINE=true
export STELLAOPS_DATA_DIR=/opt/stellaops/data

# Run smart-diff
stellaops smart-diff \
  --base sbom:app-v1.json \
  --target sbom:app-v2.json \
  --output smart-diff-report.json
```

## Workflow 2: Pre-Computed Smart-Diff Export

For environments where even running analysis tools is restricted.

### Step 1: Prepare Artifacts (Connected Machine)

```bash
# Generate SBOMs
stellaops sbom generate --artifact app:v1 --output app-v1-sbom.json
stellaops sbom generate --artifact app:v2 --output app-v2-sbom.json

# Run smart-diff with full proof bundle
stellaops smart-diff \
  --base app-v1-sbom.json \
  --target app-v2-sbom.json \
  --output-dir ./smart-diff-export \
  --include-proofs \
  --include-evidence \
  --format bundle
```

### Step 2: Verify Export Contents

The export bundle contains:
```
smart-diff-export/
├── manifest.json           # Signed manifest
├── base-sbom.json          # Base SBOM (hash verified)
├── target-sbom.json        # Target SBOM (hash verified)
├── diff-results.json       # Smart-diff findings
├── sarif-report.json       # SARIF formatted output
├── proofs/
│   ├── ledger.json         # Proof ledger
│   └── nodes/              # Individual proof nodes
├── evidence/
│   ├── reachability.json   # Reachability evidence
│   ├── vex-statements.json # VEX statements
│   └── hardening.json      # Binary hardening data
└── signature.dsse          # DSSE envelope
```

### Step 3: Import and Verify (Air-Gapped Machine)

```bash
# Verify bundle integrity
stellaops verify-bundle \
  --input smart-diff-export \
  --public-key /path/to/trusted-key.pub

# View results
stellaops smart-diff show \
  --bundle smart-diff-export \
  --format table
```

## Workflow 3: Incremental Feed Updates

### Step 1: Generate Delta Feed

On connected machine:

```bash
# Generate delta since last sync
stellaops offline feed delta \
  --since 2025-01-10 \
  --output feed-delta-2025-01-15.tar.gz \
  --sign
```

### Step 2: Apply Delta (Air-Gapped)

```bash
# Import delta
stellaops offline feed apply \
  --input feed-delta-2025-01-15.tar.gz \
  --verify

# Trigger score replay for affected scans
stellaops score replay-all \
  --trigger feed-update \
  --dry-run
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `STELLAOPS_OFFLINE` | Enable offline mode | `false` |
| `STELLAOPS_DATA_DIR` | Local data directory | `~/.stellaops` |
| `STELLAOPS_FEED_DIR` | Feed snapshot directory | `$DATA_DIR/feeds` |
| `STELLAOPS_SBOM_CACHE` | SBOM cache directory | `$DATA_DIR/sboms` |
| `STELLAOPS_SKIP_NETWORK` | Block network requests | `false` |
| `STELLAOPS_REQUIRE_SIGNATURES` | Require signed data | `true` |

### Config File

```yaml
# ~/.stellaops/config.yaml
offline:
  enabled: true
  data_dir: /opt/stellaops/data
  require_signatures: true
  
feeds:
  source: local
  path: /opt/stellaops/data/feeds
  
sbom:
  cache_dir: /opt/stellaops/data/sboms
  
network:
  allow_list: []  # Empty = no network
```

## Verification

### Verify Feed Freshness

```bash
# Check feed dates
stellaops offline status

# Output:
# Feed Status (Offline Mode)
# ─────────────────────────────
# NVD:  2025-01-15 (2 days old)
# OSV:  2025-01-15 (2 days old)
# EPSS: 2025-01-14 (3 days old)
# KEV:  2025-01-15 (2 days old)
```

### Verify Proof Integrity

```bash
# Verify smart-diff proofs
stellaops smart-diff verify \
  --input smart-diff-report.json \
  --proof-bundle ./proofs

# Output:
# ✓ Manifest hash verified
# ✓ All proof nodes valid
# ✓ Root hash matches: sha256:abc123...
```

## Determinism Guarantees

Offline smart-diff maintains determinism by:

1. **Content-addressed feeds** - Same feed hash = same results
2. **Frozen timestamps** - All timestamps use manifest creation time
3. **No network randomness** - No external API calls
4. **Stable sorting** - Deterministic output ordering

### Reproducibility Test

```bash
# Run twice and compare
stellaops smart-diff --base a.json --target b.json --output run1.json
stellaops smart-diff --base a.json --target b.json --output run2.json

# Compare hashes
sha256sum run1.json run2.json
# abc123...  run1.json
# abc123...  run2.json  (identical)
```

## Troubleshooting

### Error: Feed not found

```
Error: Feed 'nvd' not found in offline data directory
```

**Solution:** Ensure feed was included in offline kit:
```bash
stellaops offline kit status
ls $STELLAOPS_FEED_DIR/nvd/
```

### Error: Network request blocked

```
Error: Network request blocked in offline mode: api.osv.dev
```

**Solution:** This is expected behavior. Ensure all required data is in offline bundle.

### Error: Signature verification failed

```
Error: Bundle signature verification failed
```

**Solution:** Ensure correct public key is configured:
```bash
stellaops offline kit verify \
  --input bundle.tar.gz \
  --public-key /path/to/correct-key.pub
```

## Related Documentation

- [Offline Kit Guide](../10_OFFLINE_KIT.md)
- [Determinism Requirements](../product-advisories/14-Dec-2025%20-%20Determinism%20and%20Reproducibility%20Technical%20Reference.md)
- [Smart-Diff API](../api/scanner-api.md)