How to use docker buildx history inspect attachment command to inspect build attachments

Introduction

In this lab, you will learn how to use the docker buildx history inspect attachment command to examine attachments associated with Docker image builds. You will begin by building a Docker image and attaching a file to it using the --attest flag.

Following the build, you will explore how to list the build history to identify the reference for the build containing the attachment. Finally, you will practice inspecting the attached file using the obtained reference, and further refine the inspection by specifying the attachment type and platform. This hands-on experience will demonstrate how to access and verify metadata embedded within your Docker images.

Skills Graph

Build an image with an attachment

In this step, we will learn how to build a Docker image and attach metadata to it. Attachments are a way to include additional information with your image, such as build provenance, software bill of materials (SBOM), or other relevant data.

First, let's create a simple Dockerfile. Navigate to the ~/project directory if you are not already there.

cd ~/project

Now, create a file named Dockerfile using the nano editor.

nano Dockerfile

Add the following content to the Dockerfile:

FROM alpine:latest
CMD ["echo", "Hello, Docker Attachments!"]

This Dockerfile is very simple. It uses the alpine:latest image as the base and defines a command to print a message when the container starts.

Save the file and exit nano (Press Ctrl + X, then Y, then Enter).

Next, we need to create a file that we will attach to the image. Let's create a simple text file named attachment.txt.

nano attachment.txt

Add some content to attachment.txt, for example:

This is an example attachment for the Docker image.
It can contain any relevant metadata.

Save the file and exit nano.

Now, we will build the Docker image and attach the attachment.txt file. We will use the docker build command with the --attest flag. The --attest flag allows you to specify an attachment to include with the image build. The format is type=type,dest=destination,src=source.

In our case, we will use type=sbom (Software Bill of Materials) as the type, dest=/sbom/attachment.txt as the destination path within the attachment, and src=attachment.txt as the source file on our local filesystem. We will also tag the image as my-attached-image:latest.

Before building, ensure you have the necessary buildx plugin installed. If not, you might need to install it. However, for basic attachments, the built-in builder should suffice.

Let's build the image:

docker build -t my-attached-image:latest --attest type=sbom,dest=/sbom/attachment.txt,src=attachment.txt .

The . at the end of the command specifies the build context, which is the current directory (~/project).

You should see output indicating that the image is being built and the attachment is being processed.

After the build is complete, you can verify that the image was created by listing your local images.

docker images

You should see my-attached-image in the list.

List build history to find the reference

In the previous step, we built a Docker image with an attachment. Now, we need to find the reference to this attachment so we can inspect it. Attachments are associated with the build history, not directly with the final image tag.

We can use the docker buildx imagetools inspect command to view information about the image and its associated attachments. This command requires the image reference.

Let's inspect the image we built, my-attached-image:latest.

docker buildx imagetools inspect my-attached-image:latest

This command will output detailed information about the image manifest. Look for the attestations section in the output. This section lists the attachments associated with the image.

Within the attestations section, you will find entries for each attachment. Each entry will have a ref field. This ref is the reference we need to inspect the attachment content. It will look something like sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Copy the value of the ref field for the attachment you added (the one with type=sbom). This is the reference we will use in the next step.

For example, if the output shows:

{
  "manifest": {
    ...
  },
  "attestations": [
    {
      "ref": "sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "type": "sbom",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    }
  ]
}

The reference you need is sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890. Note that your actual reference will be different.

Keep this reference handy for the next step.

Inspect the attachment using the reference

In the previous step, we found the reference for the attachment associated with our Docker image using docker buildx imagetools inspect. Now, we will use this reference to inspect the content of the attachment.

We can use the docker buildx attestation inspect command to view the details of a specific attachment using its reference.

Recall the reference you obtained in the previous step. It should be in the format sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Replace <attachment_reference> with the actual reference you copied.

docker buildx attestation inspect <attachment_reference>

For example, if your reference was sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890, the command would be:

docker buildx attestation inspect sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

This command will output the content of the attachment. You should see the text you added to the attachment.txt file in Step 1.

The output will likely include some metadata about the attachment, followed by the actual content. Look for the section that contains the text "This is an example attachment...".

This demonstrates how you can retrieve the content of an attachment using its unique reference. This is useful for verifying the integrity and content of the attached data.

Inspect the attachment specifying type and platform

In the previous step, we inspected an attachment using its direct reference. However, you can also inspect attachments associated with an image by specifying the attachment type and the platform it was built for. This is particularly useful when an image has multiple attachments of different types or for different architectures.

We will use the docker buildx attestation inspect command again, but this time we will provide the image reference, the attachment type, and the platform.

The image reference is my-attached-image:latest.
The attachment type we used was sbom.
The platform for our build is typically linux/amd64 in the LabEx environment.

The command format is docker buildx attestation inspect <image_reference> --type <attachment_type> --platform <platform>.

Let's inspect the attachment using this method:

docker buildx attestation inspect my-attached-image:latest --type sbom --platform linux/amd64

This command should also output the content of the attachment, similar to the previous step. This confirms that you can retrieve the attachment information by specifying the image, type, and platform.

This method is more convenient when you know the type of attachment you are looking for and the platform of the image, as you don't need to first find the specific attachment reference using imagetools inspect.

You have now learned how to build a Docker image with an attachment and how to inspect that attachment using both its direct reference and by specifying the image, type, and platform.

Summary

In this lab, we learned how to build a Docker image with an attached file using the docker build command with the --attest flag, specifying the attachment type, destination within the attachment, and source file. We then explored how to list the build history using docker buildx history to identify the reference for the build containing the attachment.

Finally, we practiced inspecting the attached file using the docker buildx history inspect attachment command, first by providing the build reference and attachment destination, and subsequently by also specifying the attachment type and platform for more targeted inspection. This process demonstrated how to include and access additional metadata associated with a Docker image build.