feat: Implement distro-native version comparison for RPM, Debian, and Alpine packages
- Add RpmVersionComparer for RPM version comparison with epoch, version, and release handling. - Introduce DebianVersion for parsing Debian EVR (Epoch:Version-Release) strings. - Create ApkVersion for parsing Alpine APK version strings with suffix support. - Define IVersionComparator interface for version comparison with proof-line generation. - Implement VersionComparisonResult struct to encapsulate comparison results and proof lines. - Add tests for Debian and RPM version comparers to ensure correct functionality and edge case handling. - Create project files for the version comparison library and its tests.
This commit is contained in:
StellaOps Bot
363
docs/guides/compare-workflow-user-guide.md
Normal file
363
docs/guides/compare-workflow-user-guide.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user