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.
This commit is contained in:
master
287
docs/airgap/smart-diff-airgap-workflows.md
Normal file
287
docs/airgap/smart-diff-airgap-workflows.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user