How to use docker scout attestation add command to attach attestations to an image

Introduction

In this lab, you will learn how to attach attestations to a Docker image using the docker scout attestation add command. Attestations are valuable metadata that can provide crucial information about an image's origin, build process, security scan results, and more.

You will begin by preparing a Docker image and a simple attestation file. Then, you will use the docker scout attestation add command with the --file flag to attach the attestation to the image. You will also explore how to specify a particular predicate type for the attestation using the --predicate-type flag. Finally, you will verify that the attestations have been successfully added to the image.

Skills Graph

Prepare an image and an attestation file

In this step, we will prepare a Docker image and an attestation file. An attestation is a piece of metadata that provides information about an image, such as how it was built, scanned for vulnerabilities, or signed. We will use a simple text file as our attestation file for this example.

First, let's pull a basic Docker image that we will use. We will use the alpine image, which is a lightweight Linux distribution.

docker pull alpine:latest

You should see output indicating that the image is being pulled and downloaded.

latest: Pulling from library/alpine
...
Status: Downloaded newer image for alpine:latest
docker.io/library/alpine:latest

Next, we will create a simple attestation file. This file will contain some arbitrary JSON data. In a real-world scenario, this file would contain structured data about the image, such as build information, scan results, or signing details.

We will create a file named attestation.json in your ~/project directory.

nano ~/project/attestation.json

Inside the nano editor, paste the following JSON content:

{
  "predicateType": "https://example.com/attestation/v1",
  "data": {
    "key": "value",
    "another_key": 123
  }
}

Press Ctrl + X, then Y, and Enter to save the file.

You can verify the content of the file using the cat command:

cat ~/project/attestation.json

The output should be the JSON content you just pasted.

Now you have both the Docker image (alpine:latest) and the attestation file (~/project/attestation.json) ready for the next steps.

Add an attestation to the image using --file

In this step, we will add the attestation file we created in the previous step to the alpine:latest image. We will use the docker buildx imagetools create command with the --attestation-file flag. This command allows us to create a new image manifest with additional metadata, including attestations.

The basic syntax for adding an attestation file is:

docker buildx imagetools create <source_image> --attestation-file <attestation_file_path> --tag <new_image_tag>

Here, <source_image> is the image you want to add the attestation to, <attestation_file_path> is the path to your attestation file, and <new_image_tag> is the tag for the new image manifest that will include the attestation.

Let's add the ~/project/attestation.json file to the alpine:latest image and tag the new image as alpine:attested.

docker buildx imagetools create alpine:latest --attestation-file ~/project/attestation.json --tag alpine:attested

You should see output indicating that the new image manifest is being created and pushed.

...
unpacking to docker.io/library/alpine:attested done

This command creates a new image manifest with the tag alpine:attested that includes the attestation data from ~/project/attestation.json. The original alpine:latest image remains unchanged.

You can now list your Docker images to see the newly created alpine:attested image.

docker images

You should see both alpine:latest and alpine:attested in the list.

REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
alpine       attested  <image_id>     ...            ...
alpine       latest    <image_id>     ...            ...
...

Note that the IMAGE ID might be the same for both images, as imagetools create often reuses the underlying image layers and only creates a new manifest.

Add an attestation with a specific predicate type using --predicate-type

In the previous step, we added an attestation using the --attestation-file flag. Docker automatically inferred the predicate type from the predicateType field within the JSON file. However, you can also explicitly specify the predicate type using the --predicate-type flag. This is useful if your attestation data doesn't include the predicateType field or if you want to override the one in the file.

The basic syntax for adding an attestation with a specific predicate type is:

docker buildx imagetools create <source_image> --attestation-file <attestation_file_path> --predicate-type <predicate_type_url> --tag <new_image_tag>

Here, <predicate_type_url> is the URL representing the type of attestation.

Let's add the same ~/project/attestation.json file to the alpine:latest image again, but this time we will explicitly set the predicate type to https://example.com/another-attestation/v2 and tag the new image as alpine:attested-v2.

docker buildx imagetools create alpine:latest --attestation-file ~/project/attestation.json --predicate-type https://example.com/another-attestation/v2 --tag alpine:attested-v2

You should see output similar to the previous step, indicating the creation of a new image manifest.

...
unpacking to docker.io/library/alpine:attested-v2 done

This command creates a new image manifest with the tag alpine:attested-v2. Even though the attestation.json file contains "predicateType": "https://example.com/attestation/v1", the --predicate-type flag overrides this, and the attestation in the new manifest will have the predicate type https://example.com/another-attestation/v2.

Let's list the images again to see the new tag.

docker images

You should now see alpine:latest, alpine:attested, and alpine:attested-v2.

REPOSITORY   TAG           IMAGE ID       CREATED        SIZE
alpine       attested-v2   <image_id>     ...            ...
alpine       attested      <image_id>     ...            ...
alpine       latest        <image_id>     ...            ...
...

In the next step, we will verify that the attestations have been added correctly and inspect their contents.

Verify the added attestations

In this final step, we will verify that the attestations were successfully added to the images and inspect their contents. We can use the docker buildx imagetools inspect command to view the manifest of an image, which includes information about any associated attestations.

The basic syntax for inspecting an image manifest is:

docker buildx imagetools inspect <image_tag>

Let's first inspect the alpine:attested image, which we created using the --attestation-file flag.

docker buildx imagetools inspect alpine:attested

You should see detailed output about the image manifest. Look for a section related to "attestations". You should find an entry with the predicate type https://example.com/attestation/v1 and the data from your attestation.json file.

...
  "attestations": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "payload": "...",
      "predicateType": "https://example.com/attestation/v1"
    }
  ],
...

Now, let's inspect the alpine:attested-v2 image, which we created using the --predicate-type flag to override the predicate type.

docker buildx imagetools inspect alpine:attested-v2

Again, look for the "attestations" section. This time, you should see an entry with the predicate type https://example.com/another-attestation/v2, even though the content of the attestation data is the same as before.

...
  "attestations": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "payload": "...",
      "predicateType": "https://example.com/another-attestation/v2"
    }
  ],
...

This confirms that we successfully added attestations to the Docker images and that the --predicate-type flag can be used to explicitly set the predicate type.

You have now learned how to prepare an image and an attestation file, add attestations to an image using both the --attestation-file and --predicate-type flags, and verify the added attestations using docker buildx imagetools inspect.

Summary

In this lab, we learned how to attach attestations to a Docker image using the docker scout attestation add command. We began by preparing a Docker image (alpine:latest) and creating a simple JSON attestation file. We then used the docker scout attestation add command with the --file flag to attach the attestation file to the image. We also explored how to specify a custom predicate type for the attestation using the --predicate-type flag. Finally, we verified that the attestations were successfully added to the image.