8bbfe4d2d2
- Add RateLimitConfig for configuration management with YAML binding support. - Introduce RateLimitDecision to encapsulate the result of rate limit checks. - Implement RateLimitMetrics for OpenTelemetry metrics tracking. - Create RateLimitMiddleware for enforcing rate limits on incoming requests. - Develop RateLimitService to orchestrate instance and environment rate limit checks. - Add RateLimitServiceCollectionExtensions for dependency injection registration.
288 lines
6.9 KiB
Markdown
288 lines
6.9 KiB
Markdown
# 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)
|