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:
   ```bash
   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](../cli/smart-diff-cli.md)
- [Smart-Diff UI Architecture](../modules/web/smart-diff-ui-architecture.md)
- [SARIF Integration Guide](../ci/sarif-integration.md)
- [Deterministic Replay Specification](../replay/DETERMINISTIC_REPLAY.md)