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
284
docs/cli/smart-diff-cli.md
Normal file
284
docs/cli/smart-diff-cli.md
Normal 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)
|
||||
Reference in New Issue
Block a user