DHI: mirror referrers + SBOM-based scanning for hardened images#57
Merged
Conversation
- _mirror-image.yml: opt-in copy_referrers input copies image + referrers with oras (index, per-platform children, and their referrers). Default off; existing crane-only mirrors unaffected. - mirror-hardened-python.yml: enable copy_referrers. - _diag-dhi-discover.yml: temporary push-triggered diagnostic to learn the real DHI cosign-attestation/referrer layout (to be deleted before merge). Refs #54, #55
Add _scan-sbom-image.yml, a reusable scan/gate/promote workflow tailored to distroless Docker Hardened Images (DHI), which carry no package-manager metadata and cannot be scanned with `trivy image`. Instead it: - enumerates every platform in the image index, - locates each platform's SBOM referrer (an in-toto attestation whose in-toto.io/predicate-type annotation matches the configurable sbom_predicate_type, default CycloneDX) pulled from GHCR quarantine, - extracts the embedded SBOM predicate and scans it with `trivy sbom`, - applies the severity threshold plus CVE exception list across ALL platforms (blocks promotion if any platform fails or its SBOM is missing), - promotes passing images with `oras cp -r` (carrying image + all referrers), - attaches an OCI scan-report referrer recording the SBOM-based method, and - deletes the promoted tag from quarantine. Repoint scan-hardened-python.yml at the new workflow and expose a sbom_predicate_type choice input (CycloneDX / SPDX). Refs #54, #56
- image-mirror-workflows.md: document source_login_registry, copy_referrers (oras cp -r), and the authenticated-source / referrer-copy capabilities. - scan-and-promote-workflows.md: add the "SBOM-based scanning for hardened images" section covering _scan-sbom-image.yml, the sbom_predicate_type input, per-platform SBOM extraction, all-platforms gating, and referrer-preserving promotion; refresh the file listing and the signing/attestation note. - Remove the temporary _diag-dhi-discover.yml diagnostic workflow. Refs #54, #55, #56
There was a problem hiding this comment.
Pull request overview
This PR redesigns the Docker Hardened Images (DHI) mirroring and scanning automation so that OCI referrer attestations (SBOM/provenance/VEX/signatures) are preserved during mirroring and promotion, and vulnerability gating is performed against the SBOM attestation (trivy sbom) rather than the distroless image filesystem.
Changes:
- Add optional referrer-copy support to the reusable mirror workflow (
copy_referrers), usingoras cp -rto preserve OCI referrers. - Introduce a new reusable SBOM-based scanning workflow (
_scan-sbom-image.yml) and repoint the hardened Python scanner to it. - Update workflow documentation to describe the new referrer-mirroring and SBOM-scanning paths.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/architecture/workflows/scan-and-promote-workflows.md | Documents the new SBOM-based scanning workflow and hardened promotion path. |
| docs/architecture/workflows/image-mirror-workflows.md | Documents copy_referrers + authenticated source login for mirroring. |
| .github/workflows/scan-hardened-python.yml | Switches hardened python scanning to _scan-sbom-image.yml and adds an SBOM predicate selector. |
| .github/workflows/mirror-hardened-python.yml | Enables copy_referrers for the hardened python mirror. |
| .github/workflows/_scan-sbom-image.yml | New reusable workflow: per-platform SBOM discovery/extraction + trivy sbom gate + referrer-preserving promotion. |
| .github/workflows/_mirror-image.yml | Adds copy_referrers + optional ORAS install/login and ORAS-based copy path for referrers. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- _mirror-image.yml: skip the digest short-circuit when copy_referrers=true. OCI referrers (SBOM/VEX/provenance/signatures) can change independently of the subject manifest digest, so a matching image digest no longer reports "up to date" in that mode; the referrer-aware copy is re-run (oras cp is idempotent), with an adjusted log message. - _scan-sbom-image.yml: make the per-platform detail table reflect gate semantics. Compute a per-platform blocking count by subtracting the exception list from the findings, list only blocking CVE IDs, and rename the column header to "Blocking CVE IDs". The "CVEs >= threshold" column keeps the raw per-platform total. Refs #55, #56
An `oras cp -r` fans out many blob requests; some registries (notably dhi.io) intermittently return a transient "not found"/5xx for one of them, which otherwise fails the whole mirror/promotion. Wrap the referrer-aware copies in a bounded retry with exponential backoff (4 attempts, 5s/10s/20s) in both _mirror-image.yml and _scan-sbom-image.yml. Refs #55, #56
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
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.
Summary
Redesigns the mirror and scan workflows for Docker Hardened Images (DHI) so that
attestations travel with the image and the vulnerability gate runs against the
SBOM instead of the (distroless) image filesystem.
DHI images carry no package-manager metadata, so
trivy imagecannot enumeratetheir packages. Their package inventory lives in an SBOM attestation attached to
each platform manifest as an OCI referrer. This PR mirrors those referrers into
quarantine and gates promotion on the SBOM.
Changes
Mirror — copy referrers (general capability)
_mirror-image.yml: new opt-incopy_referrersinput. When enabled, the copyuses
oras cp -rfor the index and each per-platform child manifest, soall referrers (SBOMs, provenance, VEX, signatures) are copied. Default off;
existing crane-only mirrors are unchanged. Works for any image with
referrers, not just DHI.
mirror-hardened-python.yml: enablescopy_referrers.Scan — SBOM-based gate (
_scan-sbom-image.yml)locates the SBOM referrer whose
in-toto.io/predicate-typematchessbom_predicate_type(default CycloneDX, SPDX selectable), extracts theembedded BOM, and scans it with
trivy sbom.or if a platform's SBOM is missing).
oras cp -r(image + all referrers), attaches anapplication/vnd.cssc.scan-report.v1+jsonreferrer (now recordingcom.cssc.scan.method=sbomand the predicate type), and deletes the sourcetag from quarantine.
scan-hardened-python.yml: repointed at the new workflow with asbom_predicate_typechoice input.Docs
image-mirror-workflows.md: documentssource_login_registry,copy_referrers, and the oras-based copy path.scan-and-promote-workflows.md: new "SBOM-based scanning for hardened images"section.
Validation
shellcheck -S warning.copy_referrerspopulated quarantine with the full DHIattestation set.
linux/amd64andlinux/arm64SBOMs found and scanned (0missing), 0 CVEs ≥ HIGH.
base/hardened/python:3.14-alpine3.23with all referrerscopied, scan-report attached, and the quarantine tag deleted.
Closes #54
Closes #55
Closes #56