docker_scout_compare.yaml

command: docker scout compare
aliases: docker scout compare, docker scout diff
short: Compare two images and display differences (experimental)
long: |-
    The `docker scout compare` command analyzes two images and displays a comparison.

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

    The intended use of this command 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 built image is used
    as a comparison target.

    The following artifact types are supported:

    - Images
    - OCI layout directories
    - Tarball archives, as created by `docker save`
    - Local directory or file

    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, a tarball archive, a local file or directory,
    or if you want to control from where the image will be resolved, you must prefix the reference with one of the following:

    - `image://` (default) use a local image, or fall back to a registry lookup
    - `local://` use an image from the local image store (don't do a registry lookup)
    - `registry://` use an image from a registry (don't use a local image)
    - `oci-dir://` use an OCI layout directory
    - `archive://` use a tarball archive, as created by `docker save`
    - `fs://` use a local directory or file
    - `sbom://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file
usage: docker scout compare --to IMAGE|DIRECTORY|ARCHIVE [IMAGE|DIRECTORY|ARCHIVE]
pname: docker scout
plink: docker_scout.yaml
options:
    - option: exit-code
      shorthand: e
      value_type: bool
      default_value: "false"
      description: Return exit code '2' if vulnerability changes are detected
      deprecated: true
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: exit-on
      shorthand: x
      value_type: stringSlice
      default_value: '[]'
      description: |
        Comma separated list of conditions to fail the action step if worse or changed, options are: vulnerability, policy, package
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: format
      value_type: string
      default_value: text
      description: |-
        Output format of the generated vulnerability report:
        - text: default output, plain text with or without colors depending on the terminal
        - markdown: Markdown output
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: hide-policies
      value_type: bool
      default_value: "false"
      description: Hide policy status from the output
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: ignore-base
      value_type: bool
      default_value: "false"
      description: Filter out CVEs introduced from base image
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: ignore-suppressed
      value_type: bool
      default_value: "false"
      description: |
        Filter CVEs found in Scout exceptions based on the specified exception scope
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: ignore-unchanged
      value_type: bool
      default_value: "false"
      description: Filter out unchanged packages
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: multi-stage
      value_type: bool
      default_value: "false"
      description: Show packages from multi-stage Docker builds
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: only-fixed
      value_type: bool
      default_value: "false"
      description: Filter to fixable CVEs
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: only-package-type
      value_type: stringSlice
      default_value: '[]'
      description: |
        Comma separated list of package types (like apk, deb, rpm, npm, pypi, golang, etc)
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: only-policy
      value_type: stringSlice
      default_value: '[]'
      description: Comma separated list of policies to evaluate
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: only-severity
      value_type: stringSlice
      default_value: '[]'
      description: |
        Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: only-stage
      value_type: stringSlice
      default_value: '[]'
      description: Comma separated list of multi-stage Docker build stage names
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: only-unfixed
      value_type: bool
      default_value: "false"
      description: Filter to unfixed CVEs
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: only-vex-affected
      value_type: bool
      default_value: "false"
      description: Filter CVEs by VEX statements with status not affected
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: org
      value_type: string
      description: Namespace of the Docker organization
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: output
      shorthand: o
      value_type: string
      description: Write the report to a file
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: platform
      value_type: string
      description: Platform of image to analyze
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: ref
      value_type: string
      description: |-
        Reference to use if the provided tarball contains multiple references.
        Can only be used with archive
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: to
      value_type: string
      description: Image, directory, or archive to compare to
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: to-env
      value_type: string
      description: Name of environment to compare to
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: to-latest
      value_type: bool
      default_value: "false"
      description: Latest image processed to compare to
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: to-ref
      value_type: string
      description: |-
        Reference to use if the provided tarball contains multiple references.
        Can only be used with archive.
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: to-stream
      value_type: string
      description: Name of stream to compare to
      deprecated: true
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: vex
      value_type: bool
      default_value: "false"
      description: Apply VEX statements to filter CVEs
      deprecated: true
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: vex-author
      value_type: stringSlice
      default_value: '[<.*@docker.com>]'
      description: List of VEX statement authors to accept
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: vex-location
      value_type: stringSlice
      default_value: '[]'
      description: File location of directory or file containing VEX statements
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
inherited_options:
    - option: debug
      value_type: bool
      default_value: "false"
      description: Debug messages
      deprecated: false
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: verbose-debug
      value_type: bool
      default_value: "false"
      description: Verbose debug
      deprecated: false
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
examples: |-
    ### Compare the most recently built image to the latest tag

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

    ### Compare local build to the same tag from the registry

    ```console
    $ docker scout compare local://namespace/repo:latest --to registry://namespace/repo:latest
    ```

    ### Ignore base images

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

    ### Generate a markdown output

    ```console
    $ 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

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

    ### Show all policy results for both images

    ```console
    docker scout compare --to namespace/repo:latest namespace/repo:v1.2.3-pre
    ```
deprecated: false
experimental: false
experimentalcli: true
kubernetes: false
swarm: false