Upstream Status Integration PRD

CascadeGuard tracks hardened copies of upstream base images (ubuntu, node, python, etc.). Today, the UI only shows our patched image status. This plan adds upstream visibility so users can see how our hardened images compare to upstream.

Design principle: Upstream data is context, not clutter. Show it where it makes our value obvious. Don’t add filtering/sorting complexity for upstream-fixed CVEs — that’s not the #1 priority.

Data Model Changes

New: upstream_sources table

Links each tracked image to its upstream registry source. Note: the same logical upstream (e.g. ubuntu:22.04) may appear in multiple registries with different digests. We track each registry/tag combination.

Column	Type	Description
id	TEXT PK	UUID
image_id	TEXT FK→images	Our tracked image
upstream_registry	TEXT	e.g. docker.io/library
upstream_name	TEXT	e.g. ubuntu
upstream_tag	TEXT	e.g. 22.04
upstream_digest	TEXT	Current upstream digest
last_checked_at	TEXT	When we last polled upstream

Multi-registry consideration: The same upstream image (e.g. ubuntu:22.04) may exist in Docker Hub, ECR Public, GHCR, Quay, etc. with different digests even for the same tag. We should:

• Track all known registry sources per upstream name:tag
• Flag digest divergence across registries
• Show which registry our rebuild is based on

New: upstream_scans table

Scan results against the unpatched upstream image.

Column	Type	Description
id	TEXT PK	UUID
upstream_source_id	TEXT FK→upstream_sources
scanner	TEXT	grype | trivy
critical	INT	Count
high	INT	Count
medium	INT	Count
low	INT	Count
total	INT	Count
scanned_at	TEXT	ISO 8601

New: upstream_events table

Upstream releases, tag updates, and security advisories.

Column	Type	Description
id	TEXT PK	UUID
upstream_source_id	TEXT FK→upstream_sources
event_type	TEXT	release | tag_update | security_advisory
version	TEXT	e.g. 22.04.4
summary	TEXT	Human-readable changelog line
published_at	TEXT	When upstream published

Extend ImageSummary / ImageDetail types

interface UpstreamInfo {
  registry: string;
  name: string;
  tag: string;
  digest: string;
  last_checked_at: string | null;
  vulnerabilities: VulnerabilityCounts;
  digest_match: boolean;
  other_registries?: { registry: string; digest: string }[];
}
 
interface ImageDetail extends ImageSummary {
  upstream: UpstreamInfo | null;
}

Extend Vulnerability type

Add fixed_upstream: boolean — whether upstream’s latest image has a fix for this CVE.

Extend ScanHistoryEntry type

Add upstream_critical, upstream_high, upstream_medium, upstream_low, upstream_total fields for dual-line charting.

New: UpstreamEvent type

interface UpstreamEvent {
  id: string;
  event_type: 'release' | 'tag_update' | 'security_advisory';
  version: string | null;
  summary: string;
  published_at: string;
}

---

UI Integration Points

1. Image Catalogue (Dashboard Grid)

Add a small upstream indicator on each ImageCard.

• Upstream CVE delta: e.g. “Upstream: 12 CVEs” vs “Ours: 3 CVEs” as compact comparison.
• “New upstream available” badge when upstream digest changed since last rebuild.
• Color-code: green (we’re ahead), yellow (same), red (upstream fixed something we haven’t rebuilt for).
• Marketing angle: The delta IS the value prop — “We eliminated 9 CVEs that upstream still has.”

2. Image Detail Header

Add an “Upstream Source” info row below the image URL.

• Upstream registry/name:tag, digest (truncated), last checked time.
• Side-by-side vuln count: “Upstream X / Ours Y” per severity.
• Badge: “Up to date” or “Rebuild available”.

3. Vulnerabilities Tab (CVE List)

Add upstream context as a column, not a filter.

• “Fixed Upstream” column (checkmark/x icon) — informational only.
• No dedicated filter button — not the #1 priority. The column provides context without UI complexity.
• Default sort remains by severity.

4. CVE History Tab (Trend Chart)

Overlay upstream trend lines on the existing chart.

• Dashed lines for upstream counts alongside our solid lines.
• Legend: “Critical (ours)” / “Critical (upstream)” etc.
• Tooltip shows both values — visually shows when upstream patches land vs when we rebuild.

5. Rebuild Log Tab (Timeline)

Interleave upstream events into the rebuild timeline.

• Upstream events get distinct icon + blue left-border (vs green/red for our rebuilds).
• Each shows: event type badge, version, summary, timestamp.
• Unified chronological view: upstream publishes → we detect → we rebuild.

6. Try-Me Page — Upstream Comparison (Key Marketing Moment)

The Try-Me page is the primary marketing surface. When a user scans a Dockerfile’s FROM image, upstream vulnerabilities should be front and center.

• Show upstream CVE posture immediately when scanning a base image.
• When CascadeGuard has a hardened version (which it SHOULD for the default example!), make a big deal about switching:
  • Side-by-side: “ubuntu:22.04 — 47 CVEs” vs “cascadeguard/ubuntu:22.04 — 3 CVEs”
  • Prominent CTA: “Switch to Secure Image” with one-click Dockerfile rewrite
  • Visual diff showing CVEs eliminated
• This is the “aha moment” — upstream shows the problem, our image shows the solution.

7. Aggregate Stats Bar (Dashboard)

• “Pending upstream patches” — count of images where upstream has newer digest or fewer CVEs.
• “Avg upstream lag” — average time between upstream fix and our rebuild.

---

Multi-Registry Handling

The same upstream image (e.g. ubuntu:22.04) often exists in Docker Hub, ECR Public, GHCR, Quay, etc. with different digests even for the same tag.

Approach:

1. Track the primary upstream source per image (the one we rebuild from).
2. Optionally track additional registries to detect divergence.
3. Show which registry our rebuild is based on in the image detail page.
4. If divergence detected, note it — informational, not alarming.

---

API Endpoints (New)

Endpoint	Method	Description
/api/images/:id/upstream	GET	Upstream source info + latest scan
/api/images/:id/upstream/history	GET	Upstream scan history (30d)
/api/images/:id/upstream/events	GET	Upstream release/advisory events

Existing endpoints extended:

• GET /api/images/:id/vulnerabilities — adds fixed_upstream field
• GET /api/images/:id/history — adds upstream counts fields
• GET /api/images / GET /api/images/:id — adds upstream object

---

Implementation Phases

Phase 1: Data Model + Ingestion

1. Add migration with new tables (upstream_sources, upstream_scans, upstream_events).
2. Add ingestion for upstream scan results.
3. Add upstream event ingestion.
4. Cross-reference upstream for fixed_upstream on existing scans.

Phase 2: API Layer

1. Extend image endpoints to include upstream info.
2. Extend vulnerabilities endpoint with fixed_upstream.
3. Extend history endpoint with upstream counts.
4. New upstream event endpoints.

Phase 3: Frontend — Core Integrations

1. Update TypeScript types.
2. ImageCard — upstream delta indicator.
3. ImageDetailPage header — upstream source info.
4. VulnerabilityList — “Fixed Upstream” column (no filter).
5. TimeToPatchChart — upstream overlay lines.
6. RebuildTimeline — interleaved upstream events.
7. Try-Me page — upstream comparison with prominent secure-image CTA.

Phase 4: Frontend — Polish

1. Aggregate stats bar.
2. Mock data for all upstream fields.
3. Responsive/mobile testing.
4. Multi-registry divergence indicators.
5. Optional: dedicated Upstream tab.

---

Where Else Upstream Info Makes Sense

• Email/Slack notifications: “Upstream ubuntu:22.04 patched CVE-2024-XXXX — rebuild recommended.”
• SLA calculation: Factor in upstream fix availability as actionable lag.
• SBOM diff: Compare our packages/versions against upstream’s to highlight patches beyond upstream.
• Dashboard-level “upstream health” view: Summary of all tracked upstreams and their CVE posture.