stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
b4235c134cb7481f0d942fcb63c4409db2f36b23
git.stella-ops.org/docs/cli/smart-diff-cli.md
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

285 lines
7.4 KiB
Markdown
Raw Blame History

# 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 View Git Blame Copy Permalink