> For the complete documentation index, see [llms.txt](https://stablebuild.gitbook.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stablebuild.gitbook.io/en/product/sbom.md). # 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](https://cyclonedx.org/docs/1.7/json/) JSON document, so you can feed it into the compliance tool of your choice. {% hint style="info" %} SBOM is available on the Enterprise plan. If you're interested, let us know at . {% endhint %} 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: {% code overflow="wrap" %} ```docker 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" ``` {% endcode %} 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: {% code overflow="wrap" %} ```docker 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 ``` {% endcode %} And set it from your CI system, e.g. in GitHub Actions: ```yaml - name: Build container run: docker build --build-arg BUILD_ID=gh-${{ github.run_id }} . ``` {% hint style="info" %} 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. {% endhint %} ### Generating an SBOM 1. Go to the [dashboard](https://dashboard.stablebuild.com) 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-.cdx.json`.

Generating an SBOM for a build

### What's in the SBOM Every artifact becomes a CycloneDX component with a [package URL (purl)](https://github.com/package-url/purl-spec): | 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: {% code overflow="wrap" %} ```json { "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" } ] } ``` {% endcode %}