Merge pull request #16971 from eunomie/scout-v0.8.5-cli-docs

DD4.18 scout: update cli documentation

_data/scout-cli/docker_scout.yaml

@@ -5,10 +5,16 @@ usage: docker scout [command]
 pname: docker
 plink: docker.yaml
 cname:
+    - docker scout compare
     - docker scout cves
+    - docker scout quickview
+    - docker scout recommendations
     - docker scout version
 clink:
+    - docker_scout_compare.yaml
     - docker_scout_cves.yaml
+    - docker_scout_quickview.yaml
+    - docker_scout_recommendations.yaml
     - docker_scout_version.yaml
 deprecated: false
 experimental: false

_data/scout-cli/docker_scout_compare.yaml

@@ -0,0 +1,212 @@
+command: docker scout compare
+short: '[early preview] Compare two images and display differences'
+long: |-
+    The `docker scout compare` command analyzes two images and displays a comparison of both.
+
+    > This command is in **early preview** 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.
+
+    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.
+usage: docker scout compare --to IMAGE|DIRECTORY|ARCHIVE IMAGE|DIRECTORY|ARCHIVE
+pname: docker scout
+plink: docker_scout.yaml
+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: 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: 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: 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-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-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: 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 --type 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-ref
+      value_type: string
+      description: |-
+        Reference to use if the provided tarball contains multiple references.
+        Can only be used with --type archive.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: to-type
+      value_type: string
+      default_value: image
+      description: |-
+        Type of the image to analyze. Can be one of:
+        - image
+        - oci-dir
+        - archive (docker save tarball)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: type
+      value_type: string
+      default_value: image
+      description: |-
+        Type of the image to analyze. Can be one of:
+        - image
+        - oci-dir
+        - archive (docker save tarball)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+examples: |-
+    ### Compare an image to the latest tag
+
+    ```console
+    $ docker scout compare --to namespace/repo:latest namespace/repo:v1.2.3-pre
+    ```
+
+    ### 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
+    ```
+deprecated: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+

_data/scout-cli/docker_scout_cves.yaml

@@ -54,7 +54,7 @@ options:
       swarm: false
     - option: format
       value_type: string
-      default_value: txt-by-packages
+      default_value: packages
       description: |-
         Output format of the generated vulnerability report:
         - packages: default output, plain text with vulnerabilities grouped by packages
@@ -111,7 +111,7 @@ options:
       value_type: stringSlice
       default_value: '[]'
       description: |
-        Comma separated list of severities (critical, high, medium, low) to filter CVEs by
+        Comma separated list of severities (critical, high, medium, low, unspecified) to filter CVEs by
       deprecated: false
       hidden: false
       experimental: false
@@ -140,7 +140,7 @@ options:
       swarm: false
     - option: platform
       value_type: string
-      description: Platform of image for which to list CVEs for
+      description: Platform of image to analyze
       deprecated: false
       hidden: false
       experimental: false

_data/scout-cli/docker_scout_quickview.yaml

@@ -0,0 +1,91 @@
+command: docker scout quickview
+short: Quick overview of an image
+long: |-
+    The `docker scout quickview` command displays a quick overview of an image.
+    It displays a summary of the vulnerabilities in the image and the vulnerabilities from the base image.
+    If available it also displays base image refresh and update recommendations.
+usage: docker scout quickview IMAGE|DIRECTORY|ARCHIVE
+pname: docker scout
+plink: docker_scout.yaml
+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: 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 --type archive.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: type
+      value_type: string
+      default_value: image
+      description: |-
+        Type of the image to analyze. Can be one of:
+        - image
+        - oci-dir
+        - archive (docker save tarball)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+examples: |-
+    ### Quick overview of an image
+
+    ```console
+    $ docker scout quickview golang:1.19.4
+        ...Pulling
+        ✓ Pulled
+        ✓ SBOM of image already cached, 278 packages indexed
+
+      Your image  golang:1.19.4                          │    5C     3H     6M    63L
+      Base image  buildpack-deps:bullseye-scm            │    5C     1H     3M    48L     6?
+      Refreshed base image  buildpack-deps:bullseye-scm  │    0C     0H     0M    42L
+                                                         │    -5     -1     -3     -6     -6
+      Updated base image  buildpack-deps:sid-scm         │    0C     0H     1M    29L
+                                                         │    -5     -1     -2    -19     -6
+
+      │ Know more about vulnerabilities:
+      │    docker scout cves golang:1.19.4
+      │ Know more about base image update recommendations:
+      │    docker scout recommendations golang:1.19.4
+    ```
+deprecated: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+

_data/scout-cli/docker_scout_recommendations.yaml

@@ -0,0 +1,133 @@
+command: docker scout recommendations
+short: Display available base image updates and remediation recommendations
+long: |-
+    The `docker scout recommendations` command display recommendations for base images updates.
+    It analyzes the image and display recommendations to refresh or update the base image.
+    For each recommendation it shows a list of benefits like less vulnerabilities, smaller image, etc.
+
+    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 base image updates and remediation recommendations.
+
+    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` flag.
+usage: docker scout recommendations IMAGE|DIRECTORY|ARCHIVE
+pname: docker scout
+plink: docker_scout.yaml
+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: only-refresh
+      value_type: bool
+      default_value: "false"
+      description: Only display base image refresh recommendations
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: only-update
+      value_type: bool
+      default_value: "false"
+      description: Only display base image update recommendations
+      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 --type archive.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: tag
+      value_type: string
+      description: Specify tag
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: type
+      value_type: string
+      default_value: image
+      description: |-
+        Type of the image to analyze. Can be one of:
+        - image
+        - oci-dir
+        - archive (docker save tarball)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+examples: |-
+    ### Display base image update recommendations
+
+    ```console
+    $ docker scout recommendations golang:1.19.4
+    ```
+
+    ### Display base image refresh only recommendations
+
+    ```console
+    $ docker scout recommendations --only-refresh golang:1.19.4
+    ```
+
+    ### Display base image update only recommendations
+
+    ```console
+    $ docker scout recommendations --only-update golang:1.19.4
+    ```
+deprecated: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+

_data/scout-cli/docker_scout_sbom.yaml

@@ -0,0 +1,135 @@
+command: docker scout sbom
+short: Generate or display SBOM of an image
+long: |-
+    The `docker scout sbom` command analyzes a software artifact to generate the corresponding Software Bill Of Materials (SBOM).
+
+    The SBOM can be used to list all packages, or the ones from a specific type (as dep, maven, etc).
+
+    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` flag.
+usage: docker scout sbom IMAGE|DIRECTORY|ARCHIVE
+pname: docker scout
+plink: docker_scout.yaml
+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: format
+      value_type: string
+      default_value: json
+      description: |-
+        Output format:
+        - list: list of packages of the image
+        - json: json representation of the SBOM
+      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)
+        Can only be used with --format list
+      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 --type archive.
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: type
+      value_type: string
+      default_value: image
+      description: |-
+        Type of the image to analyze. Can be one of:
+        - image
+        - oci-dir
+        - archive (docker save tarball)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+examples: |-
+    ### Display the list of packages
+
+    ```console
+    $ docker scout sbom alpine
+    ```
+
+    ### Only display packages of a specific type
+
+    ```console
+     $ docker scout sbom --only-package-type apk alpine
+    ```
+
+    ### Display the full SBOM as json
+
+    ```console
+    $ docker scout sbom --format json alpine
+    ```
+
+    ### Write SBOM to a file
+
+    ```console
+    $ docker scout sbom --format json --output alpine.sbom alpine
+    ```
+deprecated: false
+experimental: false
+experimentalcli: false
+kubernetes: false
+swarm: false
+

_data/toc.yaml

@@ -621,8 +621,14 @@ reference:
       section:
       - path: /engine/reference/commandline/scout/
         title: docker scout
+      - path: /engine/reference/commandline/scout_compare/
+        title: docker scout compare
       - path: /engine/reference/commandline/scout_cves/
         title: docker scout cves
+      - path: /engine/reference/commandline/scout_quickview/
+        title: docker scout quickview
+      - path: /engine/reference/commandline/scout_recommendations/
+        title: docker scout recommendations
       - path: /engine/reference/commandline/scout_version/
         title: docker scout version
     - path: /engine/reference/commandline/search/

engine/reference/commandline/scout_compare.md

@@ -0,0 +1,13 @@
+---
+datafolder: scout-cli
+datafile: docker_scout_compare
+title: docker scout compare
+---
+<!--
+This page is automatically generated from Docker's source code. If you want to
+suggest a change to the text that appears here, open a ticket or pull request
+in the source repository on GitHub:
+
+https://github.com/docker/scout-cli-plugin
+-->
+{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

engine/reference/commandline/scout_quickview.md

@@ -0,0 +1,13 @@
+---
+datafolder: scout-cli
+datafile: docker_scout_quickview
+title: docker scout quickview
+---
+<!--
+This page is automatically generated from Docker's source code. If you want to
+suggest a change to the text that appears here, open a ticket or pull request
+in the source repository on GitHub:
+
+https://github.com/docker/scout-cli-plugin
+-->
+{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

engine/reference/commandline/scout_recommendations.md

@@ -0,0 +1,13 @@
+---
+datafolder: scout-cli
+datafile: docker_scout_recommendations
+title: docker scout recommendations
+---
+<!--
+This page is automatically generated from Docker's source code. If you want to
+suggest a change to the text that appears here, open a ticket or pull request
+in the source repository on GitHub:
+
+https://github.com/docker/scout-cli-plugin
+-->
+{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

engine/reference/commandline/scout_sbom.md

@@ -0,0 +1,13 @@
+---
+datafolder: scout-cli
+datafile: docker_scout_sbom
+title: docker scout sbom
+---
+<!--
+This page is automatically generated from Docker's source code. If you want to
+suggest a change to the text that appears here, open a ticket or pull request
+in the source repository on GitHub:
+
+https://github.com/docker/scout-cli-plugin
+-->
+{% include cli.md datafolder=page.datafolder datafile=page.datafile %}