Skip to content
Tutorials Center
My learning

Topics

Lesson 74 of 111 ยท Security

Docker Scout, SBOMs and Provenance

Attach SBOM and SLSA provenance attestations to images with BuildKit, read them with imagetools, and use Docker Scout for vulnerability policies and supply chain checks.

When a new vulnerability such as a bad bug in a popular compression library is announced, two questions decide how your week goes. Which of our images contain that library? and Can we prove where this image came from? If you cannot answer the first, you scan hundreds of images one by one. If you cannot answer the second, you are trusting a tag name.

Both answers come from metadata that travels with the image: a Software Bill of Materials (SBOM) lists the packages inside, and provenance records how, where and from what the image was built. Together they are called attestations. Docker Scout is Docker's service that reads them, matches the packages against vulnerability databases and evaluates policies. This lesson shows how to create and inspect attestations yourself (real commands, run on Docker 29.8 with buildx 0.37) and how Scout builds on them. Scout needs a Docker account, so its commands are read-only examples.

The previous basic lesson on this topic is Image Security and Scanning; here we go deeper into the supply chain.

The software supply chain in one picture

Your image is assembled from a base image, packages from distribution repositories, libraries from language registries and your own code, built by a build system, then pushed to a registry and finally run. An attacker, or just an accident, can hit any step. Attestations are signed-or-unsigned statements attached to the image that describe the steps.

flowchart LR
    S["Source code<br/>+ Dockerfile"] --> B["BuildKit build"]
    BI["Base image"] --> B
    P["Packages<br/>apk, apt, npm, pip"] --> B
    B --> I["Image"]
    B --> SB["SBOM attestation<br/>what is inside"]
    B --> PR["Provenance attestation<br/>how it was built"]
    I --> R["Registry"]
    SB --> R
    PR --> R
    R --> SC["Docker Scout<br/>CVEs and policies"]

BuildKit produces the image and two attestations. The registry stores them together, and tools such as Scout read them later.

Creating attestations with BuildKit

Attestations are options of the build. Here is a Dockerfile with one extra package:

DOCKERFILE
FROM alpine:3.22
RUN apk add --no-cache curl
CMD ["curl", "--version"]

Build it with both attestation types and push it. I used a throwaway local registry on 127.0.0.1:18955; the registry must support OCI artifacts (any current one does):

CONSOLE
$ docker buildx build --sbom=true --provenance=mode=max -t 127.0.0.1:18955/att:1 --push .
  • --sbom=true runs an SBOM scanner (Syft, shipped as a helper image) over the finished file system and stores the result in SPDX format.
  • --provenance=mode=max stores a SLSA provenance statement with full detail. Plain --provenance=true (mode min) is the default in recent buildx and records less. max includes build arguments and other details, so check them before publishing images of private projects.

Where did the attestations go? Look at the image index:

CONSOLE
$ docker buildx imagetools inspect 127.0.0.1:18955/att:1
Name:      127.0.0.1:18955/att:1
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:8617ddaf1b92...

Manifests: 
  Name:        127.0.0.1:18955/att:1@sha256:66537d771bc5...
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64

  Name:        127.0.0.1:18955/att:1@sha256:74623c09a4e3...
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    unknown/unknown
  Annotations: 
    vnd.docker.reference.digest: sha256:66537d771bc5...
    vnd.docker.reference.type:   attestation-manifest

The image index now has a second entry with platform unknown/unknown, annotated as an attestation-manifest that refers to the amd64 image by digest. That is why you saw those odd entries in Multi-Platform Images: attestations live in the same index as the images they describe, so they move with the image when you copy or mirror it. The unknown/unknown platform makes ordinary docker pull ignore them.

The classic Docker image store cannot keep attestations next to a local image. Push to a registry, or use the containerd image store (the default in Docker 29), which keeps the index including the attestation entries locally.

Reading the SBOM

imagetools inspect can print the SBOM. The format string selects the SPDX document:

CONSOLE
$ docker buildx imagetools inspect 127.0.0.1:18955/att:1 --format '{{json .SBOM.SPDX}}'
{
  "SPDXID": "SPDXRef-DOCUMENT",
  "creationInfo": {
    "created": "2026-10-29T10:21:47Z",
    "creators": [
      "Organization: Anchore, Inc",
      "Tool: syft-v1.51.0",
      "Tool: buildkit-v0.33.0"
    ],
    "licenseListVersion": "3.28"
  },
  "dataLicense": "CC0-1.0",
  ...

The full document is long, so pipe it into a tool. A small Node script that lists the packages (filtered to a few names) shows the useful part:

CONSOLE
$ docker buildx imagetools inspect 127.0.0.1:18955/att:1 --format '{{json .SBOM.SPDX}}' > sbom.json
$ node -e 'const s=require("./sbom.json"); console.log(s.packages.length, "packages"); for (const p of s.packages) if (/curl|busybox|musl/.test(p.name)) console.log(p.name, p.versionInfo)'
26 packages
busybox 1.37.0-r20
busybox-binsh 1.37.0-r20
curl 8.14.1-r4
libcurl 8.14.1-r4
musl 1.2.5-r13
musl-utils 1.2.5-r13

The SBOM found 26 packages in total: the Alpine base (musl, busybox, ...) and the curl library we added, each with its exact version. That list is what a vulnerability scanner needs. The version numbers will differ on your machine because Alpine publishes updates.

An SBOM records what the scanner found: packages known to the package manager and, for some ecosystems, language libraries it can discover from lock files or binaries. It cannot see a binary you downloaded with curl in a RUN line unless it recognises it. Treat it as a good inventory, not a proof of completeness.

You can also write the SBOM to disk during the build, without pushing, with the local exporter. The files appear in the output folder (read-only example):

CONSOLE
$ docker buildx build --sbom=true --output type=local,dest=out .

Reading the provenance

Provenance uses the SLSA format ("Supply-chain Levels for Software Artifacts"). Ask for it the same way:

CONSOLE
$ docker buildx imagetools inspect 127.0.0.1:18955/att:1 --format '{{json .Provenance.SLSA}}'

The result has two top-level objects, buildDefinition and runDetails. In our build buildDefinition contained:

  • buildType, a URL that identifies BuildKit's definition of the fields.
  • externalParameters: the request. It showed "configSource": {"path": "Dockerfile"} and the frontend dockerfile.v0. In mode=max it also lists build arguments.
  • resolvedDependencies: the exact inputs used. For us, the SBOM scanner image and the base image as a package URL with its digest, such as pkg:docker/[email protected]?platform=linux%2Famd64 with sha256:2e0b81d6....

runDetails holds the builder identity and metadata such as start and finish times. Notice the key piece: the base image is recorded by digest, so even if the tag alpine:3.22 moves tomorrow, the provenance still says which bytes this image was built on. When the build runs in CI with GitHub Actions or similar, the provenance also records the repository and the commit, which answers "which source produced this image?".

Provenance made by the builder is a claim. It becomes strong evidence when the build system is trusted and the attestation is signed (for example with Sigstore's cosign); see the signing section in Image Security and Scanning.

Docker Scout

Docker Scout takes an image (local, or in Docker Hub or another registry), builds or reads its SBOM, matches every package against a continuously updated advisory database and shows the result. It needs to know who you are, so without a login the command only prints a sign-in prompt, as it did on my machine:

CONSOLE
$ docker scout quickview alpine:3.22
Log in with your Docker ID or email address to use docker scout.
...

After docker login (or signing in to Docker Desktop), the same commands work. They are read-only examples here, and the numbers in the output depend on the day you run them:

CONSOLE
$ docker scout quickview myapp:1.0          # summary of vulnerabilities and base image
$ docker scout cves myapp:1.0               # every CVE, with package and fixed version
$ docker scout cves --only-severity critical,high --only-fixed myapp:1.0
$ docker scout recommendations myapp:1.0    # better base images and the CVEs they remove
$ docker scout compare myapp:2.0 --to myapp:1.0

Useful options:

  • --only-fixed hides vulnerabilities that have no fix yet, so the report shows what you can act on now.
  • --only-severity critical,high focuses on the important ones.
  • --exit-code makes the command fail when it finds problems, so a CI step can stop a release.
  • --format sarif or --format markdown creates a report for code-scanning dashboards or pull request comments.
  • local://image:tag forces the local image store; registry://... forces the registry.

recommendations is the feature many teams like most: Scout reads the base image from the provenance (or guesses it), and suggests a newer tag or a smaller variant, with the number of vulnerabilities each option removes. That is often a one-line fix to the FROM line, as discussed in Choosing Base Images.

Scout is also built into Docker Desktop and shows up on the Docker Hub image page, where it scans images pushed to repositories with Scout enabled. Free plans include a limited number of repositories; check Docker's pricing page for the current numbers.

Policies

A list of CVEs is information. A policy turns it into a pass or fail. Scout ships a set of default policies; the exact set changes over time, but the usual ones are:

  • No fixable critical or high vulnerabilities.
  • No known vulnerabilities with an elevated exploit risk.
  • No packages with a licence you banned (for example strong copyleft licences).
  • The base image is up to date and approved.
  • The image runs as a non-root user by default.
  • Supply chain attestations (SBOM and provenance) are present.

Notice how the last policy ties back to this lesson: if you do not create attestations, you fail the check. Organisations can configure which policies apply and run docker scout policy against an image.

VEX: when a CVE does not apply

Scanners report every vulnerable package, even when your image never calls the vulnerable code. A VEX document ("Vulnerability Exploitability eXchange") is an attestation that says: for this image, CVE-XXXX is not affected, because... Scout understands OpenVEX documents attached to an image (docker scout vex), and can hide those findings, which keeps reports honest without ignoring real problems. Writing a VEX statement is a deliberate decision that someone should review, never a way to silence a noisy report.

A supply chain workflow

Put the pieces into a pipeline, as in CI Pipelines:

  1. Build with --sbom=true --provenance=mode=max and push (a bake file can set attest once for all targets).
  2. Pin base images by digest, let a bot propose updates, and read the provenance to see which digest was used (Image Tagging Strategy).
  3. Fail the release when the scan finds a fixable critical vulnerability (docker scout cves --exit-code ...).
  4. Sign the image and attestations, and verify the signature at deploy time.
  5. Re-scan stored images regularly: new CVEs appear after the build. A registry-level watcher such as Scout's repository monitoring does this without a rebuild.
  6. Keep the SBOM somewhere you can search it. When the next big bug appears, a search across all SBOMs for libfoo 1.2.* answers the "which images?" question in minutes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where are BuildKit attestations stored when you push an image?

    The image index gets an attestation-manifest entry per image. Because it lives in the index, it travels with the image to mirrors and copies.
  2. 2. What does an SBOM tell you?

    An SBOM is an inventory of software components. Build origin is the job of provenance, and signatures are separate.
  3. 3. Why does provenance record the base image by digest?

    A digest identifies exact bytes. Recording it lets you know precisely which base the image was built on, even after the tag moves.
  4. 4. What is the purpose of a VEX statement?

    VEX documents mark findings as not affected, fixed or under investigation, so that scanners show only the findings that matter.
  5. 5. Which Scout option makes a CI job fail when a scan finds problems?

    --exit-code returns a non-zero status when vulnerabilities are found. The other options only filter or format the report.

Summary

  • An SBOM lists the packages in an image; provenance (SLSA) records how and from what it was built. Both are attestations stored in the image index.
  • Create them with docker buildx build --sbom=true --provenance=mode=max --push, read them with docker buildx imagetools inspect --format '{{json .SBOM.SPDX}}' or .Provenance.SLSA.
  • Provenance records base images by digest; an unsigned attestation is a claim, so signing and verification complete the chain.
  • Docker Scout (login required) scans images against advisory data: quickview, cves, recommendations, compare and policy; --only-fixed, --only-severity and --exit-code suit CI.
  • Policies turn findings into pass or fail, and VEX documents mark findings that do not apply.
  • Re-scan stored images regularly, because new CVEs appear after the build.

Next: Working with Registries