Software Bill of Materials (SBOM)

StableBuild can generate a Software Bill of Materials (SBOM) for any of your builds. The SBOM lists every Docker image, OS package, Python package and file that the build fetched through StableBuild, with its exact version and SHA-256 hash. It's a CycloneDX 1.7 JSON document, so you can feed it into the compliance tool of your choice.

SBOM is available on the Enterprise plan. If you're interested, let us know at [e-mail].

Because StableBuild serves these dependencies, the SBOM records what your build actually downloaded, rather than what a scanner infers from the finished image.

Recording downloads for a build

To tell StableBuild which build a download belongs to, add -- and a build ID (which is a string you choose) after your API key in the mirror URL. For example, your-prefix.pypimirror.stablebuild.com becomes your-prefix--build-1234.pypimirror.stablebuild.com. This works for all mirrors, and you can use the same build ID across mirrors:

FROM your-prefix--build-1234.dockermirror.stablebuild.com/python:3.12-slim

ARG SB_API_KEY=your-prefix--build-1234
ARG APT_PIN_DATE=2026-09-29T08:40:01Z

COPY ./sb-apt.sh /opt/sb-apt.sh
RUN bash /opt/sb-apt.sh load-apt-sources debian
RUN apt update && apt install -y curl

RUN pip install -i https://your-prefix--build-1234.pypimirror.stablebuild.com/2026-09-01/ requests==2.32.3

RUN curl -O "https://your-prefix--build-1234.httpcache.stablebuild.com/my-cache-key/https://bootstrap.pypa.io/get-pip.py"

Everything else about the mirrors stays the same: your pin dates, cache keys and cached files don't change when you add a build ID. Downloads without a build ID aren't recorded in an SBOM.

Using a unique build ID in CI

Give every CI run its own build ID, so each SBOM describes exactly one build. In a Dockerfile, you can pass it in as a build argument:

ARG BUILD_ID
FROM your-prefix--${BUILD_ID}.dockermirror.stablebuild.com/python:3.12-slim

ARG BUILD_ID
RUN pip install -i https://your-prefix--${BUILD_ID}.pypimirror.stablebuild.com/2026-09-01/ requests==2.32.3

And set it from your CI system, e.g. in GitHub Actions:

- name: Build container
  run: docker build --build-arg BUILD_ID=gh-${{ github.run_id }} .

The build ID is part of a hostname, so it can only contain lowercase letters, digits and hyphens (-). Your API key, -- and the build ID together must be at most 63 characters.

Generating an SBOM

1. Go to the dashboard and click Reports > SBOM.

2. Select one of your recent builds, or enter a build ID.

3. Click Generate SBOM. Your browser downloads the SBOM as sbom-<build id>.cdx.json.

Generating an SBOM for a build

What's in the SBOM

Every artifact becomes a CycloneDX component with a package URL (purl):

Mirror	Component type	Example purl	SHA-256 hash
Docker mirror	container	pkg:docker/library/python@sha256:f77ac9e4…	Yes
OS package registry	library	pkg:deb/ubuntu/curl@7.81.0-1?arch=amd64, pkg:apk/alpine/…	Yes
PyPI mirror	library	pkg:pypi/requests@2.32.3	Yes
File mirror	file	pkg:generic/get-pip.py?download_url=https%3A%2F%2Fbootstrap…	No

For example, an excerpt of an SBOM:

{
  "bomFormat": "CycloneDX",
  "specVersion": "1.7",
  "serialNumber": "urn:uuid:dc670615-4035-453f-8cf3-fbdbffb1328d",
  "version": 1,
  "metadata": {
    "timestamp": "2026-09-30T02:37:08.754Z",
    "properties": [
      { "name": "stablebuild:build-id", "value": "build-1234" },
      { "name": "stablebuild:coverage", "value": "Lists only the artifacts this build fetched through StableBuild." }
    ]
  },
  "components": [
    {
      "type": "container",
      "bom-ref": "pkg:docker/library/python@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f",
      "name": "library/python",
      "purl": "pkg:docker/library/python@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f",
      "hashes": [ { "alg": "SHA-256", "content": "f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f" } ]
    },
    {
      "type": "library",
      "bom-ref": "2026-09-29T08:40:01Z/archive.ubuntu.com/ubuntu/pool/main/c/curl/curl_7.81.0-1_amd64.deb",
      "name": "curl",
      "version": "7.81.0-1",
      "purl": "pkg:deb/ubuntu/curl@7.81.0-1?arch=amd64",
      "hashes": [ { "alg": "SHA-256", "content": "db4d0fbae50d3bb80754342615e242c73460dc5d59bdd41f08de19b26472d821" } ]
    },
    {
      "type": "library",
      "bom-ref": "2026-09-01/requests/requests-2.32.3-py3-none-any.whl",
      "name": "requests",
      "version": "2.32.3",
      "purl": "pkg:pypi/requests@2.32.3",
      "hashes": [ { "alg": "SHA-256", "content": "70761cfe03c773ceb22aa2f671b4757976145175cdfca038c02654d061d6dcc6" } ]
    },
    {
      "type": "file",
      "bom-ref": "https://bootstrap.pypa.io/get-pip.py",
      "name": "get-pip.py",
      "purl": "pkg:generic/get-pip.py?download_url=https%3A%2F%2Fbootstrap.pypa.io%2Fget-pip.py"
    }
  ]
}