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

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

From Build/Artifact

Navigate to Scans → Select a scan
Click Compare with baseline
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:

Witness Path: Call path from entrypoint to vulnerable function
VEX Merge: How multiple VEX sources were combined
Policy Rule: Which rule triggered and why
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

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

2. Investigating a Blocked Release

Goal: Understand why a release was blocked

Open the blocked release
Look at the Verdict chip: BLOCKED
Click Compare to see what changed
Filter to Policy category
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

Compare current branch to main
Filter to SBOM Changes
Review component version changes:
- Check if upgrades fix vulnerabilities
- Check if new vulnerabilities introduced
Filter to Findings for net impact

4. Auditor Verification

Goal: Verify security claims are accurate

Open the Compare view
Check Trust Indicators:
- Signature valid?
- Feed current?
- Policy version expected?
Click Copy Replay Command
Run replay locally to verify determinism
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:

Copy the replay command from Trust Indicators

Run locally:

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