Frontend gaps fill work. Testing fixes work. Auditing in progress.
This commit is contained in:
StellaOps Bot
307
docs/modules/sbomservice/lineage/ui-architecture.md
Normal file
307
docs/modules/sbomservice/lineage/ui-architecture.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# 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
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
1. Click pin icon on any verdict/finding
|
||||
2. Explanation captures current state with hash
|
||||
3. Export as Markdown/JSON for JIRA/ServiceNow
|
||||
|
||||
### 7.2 Ticket Export Format
|
||||
|
||||
```markdown
|
||||
## 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 |
|
||||
|
||||
## 10. Related Documentation
|
||||
|
||||
- [SbomService Lineage API](../sbomservice/lineage/architecture.md)
|
||||
- [UI Architecture](../ui/architecture.md)
|
||||
- [Graph Module Architecture](../graph/architecture.md)
|
||||
Reference in New Issue
Block a user