9.0 KiB
9.0 KiB
Lineage Smart-Diff UI Architecture
Sprint: SPRINT_20251229_001_FE_lineage_smartdiff_overview Last Updated: 2025-12-29
1. Overview
The Lineage Smart-Diff feature provides a comprehensive UI for visualizing SBOM lineage graphs, comparing artifact versions, and explaining security state changes between builds.
1.1 Completion Status
| Area | Completion | Notes |
|---|---|---|
| Lineage Graph SVG | 95% | Full DAG visualization with lanes, pan/zoom, nodes |
| Hover Cards | 85% | Basic info displayed; needs CGS integration |
| SBOM Diff View | 90% | 3-column diff exists; needs row expanders |
| VEX Diff View | 90% | Status change display; needs reachability gates |
| Compare Mode | 85% | Three-pane layout exists; needs explainer timeline |
| Export Dialog | 80% | Basic export; needs audit pack format |
| Proof Tree | 75% | Merkle tree viz; needs confidence breakdown |
| Reachability Diff | 60% | Basic view; needs gate visualization |
2. UI Data Contracts
2.1 CGS/Lineage API Integration
// Lineage Graph Response
interface LineageGraph {
artifact: string;
nodes: LineageNode[];
edges: LineageEdge[];
metadata: {
totalNodes: number;
maxDepth: number;
generatedAt: string;
};
}
interface LineageNode {
id: string;
artifactDigest: string;
artifactRef: string;
sequenceNumber: number;
createdAt: string;
source: string;
parentDigests: string[];
badges: {
newVulns: number;
resolvedVulns: number;
signatureStatus: 'valid' | 'invalid' | 'unknown';
reachabilityStatus: 'analyzed' | 'pending' | 'unavailable';
};
replayHash: string;
cgsHash?: string;
}
interface LineageEdge {
fromDigest: string;
toDigest: string;
relationship: 'parent' | 'build' | 'base' | 'derived';
}
2.2 Diff Response Schema
interface LineageDiffResponse {
fromDigest: string;
toDigest: string;
sbomDiff: {
added: ComponentDiff[];
removed: ComponentDiff[];
versionChanged: VersionChange[];
licenseChanged: LicenseChange[];
};
vexDiff: VexDelta[];
reachabilityDiff: ReachabilityDelta[];
replayHash: string;
generatedAt: string;
}
interface ComponentDiff {
purl: string;
name: string;
version: string;
ecosystem: string;
license?: string;
scope: 'runtime' | 'development' | 'optional';
}
interface VersionChange {
purl: string;
name: string;
fromVersion: string;
toVersion: string;
changeType: 'upgrade' | 'downgrade' | 'patch';
}
interface VexDelta {
cveId: string;
purl: string;
fromStatus: VexStatus;
toStatus: VexStatus;
justification?: string;
effectiveAt: string;
}
interface ReachabilityDelta {
cveId: string;
purl: string;
fromReachable: boolean;
toReachable: boolean;
paths?: string[][];
}
3. Explainer Timeline Requirements
3.1 Engine Steps
The explainer timeline shows the sequence of analysis steps:
| Step | Description | Visual Cue |
|---|---|---|
| SBOM Parse | Initial SBOM ingestion | Document icon |
| Component Match | CVE-to-component matching | Link icon |
| VEX Lookup | VEX document resolution | Shield icon |
| Reachability | Call graph analysis | Graph icon |
| Policy Gate | Policy rule evaluation | Gate icon |
| Verdict | Final determination | Checkmark/X |
3.2 Data Binding
interface ExplainerStep {
stepId: string;
stepType: 'sbom_parse' | 'component_match' | 'vex_lookup' |
'reachability' | 'policy_gate' | 'verdict';
timestamp: string;
duration: number;
status: 'success' | 'warning' | 'error';
inputs: Record<string, unknown>;
outputs: Record<string, unknown>;
evidence?: {
type: string;
hash: string;
downloadUrl?: string;
};
}
4. Node Diff Table UX
4.1 Expander Pattern
Each diff row can expand to show:
- Full component details (license, scope, dependencies)
- CVE associations and status
- Reachability paths (if analyzed)
- VEX statements affecting the component
4.2 Visual Design
┌─────────────────────────────────────────────────────────────┐
│ Component │ Before │ After │ Status│
├─────────────────────────────────────────────────────────────┤
│ ▶ lodash │ 4.17.20 │ 4.17.21 │ ↑ │
│ └─ CVE-2021-23337 (fixed in 4.17.21) │
│ └─ License: MIT │
├─────────────────────────────────────────────────────────────┤
│ ▶ axios │ 0.21.1 │ 0.21.4 │ ↑ │
├─────────────────────────────────────────────────────────────┤
│ ▶ express │ - │ 4.18.2 │ + NEW │
└─────────────────────────────────────────────────────────────┘
5. Reachability Gate Diff UI
5.1 Visual Cues
| Gate Status | Icon | Color |
|---|---|---|
| Reachable | ● | Red |
| Not Reachable | ○ | Green |
| Unknown | ? | Gray |
| Changed | ↔ | Orange |
5.2 Path Display
When reachability changes, show the call path:
entrypoint.ts → handler.ts → vulnerable_fn.ts → lodash.get()
6. Audit Pack Export UI
6.1 Export Options
| Option | Description | Default |
|---|---|---|
| Include SBOMs | Both before/after SBOMs | ✓ |
| Include Diff | Component/VEX/reachability diff | ✓ |
| Include Attestations | DSSE envelopes | ✓ |
| Include Evidence | Supporting evidence files | ✗ |
| Sign Bundle | Sign with tenant key | ✓ |
6.2 Manifest Schema
{
"version": "1.0",
"generatedAt": "2025-12-29T10:00:00Z",
"artifactA": { "digest": "sha256:...", "name": "...", "createdAt": "..." },
"artifactB": { "digest": "sha256:...", "name": "...", "createdAt": "..." },
"contents": [
{ "type": "sbom", "filename": "before.cdx.json", "sha256": "..." },
{ "type": "sbom", "filename": "after.cdx.json", "sha256": "..." },
{ "type": "diff", "filename": "diff.json", "sha256": "..." },
{ "type": "attestation", "filename": "attestations.dsse.json", "sha256": "..." }
],
"merkleRoot": "sha256:...",
"summary": {
"componentsAdded": 5,
"componentsRemoved": 2,
"vexUpdates": 3,
"attestationCount": 2
}
}
7. Copy-Safe Workflow
7.1 Pinned Explanation UX
Operators can "pin" explanations for ticket export:
- Click pin icon on any verdict/finding
- Explanation captures current state with hash
- Export as Markdown/JSON for JIRA/ServiceNow
7.2 Ticket Export Format
## Security Finding Report
**Artifact**: myorg/myapp:v1.2.3 (sha256:abc123...)
**Generated**: 2025-12-29T10:00:00Z
**Replay Hash**: sha256:def456...
### Finding: CVE-2021-23337 in lodash
| Field | Value |
|-------|-------|
| Status | Not Affected |
| Reason | Not Reachable |
| Evidence | Call graph analysis |
| VEX ID | VEX-2025-001 |
### Verification
To reproduce this verdict:
stella verdict replay --hash sha256:def456...
8. Confidence Breakdown Charts
8.1 Metrics Sources
| Metric | Source | Weight |
|---|---|---|
| SBOM Completeness | Scanner analysis | 30% |
| VEX Coverage | VEX Hub aggregation | 25% |
| Reachability Depth | Call graph analysis | 25% |
| Attestation Count | Sigstore/local | 20% |
8.2 Visualization
- Donut chart showing confidence breakdown
- Hover for detailed explanations
- Color coding: Green (>80%), Yellow (50-80%), Red (<50%)
9. Component Inventory
9.1 Lineage Feature Components
| Component | Location | Status |
|---|---|---|
LineageGraphComponent |
lineage-graph.component.ts |
Complete |
LineageNodeComponent |
lineage-node.component.ts |
Complete |
LineageEdgeComponent |
lineage-edge.component.ts |
Complete |
LineageHoverCardComponent |
lineage-hover-card.component.ts |
Needs CGS |
LineageMiniMapComponent |
lineage-minimap.component.ts |
Complete |
LineageControlsComponent |
lineage-controls.component.ts |
Complete |
LineageSbomDiffComponent |
lineage-sbom-diff.component.ts |
Needs expanders |
LineageVexDiffComponent |
lineage-vex-diff.component.ts |
Needs gates |
LineageCompareComponent |
lineage-compare.component.ts |
Needs timeline |
LineageExportDialogComponent |
lineage-export-dialog.component.ts |
Needs audit pack |