Audience: DevOps engineers, release operators, and CI authors comparing successive builds of a container image. Scope: The stella smart-diff command group — analyzing the material risk delta between two artifacts and verifying or replaying the resulting report.
Smart-Diff analyzes the changes between two container image versions to surface material risk changes — not raw findings churn. It detects reachability shifts, VEX status changes, binary hardening regressions, and intelligence-signal updates (such as new KEV entries), and ranks them by priority.
Compare two artifacts and report material risk changes.
stella smart-diff [OPTIONS]
| Option | Description |
|---|
--base <ARTIFACT> | Base artifact (image digest, SBOM path, or purl) |
--target <ARTIFACT> | Target artifact to compare against base |
| 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 |
| 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 |
| Option | Description | Default |
|---|
--feed-snapshot <HASH> | Use specific feed snapshot | latest |
--offline | Run in offline mode | false |
--feed-dir <PATH> | Local feed directory | - |
# Compare two image versions
stella 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 │
# └─────────────────┴──────────────────┴──────────┴──────────┘
# Generate SARIF for GitHub Actions
stella smart-diff \
--base app:v1.0.0 \
--target app:v1.1.0 \
--output-format sarif \
--output results.sarif
# Only show high-priority changes
stella smart-diff \
--base app:v1 \
--target app:v2 \
--min-priority 0.7 \
--output-format json
# Only tainted_sink tier findings
stella smart-diff \
--base app:v1 \
--target app:v2 \
--tier tainted_sink
# Full export with proof bundle
stella 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/
# Use local feeds only
STELLAOPS_OFFLINE=true stella smart-diff \
--base sbom-v1.json \
--target sbom-v2.json \
--feed-dir /opt/stellaops/feeds
Display results from a saved smart-diff report.
stella smart-diff show [OPTIONS] <INPUT>
| 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 |
# Show top 5 highest priority changes
stella smart-diff show \
--sort priority \
--limit 5 \
smart-diff-report.json
Verify a smart-diff report’s proof bundle.
stella smart-diff verify [OPTIONS] <INPUT>
| Option | Description | Default |
|---|
--proof-bundle <PATH> | Proof bundle path | inferred |
--public-key <PATH> | Public key for signature verification | - |
--strict | Fail on any warning | false |
# Verify report integrity
stella 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)
Re-run smart-diff with a different feed or config.
stella smart-diff replay [OPTIONS] <SCAN-ID>
| Option | Description | Default |
|---|
--feed-snapshot <HASH> | Use specific feed snapshot | latest |
--config <PATH> | Different scoring config | original |
--dry-run | Preview without saving | false |
# Replay with new feed
stella smart-diff replay \
--feed-snapshot sha256:abc123... \
scan-12345678
# Preview impact of config change
stella smart-diff replay \
--config strict-scoring.json \
--dry-run \
scan-12345678
| 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 |
| 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 |
# ~/.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
stella scan — full vulnerability scan (reference)stella score replay — deterministic score replay (reference)stella smart-diff verify — verify a smart-diff proof bundle (above)
