Skip to content

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_wait seconds; 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