How to use docker trust inspect command to examine image trust information

Introduction

In this lab, you will learn how to use the docker trust inspect command to examine the trust information associated with Docker images. You will explore how to inspect trust data for single signed and unsigned image tags, as well as for all signed tags within a repository.

Through hands-on exercises, you will gain practical experience in verifying the integrity and publisher of images by inspecting their digital signatures. You will learn how to interpret the output of the docker trust inspect command and understand the difference in trust information between signed and unsigned images. Finally, you will see how to inspect trust information for multiple images and view the output in a human-readable format.

Skills Graph

Inspect trust information for a single signed image tag

In this step, you will learn how to inspect the trust information for a single signed image tag using the docker trust inspect command. Docker Content Trust allows you to verify the integrity and publisher of images you pull from a registry.

First, let's pull a signed image. We will use the docker/trusttest image, which is specifically designed for testing Docker Content Trust.

docker pull docker/trusttest:latest

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

Now, we can inspect the trust information for this specific image tag. The docker trust inspect command is used for this purpose.

docker trust inspect docker/trusttest:latest

The output of this command will show you details about the signatures associated with the image tag. This includes the signers and their keys. If the image is signed, you will see information about the signatures. If it's not signed, the output will indicate that no trust data is found.

Inspect trust information for an unsigned image tag in a signed repository

In this step, you will learn how to inspect the trust information for an unsigned image tag within a repository that contains signed images. This demonstrates that even if a repository has signed tags, individual unsigned tags will not have trust information.

We will continue to use the docker/trusttest repository. In the previous step, we inspected the latest tag, which is signed. Now, let's try to inspect a tag that is known to be unsigned within the same repository. We will use the unsigned tag for this purpose.

First, let's attempt to pull the unsigned tag.

docker pull docker/trusttest:unsigned

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

Now, let's inspect the trust information for the unsigned tag using the docker trust inspect command.

docker trust inspect docker/trusttest:unsigned

When you run this command, you will likely see output indicating that no trust data is found for this specific tag. This is because the unsigned tag, despite being in a repository with signed tags, does not have a valid signature itself. This highlights that Docker Content Trust operates on a per-tag basis.

Inspect trust information for all signed tags in a repository

In this step, you will learn how to inspect the trust information for all signed image tags within a specific repository. This is useful for getting an overview of which tags in a repository are trusted.

We will continue using the docker/trusttest repository. In the previous steps, we looked at individual tags. Now, we will inspect the entire repository to see all signed tags.

To inspect all signed tags in a repository, you use the docker trust inspect command followed by the repository name without a specific tag.

docker trust inspect docker/trusttest

When you execute this command, the output will list all the tags within the docker/trusttest repository that have valid trust data associated with them. You should see information for the latest tag (which we verified is signed in Step 1) and potentially other signed tags if they exist in that repository. Unsigned tags, like the unsigned tag we examined in Step 2, will not appear in this output.

This command provides a convenient way to quickly see which versions of an image in a repository are considered trusted according to Docker Content Trust.

Inspect trust information for multiple images

In this step, you will learn how to inspect the trust information for multiple image tags with a single docker trust inspect command. This is useful when you want to check the trust status of several specific images at once.

We will inspect the trust information for both the signed latest tag and the unsigned unsigned tag from the docker/trusttest repository in one command.

To inspect multiple images, you simply list the image names (including the tag) after the docker trust inspect command, separated by spaces.

docker trust inspect docker/trusttest:latest docker/trusttest:unsigned

When you run this command, the output will show the trust information for each specified image tag. You should see the signature details for docker/trusttest:latest and an indication that no trust data is found for docker/trusttest:unsigned. This confirms that you can efficiently check the trust status of multiple images in a single operation.

Inspect trust information in a human-readable format

In this step, you will learn how to display the trust information in a more human-readable format using the --pretty flag with the docker trust inspect command. By default, the output is in JSON format, which is useful for scripting but less so for quick human inspection.

We will inspect the trust information for the signed docker/trusttest:latest image again, but this time we will add the --pretty flag.

docker trust inspect --pretty docker/trusttest:latest

When you execute this command, the output will be formatted in a way that is easier to read and understand. It will typically present the information in a table-like structure, showing details about the image, the signers, and their keys in a clear layout.

Comparing this output to the default JSON output from Step 1, you can see how the --pretty flag makes the trust information more accessible for human review. This is particularly helpful when you are manually checking the trust status of an image.

Summary

In this lab, we learned how to use the docker trust inspect command to examine image trust information. We started by inspecting the trust data for a single signed image tag, observing the details of the associated signatures and signers. We then explored how inspecting an unsigned image tag within a signed repository reveals that only signed tags possess trust information.

We further expanded our understanding by inspecting trust information for all signed tags within a repository and for multiple images simultaneously. Finally, we learned how to display the trust information in a more human-readable format, making it easier to interpret the signing details. These steps provided practical experience in verifying the integrity and publisher of Docker images using Docker Content Trust.