git.stella-ops.org/docs/modules/cli/guides/commands/smart-diff.md

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

• Smart-Diff Air-Gap Workflows
• SARIF Integration
• Scoring Configuration