docs: Backstage + Dependency-Track coverage portal design (spec + ADR 0035)#142
Draft
trivoallan wants to merge 2 commits into
Draft
docs: Backstage + Dependency-Track coverage portal design (spec + ADR 0035)#142trivoallan wants to merge 2 commits into
trivoallan wants to merge 2 commits into
Conversation
Brainstorm capture of the consumption surface for houba's "coverage gates value" thesis: a developer-scoped Backstage (TechInsights) portal that scores per-service provenance coverage off the houba stamp and surfaces vuln posture via Dependency-Track, with a bottom-up "onboard" demand signal (PR against the MirrorPolicy repo). Key design points captured: - Denominator = a base.digest chain walk (read OCI base.* annotations), NOT a Dockerfile FROM parse — dissolves the ARG/multi-stage/multi-file gotcha. - Provenance (manifest stamp) survives Harbor's internal fan-out; OCI 1.1 referrers (SBOM/signature) do NOT replicate on Harbor <=2.15.x (issue #23210), so coverage follows the identical digest to the attachment site. - First-party images excluded via the Backstage catalog oracle (no convention). - The portal consumes `houba audit` (digest-keyed) rather than re-walking the registry. Artifacts: spec under docs/superpowers/specs/; ADR 0035 (0034 is taken by the merged unify-SBOM-on-syft); C4 adds backstage + dependencyTrack (External/Downstream); design.md notes them as downstream consumers; scripts/stick-test.sh demonstrates the referrer-propagation mechanism. Design only; no houba code. Two small houba-side asks noted (a `digest` field on audit's CoverageOutcome; an `--sbom` audit tier). Co-Authored-By: Claude <noreply@anthropic.com>
…t embedded card The DT half of the coverage portal assumed a digest-keyed DT join as a settled "Decision 8". Two facts dissolve that: the org's DT taxonomy is undecided and DT is greenfield with no ingestion owner, and houba — by its own boundary (ADR 0032, no HTTP layer) — never writes to DT, so it has no standing to decide DT's keying. Reframe the vuln surface by plane, not audience: DT computes vuln posture, Backstage presents coverage. The owner clicks through a digest deep-link to DT's own frontend (already deployed) — no embedded card, no findings API, no DT credentials on the FactRetriever path. houba only emits the digest as the join key (the existing §7 CoverageOutcome ask). The keying + ingestion ownership are org decisions, captured as OPEN with the cheapest next check named (does DT's frontend route by name+version or only by project UUID, which would need one read-only project/lookup). Decisions 1-7 (the coverage portal) are unaffected. - spec §8: rewritten from "join by digest" to the deep-link/open-question framing. - spec §7: soften the one clause asserting DT is digest-keyed. - ADR 0035: mirror the demotion. - workspace.dsl: the backstage -> dependencyTrack edge is now a deep-link, not an API drill-in. Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Brainstorm capture of the consumption surface for houba's coverage gates value thesis: a
developer-scoped Backstage (TechInsights) portal that scores per-service provenance coverage off
the houba stamp and surfaces vuln posture via Dependency-Track, with a bottom-up "onboard"
demand signal (a PR against the MirrorPolicy repo). Design only — no houba code changes.
This wires the Backstage integration that ADR 0030 deferred, and builds on the both-paths SBOM
referrer from #140 (this branch is rebased on it, so the cross-references resolve).
What changed
docs/superpowers/specs/2026-06-17-backstage-coverage-portal-design.md(the full design).0034is taken by the merged unify-SBOM-on-syft, so this is 0035.workspace.dsladdsbackstage+dependencyTrackas External/Downstream systems +relationships (Landscape/Context use
include *).scripts/stick-test.sh— a self-contained validation harness (regctl only) demonstrating thereferrer-propagation mechanism.
Key design decisions
base.digestchain walk, not a DockerfileFROMparse — read the OCIbase.*annotations buildx stamps; dissolves the ARG / multi-stage / multi-file gotcha.≤2.15.x does not replicate OCI 1.1 referrers (SBOM/cosign-v3) — goharbor/harbor#23210, open. So coverage follows the identical digest to the attachment site (entry namespace / Dependency-Track, both digest-keyed). (Zot's sync does propagate them — the gap is Harbor-specific.)
houba audit(digest-keyed) rather than re-walking the registry — no registry credentials in Backstage.Reviewer notes
digestfield onaudit'sCoverageOutcome(the join key), and an--sbomaudit tier (the SBOM bar).docs/architecture/_export/*.mmdfromworkspace.dsl(Structurizr CLI; no Make target / CI drift-check today).
🤖 Generated with Claude Code