---
title: SBOM attestations
keywords: build, attestations, sbom, spdx, metadata, packages
description: |
  SBOM build attestations describe the contents of your image,
  and the packages used to build it.
aliases:
  - /build/attestations/sbom/
---

Software Bill of Materials (SBOM) attestations describe what software artifacts
an image contains, and artifacts used to create the image. Metadata included in
an SBOM for describing software artifacts may include:

- Name of the artifact
- Version
- License type
- Authors
- Unique package identifier

There are benefits to indexing contents of an image during the build, as opposed
to scanning a final image. When scanning happens as part of the build, you're
able to detect software you use to build the image, that may not show up in the
final image.

The SBOMs generated by BuildKit follow the SPDX standard. SBOMs attach to the
final image as a JSON-encoded SPDX document, using the format defined by the
[in-toto SPDX predicate](https://github.com/in-toto/attestation/blob/main/spec/predicates/spdx.md).

## Create SBOM attestations

To create an SBOM attestation, pass the `--attest type=sbom` option to the
`docker buildx build` command:

```console
$ docker buildx build --tag <namespace>/<image>:<version> \
    --attest type=sbom --push .
```

Alternatively, you can use the shorthand `--sbom=true` option instead of `--attest type=sbom`.

For an example on how to add SBOM attestations with GitHub Actions, see
[Add attestations with GitHub Actions](/manuals/build/ci/github-actions/attestations.md).

## Verify SBOM attestations

Always validate the generated SBOM for your image before you push your image to a registry.

To validate, you can build the image using the `local` exporter.
Building with the `local` exporter saves the build result to your local filesystem instead of creating an image.
Attestations are written to a JSON file in the root directory of your export.

```console
$ docker buildx build \
  --sbom=true \
  --output type=local,dest=out .
```

The SBOM file appears in the root directory of the output, named `sbom.spdx.json`:

```console
$ ls -1 ./out | grep sbom
sbom.spdx.json
```

## Arguments

By default, BuildKit only scans the final stage of an image. The resulting SBOM
doesn't include build-time dependencies installed in earlier stages, or that
exist in the build context. This may cause you to overlook vulnerabilities in
those dependencies, which could impact the security of your final build
artifacts.

For instance, you might use [multi-stage builds](/manuals/build/building/multi-stage.md),
with a `FROM scratch` stanza for your final stage to achieve a smaller image size.

```dockerfile
FROM alpine AS build
# build the software ...

FROM scratch
COPY --from=build /path/to/bin /bin
ENTRYPOINT [ "/bin" ]
```

Scanning the resulting image built using this Dockerfile example would not
reveal build-time dependencies used in the `build` stage.

To include build-time dependencies from your Dockerfile, you can set the build
arguments `BUILDKIT_SBOM_SCAN_CONTEXT` and `BUILDKIT_SBOM_SCAN_STAGE`. This
expands the scanning scope to include the build context and additional stages.

You can set the arguments as global arguments (after declaring the Dockerfile
syntax directive, before the first `FROM` command) or individually in each
stage. If set globally, the value propagates to each stage in the Dockerfile.

The `BUILDKIT_SBOM_SCAN_CONTEXT` and `BUILDKIT_SBOM_SCAN_STAGE` build arguments
are special values. You can't perform variable substitution using these
arguments, and you can't set them using environment variables from within the
Dockerfile. The only way to set these values is using explicit `ARG` command in
the Dockerfile.

### Scan build context

To scan the build context, set the `BUILDKIT_SBOM_SCAN_CONTEXT` to `true`.

```dockerfile
# syntax=docker/dockerfile:1
ARG BUILDKIT_SBOM_SCAN_CONTEXT=true
FROM alpine AS build
# ...
```

You can use the `--build-arg` CLI option to override the value specified in the