docker scout compare

Early Access

Advanced image analysis is provided by Docker Scout and in early access. Learn more on the Docker Scout product page.


Compare two images and display differences (experimental)

This command is experimental.

Experimental features are intended for testing and feedback as their functionality or UX may change between releases without warning or can be removed entirely in a future release.

Usage

$ docker scout compare --to IMAGE|DIRECTORY|ARCHIVE [IMAGE|DIRECTORY|ARCHIVE]

Refer to the options section for an overview of available OPTIONS for this command.

Description

The docker scout compare command analyzes two images and displays a comparison of both.

This command is experimental and its behaviour might change in the future

The main usage is to compare two versions of the same image. For instance when a new image is built and compared to the version running in production.

If no image is specified, the most recently build image will be used.

The following artifact types are supported:

  • Images
  • OCI layout directories
  • Tarball archives, as created by docker save

The tool analyzes the provided software artifact, and generates a vulnerability report.

By default, the tool expects an image reference, such as:

  • redis
  • curlimages/curl:7.87.0
  • mcr.microsoft.com/dotnet/runtime:7.0

If the artifact you want to analyze is an OCI directory or a tarball archive, you must use the --type or --to-type flag.

For example uses of this command, refer to the examples section below.

Options

Name, shorthand Default Description
--exit-code , -e Return exit code ‘2’ if vulnerability changes are detected
--format text Output format of the generated vulnerability report: - text: default output, plain text with or without colors depending on the terminal - markdown: Markdown output
--ignore-base Filter out CVEs introduced from base image
--ignore-unchanged Filter out unchanged packages
--only-fixed Filter to fixable CVEs
--only-package-type Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)
--only-severity Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by
--only-unfixed Filter to unfixed CVEs
--output , -o Write the report to a file.
--platform Platform of image to analyze
--ref Reference to use if the provided tarball contains multiple references. Can only be used with --type archive.
--to Image, directory or archive to compare to
--to-latest Latest image processed to compare to
--to-ref Reference to use if the provided tarball contains multiple references. Can only be used with --type archive.
--to-stream Name of stream to compare to
--to-type image Type of the image to analyze. Can be one of: - image - oci-dir - archive (docker save tarball)
--type image Type of the image to analyze. Can be one of: - image - oci-dir - archive (docker save tarball)

Examples

Compare the most recently built image to the latest tag

$ docker scout compare --to namespace/repo:latest

Ignore base images

$ docker scout compare --ignore-base --to namespace/repo:latest namespace/repo:v1.2.3-pre

Generate a markdown output

$ docker scout compare --format markdown --to namespace/repo:latest namespace/repo:v1.2.3-pre

Only compare maven packages and only display critical vulnerabilities for maven packages

$ docker scout compare --only-package-type maven --only-severity critical --to namespace/repo:latest namespace/repo:v1.2.3-pre

Parent command

Command Description
docker scout Command line tool for Docker Scout
Command Description
docker scout compare Compare two images and display differences (experimental)
docker scout cves Display CVEs identified in a software artifact
docker scout quickview Quick overview of an image
docker scout recommendations Display available base image updates and remediation recommendations
docker scout repo Commands to list, enable and disable Docker Scout on repositories
docker scout stream Record an image into a stream (experimental)
docker scout version Show Docker Scout version information