Files

master 8bbfe4d2d2 feat(rate-limiting): Implement core rate limiting functionality with configuration, decision-making, metrics, middleware, and service registration

- 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.

2025-12-17 18:02:37 +02:00

6.9 KiB

Raw Blame History

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

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

Workflow 1: Offline Smart-Diff Analysis

Step 1: Prepare Offline Bundle

On a connected machine:

# 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:

# 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

# 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)

# 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)

# 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:

# 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)

# 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

# ~/.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

# 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

# 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:

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

Reproducibility Test

# 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:

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:

stellaops offline kit verify \
  --input bundle.tar.gz \
  --public-key /path/to/correct-key.pub

6.9 KiB Raw Blame History