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
2025-12-17 18:02:37 +02:00
parent 394b57f6bf
commit 8bbfe4d2d2
211 changed files with 47179 additions and 1590 deletions

View File

@@ -0,0 +1,233 @@
# Keyboard Shortcuts Reference
**Sprint:** SPRINT_3600_0001_0001
**Task:** TRI-MASTER-0010 - Document keyboard shortcuts in user guide
## Overview
StellaOps supports keyboard shortcuts for efficient triage and navigation. Shortcuts are available in the Web UI and CLI interactive modes.
## Triage View Shortcuts
### Navigation
| Key | Action | Context |
|-----|--------|---------|
| `j` / `↓` | Next finding | Finding list |
| `k` / `↑` | Previous finding | Finding list |
| `g g` | Go to first finding | Finding list |
| `G` | Go to last finding | Finding list |
| `Enter` | Open finding details | Finding list |
| `Esc` | Close panel / Cancel | Any |
### Decision Actions
| Key | Action | Context |
|-----|--------|---------|
| `a` | Mark as Affected | Finding selected |
| `n` | Mark as Not Affected | Finding selected |
| `w` | Mark as Won't Fix | Finding selected |
| `f` | Mark as False Positive | Finding selected |
| `u` | Undo last decision | Any |
| `Ctrl+z` | Undo | Any |
### Evidence & Context
| Key | Action | Context |
|-----|--------|---------|
| `e` | Toggle evidence panel | Finding selected |
| `g` | Toggle graph view | Finding selected |
| `c` | Show call stack | Finding selected |
| `v` | Show VEX status | Finding selected |
| `p` | Show provenance | Finding selected |
| `d` | Show diff | Finding selected |
### Search & Filter
| Key | Action | Context |
|-----|--------|---------|
| `/` | Open search | Global |
| `Ctrl+f` | Find in page | Global |
| `Ctrl+k` | Quick filter | Global |
| `x` | Clear filters | Filter active |
### View Controls
| Key | Action | Context |
|-----|--------|---------|
| `1` | Show all findings | View |
| `2` | Show untriaged only | View |
| `3` | Show affected only | View |
| `4` | Show not affected | View |
| `[` | Collapse all | List view |
| `]` | Expand all | List view |
| `Tab` | Next panel | Multi-panel |
| `Shift+Tab` | Previous panel | Multi-panel |
### Bulk Actions
| Key | Action | Context |
|-----|--------|---------|
| `Space` | Toggle selection | Finding |
| `Shift+j` | Select next | Selection mode |
| `Shift+k` | Select previous | Selection mode |
| `Ctrl+a` | Select all visible | Finding list |
| `Shift+a` | Bulk: Affected | Selection |
| `Shift+n` | Bulk: Not Affected | Selection |
## CLI Batch Mode Shortcuts
### Navigation
| Key | Action |
|-----|--------|
| `j` / `↓` | Next finding |
| `k` / `↑` | Previous finding |
| `Page Down` | Skip 10 forward |
| `Page Up` | Skip 10 back |
| `Home` | First finding |
| `End` | Last finding |
### Decisions
| Key | Action |
|-----|--------|
| `a` | Affected |
| `n` | Not affected |
| `w` | Won't fix |
| `f` | False positive |
| `s` | Skip (no decision) |
| `u` | Undo last |
### Information
| Key | Action |
|-----|--------|
| `e` | Show evidence |
| `i` | Show full info |
| `?` | Show help |
### Control
| Key | Action |
|-----|--------|
| `q` | Save and quit |
| `Q` | Quit without saving |
| `Ctrl+c` | Abort |
## Graph View Shortcuts
| Key | Action |
|-----|--------|
| `+` / `=` | Zoom in |
| `-` | Zoom out |
| `0` | Reset zoom |
| `Arrow keys` | Pan view |
| `f` | Fit to screen |
| `h` | Highlight path to root |
| `l` | Highlight dependents |
| `Enter` | Select node |
| `Esc` | Deselect |
## Dashboard Shortcuts
| Key | Action |
|-----|--------|
| `r` | Refresh data |
| `t` | Toggle sidebar |
| `m` | Open menu |
| `s` | Open settings |
| `?` | Show shortcuts |
## Scan View Shortcuts
| Key | Action |
|-----|--------|
| `j` / `k` | Navigate scans |
| `Enter` | Open scan details |
| `d` | Download report |
| `c` | Compare scans |
| `r` | Rescan |
## Configuration
### Enable/Disable Shortcuts
```yaml
# ~/.stellaops/ui.yaml
keyboard:
enabled: true
vim_mode: true # Use vim-style navigation
# Customize keys
custom:
next_finding: "j"
prev_finding: "k"
affected: "a"
not_affected: "n"
```
### CLI Configuration
```yaml
# ~/.stellaops/cli.yaml
interactive:
keyboard_enabled: true
confirm_quit: true
auto_save: true
```
### Web UI Settings
Access via **Settings → Keyboard Shortcuts**:
- Enable/disable shortcuts
- Customize key bindings
- Import/export configurations
## Accessibility
### Screen Reader Support
All keyboard shortcuts have equivalent menu actions:
- Use `Alt` to access menu bar
- Tab navigation for all controls
- ARIA labels for all actions
### Motion Preferences
When `prefers-reduced-motion` is set:
- Instant transitions replace animations
- Focus indicators remain visible longer
## Quick Reference Card
```
┌────────────────────────────────────────────┐
│ STELLAOPS KEYBOARD SHORTCUTS │
├────────────────────────────────────────────┤
│ NAVIGATION │ DECISIONS │
│ j/k Next/Prev │ a Affected │
│ g g First │ n Not Affected │
│ G Last │ w Won't Fix │
│ Enter Open │ f False Positive │
│ Esc Close │ u Undo │
├─────────────────────┼──────────────────────┤
│ EVIDENCE │ VIEW │
│ e Evidence panel │ 1 All findings │
│ g Graph view │ 2 Untriaged │
│ c Call stack │ 3 Affected │
│ v VEX status │ / Search │
├─────────────────────┼──────────────────────┤
│ BULK │ CONTROL │
│ Space Select │ q Save & quit │
│ Ctrl+a Select all │ ? Help │
│ Shift+a Bulk affect │ Ctrl+z Undo │
└─────────────────────┴──────────────────────┘
```
## Related Documentation
- [Triage CLI Reference](./triage-cli.md)
- [Web UI Guide](../15_UI_GUIDE.md)
- [Accessibility Guide](../accessibility.md)

284
docs/cli/smart-diff-cli.md Normal file
View File

@@ -0,0 +1,284 @@
# Smart-Diff CLI Reference
**Sprint:** SPRINT_3500_0001_0001
**Task:** SDIFF-MASTER-0008 - Update CLI documentation with smart-diff commands
## Overview
Smart-Diff analyzes changes between container image versions to identify material risk changes. It detects reachability shifts, VEX status changes, binary hardening regressions, and intelligence signal updates.
## Commands
### stellaops smart-diff
Compare two artifacts and report material risk changes.
```bash
stellaops smart-diff [OPTIONS]
```
#### Required Options
| Option | Description |
|--------|-------------|
| `--base <ARTIFACT>` | Base artifact (image digest, SBOM path, or purl) |
| `--target <ARTIFACT>` | Target artifact to compare against base |
#### Output Options
| Option | Description | Default |
|--------|-------------|---------|
| `--output <PATH>` | Output file path | stdout |
| `--output-format <FMT>` | Output format: `json`, `yaml`, `table`, `sarif` | `table` |
| `--output-dir <DIR>` | Output directory for bundle format | - |
| `--include-proofs` | Include proof ledger in output | `false` |
| `--include-evidence` | Include raw evidence data | `false` |
| `--pretty` | Pretty-print JSON/YAML output | `false` |
#### Analysis Options
| Option | Description | Default |
|--------|-------------|---------|
| `--rules <PATH>` | Custom detection rules file | built-in |
| `--config <PATH>` | Scoring configuration file | default config |
| `--tier <TIER>` | Filter by evidence tier: `imported`, `executed`, `tainted_sink` | all |
| `--min-priority <N>` | Minimum priority score (0-1) | 0.0 |
| `--include-unchanged` | Include unchanged findings | `false` |
#### Feed Options
| Option | Description | Default |
|--------|-------------|---------|
| `--feed-snapshot <HASH>` | Use specific feed snapshot | latest |
| `--offline` | Run in offline mode | `false` |
| `--feed-dir <PATH>` | Local feed directory | - |
### Examples
#### Basic Comparison
```bash
# Compare two image versions
stellaops smart-diff \
--base registry.example.com/app:v1.0.0 \
--target registry.example.com/app:v1.1.0
# Output:
# Smart-Diff Report: app:v1.0.0 → app:v1.1.0
# ═══════════════════════════════════════════
#
# Summary:
# Total Changes: 5
# Risk Increased: 2
# Risk Decreased: 3
# Hardening Regressions: 1
#
# Material Changes:
# ┌─────────────────┬──────────────────┬──────────┬──────────┐
# │ Vulnerability │ Component │ Change │ Priority │
# ├─────────────────┼──────────────────┼──────────┼──────────┤
# │ CVE-2024-1234 │ lodash@4.17.20 │ +reach │ 0.85 │
# │ CVE-2024-5678 │ requests@2.28.0 │ +kev │ 0.95 │
# │ CVE-2024-9999 │ urllib3@1.26.0 │ -reach │ 0.60 │
# └─────────────────┴──────────────────┴──────────┴──────────┘
```
#### SARIF Output for CI/CD
```bash
# Generate SARIF for GitHub Actions
stellaops smart-diff \
--base app:v1.0.0 \
--target app:v1.1.0 \
--output-format sarif \
--output results.sarif
```
#### Filtered Analysis
```bash
# Only show high-priority changes
stellaops smart-diff \
--base app:v1 \
--target app:v2 \
--min-priority 0.7 \
--output-format json
# Only tainted_sink tier findings
stellaops smart-diff \
--base app:v1 \
--target app:v2 \
--tier tainted_sink
```
#### Export with Proofs
```bash
# Full export with proof bundle
stellaops smart-diff \
--base app:v1 \
--target app:v2 \
--output-dir ./smart-diff-export \
--include-proofs \
--include-evidence
# Creates:
# ./smart-diff-export/
# ├── manifest.json
# ├── diff-results.json
# ├── proofs/
# └── evidence/
```
#### Offline Mode
```bash
# Use local feeds only
STELLAOPS_OFFLINE=true stellaops smart-diff \
--base sbom-v1.json \
--target sbom-v2.json \
--feed-dir /opt/stellaops/feeds
```
### stellaops smart-diff show
Display results from a saved smart-diff report.
```bash
stellaops smart-diff show [OPTIONS] <INPUT>
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--format <FMT>` | Output format: `table`, `json`, `yaml` | `table` |
| `--filter <EXPR>` | Filter expression (e.g., `priority>=0.8`) | - |
| `--sort <FIELD>` | Sort field: `priority`, `vuln`, `component` | `priority` |
| `--limit <N>` | Maximum results to show | all |
#### Example
```bash
# Show top 5 highest priority changes
stellaops smart-diff show \
--sort priority \
--limit 5 \
smart-diff-report.json
```
### stellaops smart-diff verify
Verify a smart-diff report's proof bundle.
```bash
stellaops smart-diff verify [OPTIONS] <INPUT>
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--proof-bundle <PATH>` | Proof bundle path | inferred |
| `--public-key <PATH>` | Public key for signature verification | - |
| `--strict` | Fail on any warning | `false` |
#### Example
```bash
# Verify report integrity
stellaops smart-diff verify \
--proof-bundle ./proofs \
--public-key /path/to/key.pub \
smart-diff-report.json
# Output:
# ✓ Manifest hash verified: sha256:abc123...
# ✓ Proof ledger valid (45 nodes)
# ✓ Root hash matches
# ✓ Signature valid (key: CN=scanner.stellaops.io)
```
### stellaops smart-diff replay
Re-run smart-diff with different feed or config.
```bash
stellaops smart-diff replay [OPTIONS] <SCAN-ID>
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--feed-snapshot <HASH>` | Use specific feed snapshot | latest |
| `--config <PATH>` | Different scoring config | original |
| `--dry-run` | Preview without saving | `false` |
#### Example
```bash
# Replay with new feed
stellaops smart-diff replay \
--feed-snapshot sha256:abc123... \
scan-12345678
# Preview impact of config change
stellaops smart-diff replay \
--config strict-scoring.json \
--dry-run \
scan-12345678
```
## Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success, no material changes |
| 1 | Success, material changes found |
| 2 | Success, hardening regressions found |
| 3 | Success, KEV additions found |
| 10 | Invalid arguments |
| 11 | Artifact not found |
| 12 | Feed not available |
| 20 | Verification failed |
| 99 | Internal error |
## Environment Variables
| Variable | Description |
|----------|-------------|
| `STELLAOPS_OFFLINE` | Run in offline mode |
| `STELLAOPS_FEED_DIR` | Local feed directory |
| `STELLAOPS_CONFIG` | Default config file |
| `STELLAOPS_OUTPUT_FORMAT` | Default output format |
## Configuration File
```yaml
# ~/.stellaops/smart-diff.yaml
defaults:
output_format: json
include_proofs: true
min_priority: 0.3
scoring:
reachability_flip_up_weight: 1.0
kev_added_weight: 1.5
hardening_regression_weight: 0.8
rules:
custom_path: /path/to/custom-rules.json
```
## Related Commands
- `stellaops scan` - Full vulnerability scan
- `stellaops score replay` - Score replay
- `stellaops verify-bundle` - Verify proof bundles
## Related Documentation
- [Smart-Diff Air-Gap Workflows](../airgap/smart-diff-airgap-workflows.md)
- [SARIF Integration](../ci/sarif-integration.md)
- [Scoring Configuration](../ci/scoring-configuration.md)

323
docs/cli/triage-cli.md Normal file
View File

@@ -0,0 +1,323 @@
# Triage CLI Reference
**Sprint:** SPRINT_3600_0001_0001
**Task:** TRI-MASTER-0008 - Update CLI documentation with offline commands
## Overview
The Triage CLI provides commands for vulnerability triage, decision management, and offline workflows. It supports evidence-based decision making and audit-ready replay tokens.
## Commands
### stellaops triage list
List findings for triage.
```bash
stellaops triage list [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Filter by scan ID | - |
| `--status <STATUS>` | Filter: `untriaged`, `affected`, `not_affected`, `wont_fix`, `false_positive` | all |
| `--priority-min <N>` | Minimum priority (0-1) | 0 |
| `--priority-max <N>` | Maximum priority (0-1) | 1 |
| `--sort <FIELD>` | Sort: `priority`, `vuln`, `component`, `created` | `priority` |
| `--format <FMT>` | Output: `table`, `json`, `csv` | `table` |
| `--limit <N>` | Max results | 50 |
| `--workspace <PATH>` | Offline workspace | - |
#### Examples
```bash
# List untriaged high-priority findings
stellaops triage list \
--scan-id scan-12345678 \
--status untriaged \
--priority-min 0.7
# Export for review
stellaops triage list \
--scan-id scan-12345678 \
--format json > findings.json
```
### stellaops triage show
Show finding details with evidence.
```bash
stellaops triage show <FINDING-ID> [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--show-evidence` | Include full evidence | `false` |
| `--evidence-first` | Lead with evidence summary | `false` |
| `--show-history` | Show decision history | `false` |
| `--format <FMT>` | Output: `text`, `json`, `yaml` | `text` |
| `--workspace <PATH>` | Offline workspace | - |
#### Example
```bash
# Show with evidence
stellaops triage show CVE-2024-1234 \
--show-evidence \
--evidence-first
# Output:
# ═══════════════════════════════════════════
# CVE-2024-1234 · pkg:npm/lodash@4.17.20
# ═══════════════════════════════════════════
#
# EVIDENCE
# ────────
# Reachability: TAINTED_SINK (tier 3/3)
# └─ api.js:42 → utils.js:15 → lodash/merge
#
# Call Stack:
# 1. api.js:42 handleUserInput()
# 2. utils.js:15 processData()
# 3. lodash:merge <vulnerable sink>
#
# VEX: No statement
# EPSS: 0.67 (High)
# KEV: No
#
# VULNERABILITY
# ─────────────
# CVE-2024-1234: Prototype Pollution in lodash
# CVSS: 7.5 (High)
# CWE: CWE-1321
#
# STATUS: untriaged
```
### stellaops triage decide
Record a triage decision.
```bash
stellaops triage decide <FINDING-ID> [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--status <STATUS>` | Required: `affected`, `not_affected`, `wont_fix`, `false_positive` | - |
| `--justification <TEXT>` | Decision justification | - |
| `--reviewer <NAME>` | Reviewer identifier | current user |
| `--vex-emit` | Emit VEX statement | `false` |
| `--workspace <PATH>` | Offline workspace | - |
#### Examples
```bash
# Mark as not affected
stellaops triage decide CVE-2024-1234 \
--status not_affected \
--justification "Feature gated, unreachable in production"
# Mark affected and emit VEX
stellaops triage decide CVE-2024-5678 \
--status affected \
--justification "In use, remediation planned" \
--vex-emit
```
### stellaops triage batch
Interactive batch triage mode.
```bash
stellaops triage batch [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan to triage | - |
| `--query <EXPR>` | Filter expression | - |
| `--input <PATH>` | Offline bundle | - |
| `--workspace <PATH>` | Offline workspace | - |
#### Keyboard Shortcuts
| Key | Action |
|-----|--------|
| `j` / `↓` | Next finding |
| `k` / `↑` | Previous finding |
| `a` | Mark affected |
| `n` | Mark not affected |
| `w` | Mark won't fix |
| `f` | Mark false positive |
| `e` | Show full evidence |
| `g` | Show graph context |
| `u` | Undo last decision |
| `/` | Search findings |
| `?` | Show help |
| `q` | Save and quit |
#### Example
```bash
# Interactive triage
stellaops triage batch \
--scan-id scan-12345678 \
--query "priority>=0.5"
```
### stellaops triage export
Export findings for offline triage.
```bash
stellaops triage export [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--scan-id <ID>` | Scan to export | required |
| `--findings <IDS>` | Specific finding IDs (comma-separated) | - |
| `--all-findings` | Export all findings | `false` |
| `--include-evidence` | Include evidence data | `true` |
| `--include-graph` | Include dependency graph | `true` |
| `--output <PATH>` | Output path (.stella.bundle.tgz) | required |
| `--sign` | Sign the bundle | `true` |
#### Example
```bash
# Export specific findings
stellaops triage export \
--scan-id scan-12345678 \
--findings CVE-2024-1234,CVE-2024-5678 \
--output triage-bundle.stella.bundle.tgz
```
### stellaops triage import
Import offline bundle for triage.
```bash
stellaops triage import [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--input <PATH>` | Bundle path | required |
| `--workspace <PATH>` | Target workspace | `~/.stellaops/triage` |
| `--verify` | Verify signature | `true` |
| `--public-key <PATH>` | Public key for verification | - |
### stellaops triage export-decisions
Export decisions for sync.
```bash
stellaops triage export-decisions [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--workspace <PATH>` | Workspace path | required |
| `--output <PATH>` | Output path | required |
| `--format <FMT>` | Format: `json`, `ndjson` | `json` |
| `--sign` | Sign output | `true` |
### stellaops triage import-decisions
Import and apply decisions.
```bash
stellaops triage import-decisions [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--input <PATH>` | Decisions file | required |
| `--verify` | Verify signatures | `true` |
| `--apply` | Apply to server | `false` |
| `--dry-run` | Preview only | `false` |
| `--conflict-mode <MODE>` | Conflict handling: `keep-local`, `keep-server`, `newest`, `review` | `review` |
### stellaops triage verify-bundle
Verify bundle integrity.
```bash
stellaops triage verify-bundle [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--input <PATH>` | Bundle path | required |
| `--public-key <PATH>` | Public key | required |
| `--strict` | Fail on warnings | `false` |
### stellaops triage show-token
Display replay token details.
```bash
stellaops triage show-token <TOKEN>
```
### stellaops triage verify-token
Verify replay token.
```bash
stellaops triage verify-token <TOKEN> [OPTIONS]
```
#### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--public-key <PATH>` | Public key | required |
## Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Findings require attention |
| 10 | Invalid arguments |
| 11 | Resource not found |
| 20 | Verification failed |
| 21 | Signature invalid |
| 30 | Conflict detected |
| 99 | Internal error |
## Environment Variables
| Variable | Description |
|----------|-------------|
| `STELLAOPS_OFFLINE` | Enable offline mode |
| `STELLAOPS_TRIAGE_WORKSPACE` | Default workspace |
| `STELLAOPS_REVIEWER` | Default reviewer name |
## Related Documentation
- [Triage Air-Gap Workflows](../airgap/triage-airgap-workflows.md)
- [Keyboard Shortcuts](./keyboard-shortcuts.md)
- [Triage API Reference](../api/triage-api.md)