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

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:

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

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

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:

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

## 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

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

10. Related Documentation

• SbomService Lineage API
• UI Architecture
• Graph Module Architecture