image-sbom¶
On a tag pipeline, after the job that pushed the image, builds a CycloneDX SBOM
of that tag and links it from the tag's release as sbom.json. The link's
name is fixed, because that is what the images docs site reads; the URL behind
it can move.
| job | runs in | does |
|---|---|---|
image-sbom |
trivy | trivy image --format cyclonedx on the published tag; keeps the SBOM as an artifact |
image-sbom:attach |
ci-base | checks the SBOM, waits for the release, uploads it, links it |
There are two jobs because no one image holds both halves: the trivy image has no curl or jq, and ci-base has no trivy.
What image-sbom:attach checks¶
Before anything is written:
- The digest. It asks the registry which digest the tag points at, and
requires the SBOM to record that same
image@digest(aquasecurity:trivy:RepoDigest). So the SBOM describes the exact image a consumer pulls, and it must be that whole line, not one containing it. Exit 4 if not: the tag moved, or trivy read something else. - The floor. At least 10 components. A valid but nearly empty SBOM would otherwise pass everything. The smallest image in the estate lists 197. Exit 3 if not.
- The release. The release tool tags first and creates the release
seconds later, so a 404 waits, up to
release_waitseconds; exit 5 if it never appears. A 401 or 403 fails at once with exit 6, and any other status at once with exit 1.
Then it uploads the file to the project's generic package registry as
sbom/<tag>/sbom.json, and creates the sbom.json release link, of type
other, pointing at it. A retried job or a re-run tag pipeline finds the
link by name and updates it. The package gains a second file, and its
download serves the newest. In a public project that download needs no
credentials.
Exit codes¶
| code | meaning |
|---|---|
| 0 | the SBOM is uploaded and linked |
| 1 | anything else: a failed upload or link write, a registry or trivy failure, a malformed SBOM, a variant under the default job name |
| 2 | a variable the job needs is unset (the shell's own exit) |
| 3 | fewer than 10 components |
| 4 | the SBOM does not record the registry's digest for the tag |
| 5 | no release for the tag within release_wait seconds |
| 6 | the token got 401 or 403 reading the release |
Every curl call is checked, so curl's own exit codes, such as 22, never reach the job.
A retried :attach runs as whoever retries it
The job token carries the permissions of the account that ran or retried the pipeline. Changing a release on a protected tag needs the tag's own access, not a project role: on the phpboyscout images only the release accounts have it, and a Maintainer is refused too. Anyone else who retries the job gets exit 6 or a failed link write, so only an account the tag protection admits should retry it.
Inputs¶
| input | type | default | |
|---|---|---|---|
stage |
string | publish |
Stage for both jobs. You must declare it. |
name |
string | image-sbom |
Job name; the jobs are <name> and <name>:attach. A second include must set its own, or GitLab merges the two; a variant under the default name fails. |
variant |
string | "" |
ndk reads the <tag>-ndk image and names the file sbom-ndk.json. An include that sets it must also set name. |
publish_job |
string | publish:semver |
The job that pushes the tag. <name> needs: it, so a tag that publishes nothing gets no SBOM. |
image_name |
string | $CI_REGISTRY_IMAGE |
The image, without its tag. It must be in this project's registry. |
trivy_image |
string | ghcr.io/aquasecurity/trivy:0.73.0 |
Trivy image <name> runs in. |
image_version |
string | "v0.3.5" |
phpboyscout/images/ci-base tag <name>:attach runs in. |
token |
string | $CI_JOB_TOKEN |
Token for the release and package APIs. The job token is sent as JOB-TOKEN, anything else as PRIVATE-TOKEN. |
release_wait |
number | 300 |
Seconds to wait for the tag's release. |
if |
string | $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/ |
rules:if: for both jobs. Keep it in step with the publish job's own rule: on a tag where the publish job is absent, GitLab refuses to create the pipeline, because image-sbom needs it. |
No vulnerability scan runs, so neither job needs the trivy DB or the
trivy-cache runner. Vulnerabilities belong to image-scan:
they change daily, and the SBOM does not.
Usage¶
The examples pin a release, as a consumer outside the estate should.
Repositories in the phpboyscout estate include it at @main instead, like
every other cicd component.
stages: [lint, build, scan, release, publish]
include:
- component: gitlab.com/phpboyscout/cicd/[email protected]
An image with a variant tag includes it twice, each with its own name. Put the variant include after the plain one: if it comes first and is left without a name, the plain include silently replaces it, and sbom-ndk.json never appears.
include:
- component: gitlab.com/phpboyscout/cicd/[email protected]
- component: gitlab.com/phpboyscout/cicd/[email protected]
inputs:
name: "image-sbom:ndk"
variant: ndk
publish_job: "publish:semver:ndk"
When the image is published from a child pipeline, include it there and name
that pipeline's publishing job, for example publish_job: "retag:semver".
What the self-test cannot prove¶
The writes. The self-test runs both jobs for real against ci-base's
published tag, through the digest and floor checks, and must stop at exit 5:
it points at no project, so no release appears and nothing is written. The
upload and the link are proved at the first consumer's tag pipeline.
Whether a job token may create a link on a release whose tag is protected is part of that. The token acts as whoever triggered the pipeline.
See also¶
image-scan, which scans the same image for advisories- Spec 0134