git.stella-ops.org/docs/product-advisories/21-Dec-2025 - Smart Diff - Reproducibility as a Feature.md

Yes — you need dedicated UI affordances for “Verdict + DeltaVerdict + Evidence” because the interaction model is fundamentally different from a classic “vulnerability list” UI. But you do not necessarily need a whole new top‑level product area on day one.

The right approach is usually:

1. Embed the experience where decisions happen (build/release/PR gates).
2. Add one dedicated “Compare / Delta” screen (a focused view) reachable from those contexts.
3. Introduce a top-level “Assurance/Audit” workspace only if you have compliance-heavy users who need cross-project oversight.

Below is a concrete way to implement both options and when to choose each.

---

When a dedicated UI is warranted

A dedicated UI is justified if at least two of these are true:

• You have multiple repos/services and security/compliance need to see fleet-wide deltas, not just per build.
• You need approval workflows (exceptions, risk acceptance, “ship with waiver”).
• You need auditor-grade artifact browsing: signatures, provenance, replay, evidence packs.
• Developers complain about “scan noise” and need diff-first triage to be fast.
• You have separate personas: Dev, Security, Compliance/Audit — each needs different default views.

If those aren’t true, keep it embedded and light.

---

Recommended approach (most teams): Dedicated “Compare view” + embedded panels

Where it belongs in the existing UI

Assuming your current navigation is something like:

Projects → Repos → Builds/Releases → Findings/Vulnerabilities

Then “DeltaVerdict” belongs primarily in Build/Release details, not in the global vulnerability list.

Add two key entry points:

1. A status + delta summary on every Build/Release page (above the fold).
2. A Compare action that opens a dedicated comparison screen (or tab).

Information architecture (practical, minimal)

On the Build/Release details page, add a header section:

• Verdict chip: Allowed / Blocked / Warn

• Delta chip: “+2 new exploitable highs”, “Reachability flip: yes/no”, “Unknowns: +3”

• Baseline: “Compared to: v1.4.2 (last green in prod)”

• Actions:

  • Compare (opens dedicated delta view)
  • Download Evidence Pack
  • Verify Signatures
  • Replay (copy command / show determinism hash)

Then add a tab set:

• Delta (default)
• Components (SBOM)
• Vulnerabilities
• Reachability
• VEX / Claims
• Attestations (hashes, signatures, provenance)

Why “Delta” should be the default tab

The user’s first question in a release is: What changed that affects risk? If you make them start in a full vuln list, you rebuild the noise problem.

---

How the dedicated “Compare / Delta” view should work

Think of it as a “git diff”, but for risk and provenance.

1) Baseline selection (must be explicit and explainable)

Top of the Compare view:

• Base selector (default chosen by system):

  • “Last green verdict in same environment”
  • “Previous release tag”
  • “Parent commit / merge-base”

• Head selector:

  • Current build/release

• Show why the baseline was chosen (small text): “Selected last prod release with Allowed verdict under policy P123.”

This matters because auditors will ask “why did you compare against that?”

2) Delta summary strip (fast triage)

A horizontal strip with only the key deltas:

• New exploitable vulns: N (by severity)
• Reachability flips: N (new reachable / newly unreachable)
• Component changes: +A / −R / ~C
• VEX claim flips: N
• Policy/feed drift: policy changed? feed snapshot changed? stale?

3) Three-pane layout (best for speed)

Left: Delta categories (counts)

• New exploitable vulns
• Newly reachable
• Component adds/removes
• Changed versions
• Claim changes
• Unknowns / missing data

Middle: List of changed items (sorted by risk)

• Each item shows: component, version, CVE (if applicable), exploitability, reachability, current disposition (VEX), gating rule triggered

Right: Proof / explanation panel

• “Why is it blocked?”

• Shows:

  • the policy rule that fired (with rule ID)
  • the witness path for reachability (minimal path)
  • the claim sources for VEX (vendor/distro/internal) and merge explanation
  • links to the exact envelope hashes involved

This is where “proof-carrying” becomes usable.

4) Actionables output (make it operational)

At the top of the item list include a “What to do next” section:

• Upgrade component X → version Y
• Patch CVE Z
• Add/confirm VEX claim with evidence
• Reduce reachability (feature flag, build config)
• Resolve unknowns (SBOM missing for module A)

This prevents the compare screen from becoming yet another “informational dashboard.”

---

If you do NOT create any new dedicated view

If you strongly want zero new screens, the minimum acceptable integration is:

• Add a Delta toggle on the existing Vulnerabilities page:

  • “All findings” vs “Changes since baseline”

• Add a baseline selector on that page.

• Add an Attestations panel on the Build/Release page for evidence pack + signature verification.

This can work, but it tends to fail as the system grows because:

• Vulnerability list UIs are optimized for volume browsing, not causal proof
• Reachability and VEX explanation become buried
• Auditors still need a coherent “verdict story”

If you go this route, at least add a “Compare drawer” (modal) that shows the delta summary and links into filtered views.

---

When you SHOULD add a top-level dedicated UI (“Assurance” workspace)

Create a dedicated left-nav item only when you have these needs:

1. Cross-project oversight: “show me all new exploitable highs introduced this week across org.”
2. Audit operations: evidence pack management, replay logs, signature verification at scale.
3. Policy governance: browse policy versions, rollout status, exceptions, owners.
4. Release approvals: security sign-off steps, waivers, expiry dates.

What that workspace would contain

• Overview dashboard

  • blocked releases (by reason)
  • new risk deltas by team/repo
  • unknowns trend
  • stale feed snapshot alerts

• Comparisons

  • search by repo/build/tag and compare any two artifacts

• Attestations & Evidence

  • list of verdicts/delta verdicts with verification status
  • evidence pack download and replay

• Policies & Exceptions

  • policy versions, diffs, who changed what
  • exceptions with expiry and justification

This becomes the home for Security/Compliance, while Devs stay in the build/release context.

---

Implementation details that make the UI “work” (avoid common failures)

1) Idempotent “Compute delta” behavior

When user opens Compare view:

• UI requests DeltaVerdict by {base_verdict_hash, head_verdict_hash, policy_hash}.
• If not present, backend computes it.
• UI shows deterministic progress (“pending”), not “scanning…”.

2) Determinism and trust indicators

Every compare screen should surface:

• Determinism hash
• Policy version/hash
• Feed snapshot timestamp/age
• Signature verification status

If verification fails, the UI must degrade clearly (red banner, disable “Approved” actions).

3) Baseline rules must be visible

Auditors hate “magic.” Show baseline selection logic and allow override.

4) Don’t show full graphs by default

Default to:

• minimal witness path(s)
• minimal changed subgraph
• expand-on-demand for deep investigation

5) Role-based access

• Developers: see deltas, actionables, witness paths
• Security: see claims sources, merge rationale, policy reasoning
• Audit: see signatures, replay, evidence pack

---

Decision recommendation (most likely correct)

• Build embedded panels + a dedicated Compare/Delta view reachable from Build/Release and PR checks.
• Delay a top-level “Assurance” workspace until you see real demand from security/compliance for cross-project oversight and approvals.

This gives you the usability benefits of “diff-first” without fragmenting navigation or building a parallel UI too early.

If you share (even roughly) your existing nav structure (what pages exist today), I can map the exact placements and propose a concrete IA tree and page wireframe outline aligned to your current UI.