git.stella-ops.org/docs/guides/compare-workflow-user-guide.md

Compare Workflow User Guide

Version: 1.0 Last Updated: 2025-12-22

Overview

The Compare workflow in StellaOps enables you to analyze what changed between two container image versions from a security perspective. Instead of reviewing entire vulnerability lists, you focus on material risk changes — the delta that matters for security decisions.

When to Use Compare

Use the Compare view when you need to:

• Evaluate a new release before deploying to production
• Understand risk delta between current and previous versions
• Investigate policy gate failures to see what caused blocking
• Review security posture changes after dependency updates
• Audit compliance by verifying what changed and why

Accessing the Compare View

From Release Details

1. Navigate to Releases → Select a release
2. Click the Compare button in the release header
3. The system automatically selects the recommended baseline

From Build/Artifact

1. Navigate to Scans → Select a scan
2. Click Compare with baseline
3. Select a baseline from the recommended options

Direct URL

/compare/{currentDigest}/{baselineDigest}

Understanding the Interface

Baseline Selector

At the top of the Compare view, you'll see the baseline selector:

Comparing: [myapp:v2.1.0] → [Select baseline ▼]
                                  ├── Last Green Build (Recommended)
                                  ├── Previous Release (v2.0.0)
                                  ├── Main Branch
                                  └── Custom...

Baseline Options:

• Last Green Build: Most recent version that passed all security gates
• Previous Release: The version tagged before the current one
• Main Branch: Latest scan from the main/master branch
• Custom: Manually select any previous scan

Baseline Rationale

Below the selector, you'll see why this baseline was chosen:

"Selected last prod release with Allowed verdict under policy P-2024-001."

This helps auditors understand the comparison context.

Delta Summary Strip

The summary strip shows high-level counts:

┌────────────┬─────────────┬──────────────┬──────────────┬─────────────┐
│ +5 added   │ -3 removed  │ ~2 changed   │ Policy: v1.2 │ Feed: 2h ago│
└────────────┴─────────────┴──────────────┴──────────────┴─────────────┘

Three-Pane Layout

Left Pane: Categories

Categories organize changes by type:

Category	Description
SBOM Changes	Component additions, removals, version changes
Reachability	Functions becoming reachable/unreachable
VEX Status	Vulnerability status changes
Policy	Policy rule trigger changes
Findings	New or resolved vulnerabilities
Unknowns	New gaps in analysis

Click a category to filter the items pane.

Middle Pane: Items

Shows individual changes sorted by risk priority:

┌─────────────────────────────────────────────────────────────┐
│ ⊕ CVE-2024-1234 · lodash@4.17.20 · +reachable    [HIGH]    │
│ ⊕ CVE-2024-5678 · requests@2.28.0 · +KEV         [CRITICAL]│
│ ⊖ CVE-2024-9999 · urllib3@1.26.0 · -reachable    [MEDIUM]  │
└─────────────────────────────────────────────────────────────┘

Change Types:

• ⊕ Added (green): New in current version
• ⊖ Removed (red): Gone from current version
• ↔ Changed (yellow): Status or value changed

Right Pane: Proof/Evidence

When you select an item, the proof pane shows:

1. Witness Path: Call path from entrypoint to vulnerable function
2. VEX Merge: How multiple VEX sources were combined
3. Policy Rule: Which rule triggered and why
4. Envelope Hashes: Cryptographic evidence for verification

Trust Indicators

The trust indicators bar shows:

Indicator	Description
Det. Hash	Determinism hash for reproducibility
Policy	Policy version used for evaluation
Feed	Vulnerability feed snapshot timestamp
Signature	DSSE signature verification status

Warning States:

• ⚠️ Stale Feed: Vulnerability data > 24h old
• ⚠️ Policy Drift: Policy changed between scans
• 🔴 Signature Invalid: Verification failed

Actionables Panel

The "What to do next" section provides prioritized recommendations:

┌─────────────────────────────────────────────────────────────────┐
│ What to do next:                                                │
│ 1. [CRITICAL] Upgrade lodash → 4.17.21          [Apply]         │
│ 2. [HIGH] Add VEX statement for urllib3         [Apply]         │
│ 3. [MEDIUM] Investigate new reachable path      [Investigate]   │
│ 4. [LOW] Resolve unknown: missing SBOM          [Investigate]   │
└─────────────────────────────────────────────────────────────────┘

Common Workflows

1. Pre-Release Security Review

Goal: Verify a release is safe to deploy

1. Open the release in the UI
2. Click Compare (defaults to last green baseline)
3. Review the delta summary:
   • New critical/high vulnerabilities?
   • Reachability increases?
   • Policy violations?
4. Examine each critical item:
   • Check witness paths
   • Review VEX status
5. Apply actionables or approve release

2. Investigating a Blocked Release

Goal: Understand why a release was blocked

1. Open the blocked release
2. Look at the Verdict chip: BLOCKED
3. Click Compare to see what changed
4. Filter to Policy category
5. Select blocking rules to see:
   • Which policy rule fired
   • Evidence that triggered it
   • Remediation options

3. Dependency Update Impact

Goal: Assess security impact of dependency updates

1. Compare current branch to main
2. Filter to SBOM Changes
3. Review component version changes:
   • Check if upgrades fix vulnerabilities
   • Check if new vulnerabilities introduced
4. Filter to Findings for net impact

4. Auditor Verification

Goal: Verify security claims are accurate

1. Open the Compare view
2. Check Trust Indicators:
   • Signature valid?
   • Feed current?
   • Policy version expected?
3. Click Copy Replay Command
4. Run replay locally to verify determinism
5. Download Evidence Pack for records

Understanding Evidence

Witness Paths

Witness paths show how vulnerable code is reachable:

main() [entrypoint]
  ↓
parseConfig()
  ↓
loadJson()
  ↓
yaml.load() [sink - CVE-2024-1234]

Confidence: CONFIRMED
Gates: input_validation, sandboxing

Confidence Tiers:

• CONFIRMED: Call path verified through multiple sources
• LIKELY: High-confidence static analysis
• PRESENT: Function exists but reachability uncertain

VEX Merge Explanation

When multiple VEX sources exist, the merge shows how they combined:

┌─────────────────────────────────────────────────────────┐
│ VEX Status: NOT_AFFECTED                                │
│ Strategy: priority                                      │
│                                                         │
│ Sources:                                                │
│ ★ [vendor] RedHat RHSA-2024:1234 - not_affected    P1  │
│   [distro] Ubuntu USN-5678-1 - affected            P2  │
│   [internal] Team assessment - not_affected        P3  │
│                                                         │
│ Resolution: Vendor claim takes priority                 │
└─────────────────────────────────────────────────────────┘

Determinism Verification

To verify a comparison is reproducible:

1. Copy the replay command from Trust Indicators
2. Run locally:

   stellaops smart-diff replay \
     --base sha256:abc123... \
     --target sha256:def456... \
     --feed-snapshot sha256:feed789... \
     --policy sha256:policy012...
   

3. Compare the determinism hash

Role-Based Views

Developer View (Default)

Focus: What do I need to fix?

• Default Tab: Actionables
• Visible: Upgrade suggestions, witness paths
• Hidden: Detailed attestations, policy internals

Security View

Focus: Are the security claims valid?

• Default Tab: Claims/VEX
• Visible: VEX merge, policy reasoning, claim sources
• Hidden: Low-level attestation details

Audit View

Focus: Can I verify these claims?

• Default Tab: Attestations
• Visible: Signatures, replay commands, evidence pack
• Hidden: Actionables (read-only mode)

Exporting Reports

JSON Export

Click Export → JSON to download:

• Full delta with all items
• Evidence references
• Trust indicators
• Actionables

PDF Export

Click Export → PDF for a formatted report including:

• Executive summary
• Delta breakdown by category
• Critical findings
• Remediation recommendations

SARIF Export

Click Export → SARIF for CI/CD integration:

• SARIF 2.1.0 format
• Compatible with GitHub Security, Azure DevOps
• Includes rule IDs for automation

Keyboard Shortcuts

Key	Action
Tab	Move between panes
↑/↓	Navigate items
Enter	Select/expand item
Esc	Close expanded detail
C	Copy replay command
E	Export menu

Troubleshooting

"No baseline available"

The system couldn't find a suitable baseline because:

• This is the first scan of this image
• No previous scans passed policy gates

Solution: Use "Custom" to manually select any previous scan.

"Stale feed warning"

The vulnerability feed is more than 24 hours old.

Impact: New CVEs may not be reflected in the comparison.

Solution:

1. Trigger a feed refresh
2. Re-run comparison after refresh

"Signature verification failed"

The DSSE envelope signature couldn't be verified.

Causes:

• Key rotation occurred
• Attestation was modified
• Network issue fetching public key

Solution:

1. Check if keys were recently rotated
2. Try offline verification with local key
3. Contact security team if persistent

Related Documentation

• Smart-Diff CLI Reference
• Smart-Diff UI Architecture
• SARIF Integration Guide
• Deterministic Replay Specification