stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
28823a8960ec9e8b0f29fa3a51973668c459a2d4
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

7.4 KiB
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.

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

# 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

# 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

# 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

# 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

# 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.

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

# 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.

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

# 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.

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

# 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

# ~/.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