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
366
docs/airgap/triage-airgap-workflows.md
Normal file
366
docs/airgap/triage-airgap-workflows.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# Triage Air-Gap Workflows
|
||||
|
||||
**Sprint:** SPRINT_3600_0001_0001
|
||||
**Task:** TRI-MASTER-0006 - Document air-gap triage workflows
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes how to perform vulnerability triage in fully air-gapped environments. The triage workflow supports offline evidence bundles, decision capture, and replay token generation.
|
||||
|
||||
## Workflow 1: Offline Triage with Evidence Bundles
|
||||
|
||||
### Step 1: Export Evidence Bundle (Connected Machine)
|
||||
|
||||
```bash
|
||||
# Export triage bundle for specific findings
|
||||
stellaops triage export \
|
||||
--scan-id scan-12345678 \
|
||||
--findings CVE-2024-1234,CVE-2024-5678 \
|
||||
--include-evidence \
|
||||
--include-graph \
|
||||
--output triage-bundle.stella.bundle.tgz
|
||||
|
||||
# Export entire scan for offline review
|
||||
stellaops triage export \
|
||||
--scan-id scan-12345678 \
|
||||
--all-findings \
|
||||
--output full-triage-bundle.stella.bundle.tgz
|
||||
```
|
||||
|
||||
### Step 2: Bundle Contents
|
||||
|
||||
The `.stella.bundle.tgz` archive contains:
|
||||
|
||||
```
|
||||
triage-bundle.stella.bundle.tgz/
|
||||
├── manifest.json # Signed bundle manifest
|
||||
├── findings/
|
||||
│ ├── index.json # Finding list with IDs
|
||||
│ ├── CVE-2024-1234.json # Finding details
|
||||
│ └── CVE-2024-5678.json
|
||||
├── evidence/
|
||||
│ ├── reachability/ # Reachability proofs
|
||||
│ ├── callstack/ # Call stack snippets
|
||||
│ ├── vex/ # VEX/CSAF statements
|
||||
│ └── provenance/ # Provenance data
|
||||
├── graph/
|
||||
│ ├── nodes.ndjson # Dependency graph nodes
|
||||
│ └── edges.ndjson # Graph edges
|
||||
├── feeds/
|
||||
│ └── snapshot.json # Feed snapshot metadata
|
||||
└── signature.dsse # DSSE envelope
|
||||
```
|
||||
|
||||
### Step 3: Transfer to Air-Gapped Environment
|
||||
|
||||
Transfer using approved methods:
|
||||
- USB media (security scanned)
|
||||
- Optical media
|
||||
- Data diode
|
||||
|
||||
### Step 4: Import and Verify
|
||||
|
||||
On the air-gapped machine:
|
||||
|
||||
```bash
|
||||
# Verify bundle integrity
|
||||
stellaops triage verify-bundle \
|
||||
--input triage-bundle.stella.bundle.tgz \
|
||||
--public-key /path/to/signing-key.pub
|
||||
|
||||
# Import for offline triage
|
||||
stellaops triage import \
|
||||
--input triage-bundle.stella.bundle.tgz \
|
||||
--workspace /opt/stellaops/triage
|
||||
```
|
||||
|
||||
### Step 5: Perform Offline Triage
|
||||
|
||||
```bash
|
||||
# List findings in bundle
|
||||
stellaops triage list \
|
||||
--workspace /opt/stellaops/triage
|
||||
|
||||
# View finding with evidence
|
||||
stellaops triage show CVE-2024-1234 \
|
||||
--workspace /opt/stellaops/triage \
|
||||
--show-evidence
|
||||
|
||||
# Make triage decision
|
||||
stellaops triage decide CVE-2024-1234 \
|
||||
--workspace /opt/stellaops/triage \
|
||||
--status not_affected \
|
||||
--justification "Code path is unreachable due to config gating" \
|
||||
--reviewer "security-team"
|
||||
```
|
||||
|
||||
### Step 6: Export Decisions
|
||||
|
||||
```bash
|
||||
# Export decisions for sync back
|
||||
stellaops triage export-decisions \
|
||||
--workspace /opt/stellaops/triage \
|
||||
--output decisions-2025-01-15.json \
|
||||
--sign
|
||||
```
|
||||
|
||||
### Step 7: Sync Decisions (Connected Machine)
|
||||
|
||||
```bash
|
||||
# Import and apply decisions
|
||||
stellaops triage import-decisions \
|
||||
--input decisions-2025-01-15.json \
|
||||
--verify \
|
||||
--apply
|
||||
```
|
||||
|
||||
## Workflow 2: Batch Offline Triage
|
||||
|
||||
For high-volume environments.
|
||||
|
||||
### Step 1: Export Batch Bundle
|
||||
|
||||
```bash
|
||||
# Export all untriaged findings
|
||||
stellaops triage export-batch \
|
||||
--query "status=untriaged AND priority>=0.7" \
|
||||
--limit 100 \
|
||||
--output batch-triage-2025-01-15.stella.bundle.tgz
|
||||
```
|
||||
|
||||
### Step 2: Offline Batch Processing
|
||||
|
||||
```bash
|
||||
# Interactive batch triage
|
||||
stellaops triage batch \
|
||||
--workspace /opt/stellaops/triage \
|
||||
--input batch-triage-2025-01-15.stella.bundle.tgz
|
||||
|
||||
# Keyboard shortcuts enabled:
|
||||
# j/k - Next/Previous finding
|
||||
# a - Accept (affected)
|
||||
# n - Not affected
|
||||
# w - Will not fix
|
||||
# f - False positive
|
||||
# u - Undo last decision
|
||||
# q - Quit (saves progress)
|
||||
```
|
||||
|
||||
### Step 3: Export and Sync
|
||||
|
||||
```bash
|
||||
# Export batch decisions
|
||||
stellaops triage export-decisions \
|
||||
--workspace /opt/stellaops/triage \
|
||||
--format json \
|
||||
--sign \
|
||||
--output batch-decisions.json
|
||||
```
|
||||
|
||||
## Workflow 3: Evidence-First Offline Review
|
||||
|
||||
### Step 1: Pre-compute Evidence
|
||||
|
||||
On connected machine:
|
||||
|
||||
```bash
|
||||
# Generate evidence for all high-priority findings
|
||||
stellaops evidence generate \
|
||||
--scan-id scan-12345678 \
|
||||
--priority-min 0.7 \
|
||||
--output-dir ./evidence-pack
|
||||
|
||||
# Include:
|
||||
# - Reachability analysis
|
||||
# - Call stack traces
|
||||
# - VEX lookups
|
||||
# - Dependency graph snippets
|
||||
```
|
||||
|
||||
### Step 2: Package with Findings
|
||||
|
||||
```bash
|
||||
stellaops triage package \
|
||||
--scan-id scan-12345678 \
|
||||
--evidence-dir ./evidence-pack \
|
||||
--output evidence-triage.stella.bundle.tgz
|
||||
```
|
||||
|
||||
### Step 3: Offline Review with Evidence
|
||||
|
||||
```bash
|
||||
# Evidence-first view
|
||||
stellaops triage show CVE-2024-1234 \
|
||||
--workspace /opt/stellaops/triage \
|
||||
--evidence-first
|
||||
|
||||
# Output:
|
||||
# ═══════════════════════════════════════════
|
||||
# CVE-2024-1234 · lodash@4.17.20
|
||||
# ═══════════════════════════════════════════
|
||||
#
|
||||
# EVIDENCE SUMMARY
|
||||
# ────────────────
|
||||
# Reachability: EXECUTED (tier 2/3)
|
||||
# └─ main.js:42 → utils.js:15 → lodash/merge
|
||||
#
|
||||
# Call Stack:
|
||||
# 1. main.js:42 handleRequest()
|
||||
# 2. utils.js:15 mergeConfig()
|
||||
# 3. lodash:merge <vulnerable>
|
||||
#
|
||||
# VEX Status: No statement found
|
||||
# EPSS: 0.45 (Medium)
|
||||
# KEV: No
|
||||
#
|
||||
# ─────────────────────────────────────────────
|
||||
# Press [a]ffected, [n]ot affected, [s]kip...
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `STELLAOPS_OFFLINE` | Enable offline mode | `false` |
|
||||
| `STELLAOPS_TRIAGE_WORKSPACE` | Triage workspace path | `~/.stellaops/triage` |
|
||||
| `STELLAOPS_BUNDLE_VERIFY` | Verify bundle signatures | `true` |
|
||||
| `STELLAOPS_DECISION_SIGN` | Sign exported decisions | `true` |
|
||||
|
||||
### Config File
|
||||
|
||||
```yaml
|
||||
# ~/.stellaops/triage.yaml
|
||||
offline:
|
||||
enabled: true
|
||||
workspace: /opt/stellaops/triage
|
||||
bundle_verify: true
|
||||
|
||||
decisions:
|
||||
require_justification: true
|
||||
sign_exports: true
|
||||
|
||||
keyboard:
|
||||
enabled: true
|
||||
vim_mode: true
|
||||
```
|
||||
|
||||
## Bundle Format Specification
|
||||
|
||||
### manifest.json
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"type": "triage-bundle",
|
||||
"created_at": "2025-01-15T10:00:00Z",
|
||||
"scan_id": "scan-12345678",
|
||||
"finding_count": 25,
|
||||
"feed_snapshot": "sha256:abc123...",
|
||||
"graph_revision": "sha256:def456...",
|
||||
"signatures": {
|
||||
"manifest": "sha256:ghi789...",
|
||||
"dsse_envelope": "signature.dsse"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Decision Format
|
||||
|
||||
```json
|
||||
{
|
||||
"finding_id": "finding-12345678",
|
||||
"vuln_key": "CVE-2024-1234:pkg:npm/lodash@4.17.20",
|
||||
"status": "not_affected",
|
||||
"justification": "Code path gated by feature flag",
|
||||
"reviewer": "security-team",
|
||||
"decided_at": "2025-01-15T14:30:00Z",
|
||||
"replay_token": "rt_abc123...",
|
||||
"evidence_refs": [
|
||||
"evidence/reachability/CVE-2024-1234.json"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Replay Tokens
|
||||
|
||||
Each decision generates a replay token for audit trail:
|
||||
|
||||
```bash
|
||||
# View replay token
|
||||
stellaops triage show-token rt_abc123...
|
||||
|
||||
# Output:
|
||||
# Replay Token: rt_abc123...
|
||||
# ─────────────────────────────
|
||||
# Finding: CVE-2024-1234
|
||||
# Decision: not_affected
|
||||
# Evidence Hash: sha256:xyz789...
|
||||
# Feed Snapshot: sha256:abc123...
|
||||
# Decided: 2025-01-15T14:30:00Z
|
||||
# Reviewer: security-team
|
||||
```
|
||||
|
||||
### Verify Token
|
||||
|
||||
```bash
|
||||
stellaops triage verify-token rt_abc123... \
|
||||
--public-key /path/to/key.pub
|
||||
|
||||
# ✓ Token signature valid
|
||||
# ✓ Evidence hash matches
|
||||
# ✓ Feed snapshot verified
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: Bundle signature invalid
|
||||
|
||||
```
|
||||
Error: Bundle signature verification failed
|
||||
```
|
||||
|
||||
**Solution:** Ensure the correct public key is used:
|
||||
```bash
|
||||
stellaops triage verify-bundle \
|
||||
--input bundle.tgz \
|
||||
--public-key /path/to/correct-key.pub \
|
||||
--verbose
|
||||
```
|
||||
|
||||
### Error: Evidence not found
|
||||
|
||||
```
|
||||
Error: Evidence for CVE-2024-1234 not included in bundle
|
||||
```
|
||||
|
||||
**Solution:** Re-export with evidence:
|
||||
```bash
|
||||
stellaops triage export \
|
||||
--scan-id scan-12345678 \
|
||||
--findings CVE-2024-1234 \
|
||||
--include-evidence \
|
||||
--output bundle.tgz
|
||||
```
|
||||
|
||||
### Error: Decision sync conflict
|
||||
|
||||
```
|
||||
Error: Finding CVE-2024-1234 has newer decision on server
|
||||
```
|
||||
|
||||
**Solution:** Review and resolve:
|
||||
```bash
|
||||
stellaops triage import-decisions \
|
||||
--input decisions.json \
|
||||
--conflict-mode review
|
||||
|
||||
# Options: keep-local, keep-server, newest, review
|
||||
```
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Offline Kit Guide](../10_OFFLINE_KIT.md)
|
||||
- [Triage API Reference](../api/triage-api.md)
|
||||
- [Keyboard Shortcuts](../ui/keyboard-shortcuts.md)
|
||||
Reference in New Issue
Block a user