[BOT] Update docs for v1.20.1 release

Author: chrispatrick

docs/docker_scout_compare.yaml

@@ -2,40 +2,39 @@ 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 of both.
+    The `docker scout compare` command analyzes two images and displays a comparison.
 
-        This command is experimental and its behaviour might change in the future
+    > 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.
+    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 will be used.
+    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
+    - Tarball archives, as created by `docker save`
     - Local directory or file
 
-    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
+    - `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:// use an SBOM as SPDX file or in-toto attestation file with SPDX predicate or syft json SBOM file
+    - `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
@@ -337,7 +336,42 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
-examples: "  Compare the most recently built image to a reference\n  $ docker scout compare --to namespace/repo:latest\e[0m\n\n  Compare an image to the latest tag\n  $ docker scout compare --to namespace/repo:latest namespace/repo:v1.2.3-pre\e[0m\n\n  Compare a local build to the same tag from the registry\n  $ docker scout compare local://namespace/repo:v1.2.3 --to registry://namespace/repo:v1.2.3\e[0m\n\n  Ignore base images\n  $ docker scout compare --ignore-base --to namespace/repo:latest namespace/repo:v1.2.3-pre\e[0m\n\n  Generate a markdown output\n  $ docker scout compare --format markdown --to namespace/repo:latest namespace/repo:v1.2.3-pre\e[0m\n\n  Only compare maven packages and only display critical vulnerabilities for maven packages\n  $ docker scout compare --only-package-type maven --only-severity critical --to namespace/repo:latest namespace/repo:v1.2.3-pre\e[0m"
+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

docs/docker_scout_cves.yaml

@@ -1,36 +1,34 @@
 command: docker scout cves
 short: Display CVEs identified in a software artifact
 long: |-
-    The docker scout cves command analyzes a software artifact for vulnerabilities.
+    The `docker scout cves` command analyzes a software artifact for vulnerabilities.
 
     If no image is specified, the most recently built image is used.
 
     The following artifact types are supported:
 
     - Images
     - OCI layout directories
-    - Tarball archives, as created by docker save
+    - Tarball archives, as created by `docker save`
     - Local directory or file
-    - SPDX file or in-toto attestation file with SPDX predicate
-
-    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
+    - `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:// use an SBOM as SPDX file or in-toto attestation file with SPDX predicate or syft json SBOM file
+    - `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
+        In case of `sbom://` prefix, if the file is not defined then it will try to read it from the standard input.
 usage: docker scout cves [OPTIONS] [IMAGE|DIRECTORY|ARCHIVE]
 pname: docker scout
 plink: docker_scout.yaml
@@ -59,6 +57,7 @@ options:
       default_value: "false"
       description: |
         Display the EPSS scores and organize the package's CVEs according to their EPSS score
+      details_url: '#epss'
       deprecated: false
       hidden: false
       experimental: false
@@ -399,7 +398,168 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
-examples: "  Display vulnerabilities for the most recently built image\n  $ docker scout cves\e[0m\n\n  Display vulnerabilities grouped by package\n  $ docker scout cves alpine\e[0m\n\n  Display vulnerabilities from a docker save tarball\n  $ docker save alpine > alpine.tar\e[0m\n  $ docker scout cves archive://alpine.tar\e[0m\n\n  Display vulnerabilities from an OCI directory\n  $ skopeo copy --override-os linux docker://alpine oci:alpine\e[0m\n  $ docker scout cves oci-dir://alpine\e[0m\n\n  Display vulnerabilities from the current directory\n  $ docker scout cves fs://.\e[0m\n\n  Export vulnerabilities to a SARIF JSON file\n  $ docker scout cves --format sarif --output alpine.sarif.json alpine\e[0m\n\n  Markdown output, including HTML tags. To be used in Pull Request comments for instance.\n  $ docker scout cves --format markdown alpine\e[0m\n\n  List all Go packages of the image that are vulnerable\n  $ docker scout cves --format only-packages --only-package-type golang --only-vuln-packages golang:1.18.0\e[0m\n\n  List vulnerabilities from an SPDX file\n  $ syft -o spdx-json alpine | docker scout cves sbom://\e[0m"
+examples: |-
+    ### Display vulnerabilities grouped by package
+
+    ```console
+    $ docker scout cves alpine
+    Analyzing image alpine
+    ✓ Image stored for indexing
+    ✓ Indexed 18 packages
+    ✓ No vulnerable package detected
+    ```
+
+    ### Display vulnerabilities from a `docker save` tarball
+
+    ```console
+    $ docker save alpine > alpine.tar
+
+    $ docker scout cves archive://alpine.tar
+    Analyzing archive alpine.tar
+    ✓ Archive read
+    ✓ SBOM of image already cached, 18 packages indexed
+    ✓ No vulnerable package detected
+    ```
+
+    ### Display vulnerabilities from an OCI directory
+
+    ```console
+    $ skopeo copy --override-os linux docker://alpine oci:alpine
+
+    $ docker scout cves oci-dir://alpine
+    Analyzing OCI directory alpine
+    ✓ OCI directory read
+    ✓ Image stored for indexing
+    ✓ Indexed 19 packages
+    ✓ No vulnerable package detected
+    ```
+
+    ### Display vulnerabilities from the current directory
+
+    ```console
+    $ docker scout cves fs://.
+    ```
+
+    ### Export vulnerabilities to a SARIF JSON file
+
+    ```console
+    $ docker scout cves --format sarif --output alpine.sarif.json alpine
+    Analyzing image alpine
+    ✓ SBOM of image already cached, 18 packages indexed
+    ✓ No vulnerable package detected
+    ✓ Report written to alpine.sarif.json
+    ```
+
+    ### Display markdown output
+
+    The following example shows how to generate the vulnerability report as markdown.
+
+    ```console
+    $ docker scout cves --format markdown alpine
+    ✓ Pulled
+    ✓ SBOM of image already cached, 19 packages indexed
+    ✗ Detected 1 vulnerable package with 3 vulnerabilities
+    <h2>:mag: Vulnerabilities of <code>alpine</code></h2>
+
+    <details open="true"><summary>:package: Image Reference</strong> <code>alpine</code></summary>
+    <table>
+    <tr><td>digest</td><td><code>sha256:e3bd82196e98898cae9fe7fbfd6e2436530485974dc4fb3b7ddb69134eda2407</code></td><tr><tr><td>vulnerabilities</td><td><img alt="critical: 0" src="https://img.shields.io/badge/critical-0-lightgrey"/> <img alt="high: 0" src="https://img.shields.io/badge/high-0-lightgrey"/> <img alt="medium: 2" src="https://img.shields.io/badge/medium-2-fbb552"/> <img alt="low: 0" src="https://img.shields.io/badge/low-0-lightgrey"/> <img alt="unspecified: 1" src="https://img.shields.io/badge/unspecified-1-lightgrey"/></td></tr>
+    <tr><td>platform</td><td>linux/arm64</td></tr>
+    <tr><td>size</td><td>3.3 MB</td></tr>
+    <tr><td>packages</td><td>19</td></tr>
+    </table>
+    </details></table>
+    </details>
+    ...
+    ```
+
+    ### List all vulnerable packages of a certain type
+
+    The following example shows how to generate a list of packages, only including
+    packages of the specified type, and only showing packages that are vulnerable.
+
+    ```console
+    $ docker scout cves --format only-packages --only-package-type golang --only-vuln-packages golang:1.18.0
+    ✓ Pulled
+    ✓ SBOM of image already cached, 296 packages indexed
+    ✗ Detected 1 vulnerable package with 40 vulnerabilities
+
+    Name   Version   Type         Vulnerabilities
+    ───────────────────────────────────────────────────────────
+    stdlib  1.18     golang     2C    29H     8M     1L
+    ```
+
+    ### Display EPSS score (--epss) {#epss}
+
+    The `--epss` flag adds [Exploit Prediction Scoring System (EPSS)](https://www.first.org/epss/)
+    scores to the `docker scout cves` output. EPSS scores are estimates of the likelihood (probability)
+    that a software vulnerability will be exploited in the wild in the next 30 days.
+    The higher the score, the greater the probability that a vulnerability will be exploited.
+
+    ```console {hl_lines="13,14"}
+    $ docker scout cves --epss nginx
+     ✓ Provenance obtained from attestation
+     ✓ SBOM obtained from attestation, 232 packages indexed
+     ✓ Pulled
+     ✗ Detected 23 vulnerable packages with a total of 39 vulnerabilities
+
+    ...
+
+     ✗ HIGH CVE-2023-52425
+       https://scout.docker.com/v/CVE-2023-52425
+       Affected range  : >=2.5.0-1
+       Fixed version   : not fixed
+       EPSS Score      : 0.000510
+       EPSS Percentile : 0.173680
+    ```
+
+    - `EPSS Score` is a floating point number between 0 and 1 representing the probability of exploitation in the wild in the next 30 days (following score publication).
+    - `EPSS Percentile` is the percentile of the current score, the proportion of all scored vulnerabilities with the same or a lower EPSS score.
+
+    You can use the `--epss-score` and `--epss-percentile` flags to filter the output
+    of `docker scout cves` based on these scores. For example,
+    to only show vulnerabilities with an EPSS score higher than 0.5:
+
+    ```console
+    $ docker scout cves --epss --epss-score 0.5 nginx
+     ✓ SBOM of image already cached, 232 packages indexed
+     ✓ EPSS scores for 2024-03-01 already cached
+     ✗ Detected 1 vulnerable package with 1 vulnerability
+
+    ...
+
+     ✗ LOW CVE-2023-44487
+       https://scout.docker.com/v/CVE-2023-44487
+       Affected range  : >=1.22.1-9
+       Fixed version   : not fixed
+       EPSS Score      : 0.705850
+       EPSS Percentile : 0.979410
+    ```
+
+    EPSS scores are updated on a daily basis.
+    By default, the latest available score is displayed.
+    You can use the `--epss-date` flag to manually specify a date
+    in the format `yyyy-mm-dd` for fetching EPSS scores.
+
+    ```console
+    $ docker scout cves --epss --epss-date 2024-01-02 nginx
+    ```
+
+    ### List vulnerabilities from an SPDX file
+
+    The following example shows how to generate a list of vulnerabilities from an SPDX file using `syft`.
+
+    ```console
+    $ syft -o spdx-json alpine:3.16.1 | docker scout cves sbom://
+     ✔ Pulled image
+     ✔ Loaded image                                                                                                                              alpine:3.16.1
+     ✔ Parsed image                                                                    sha256:3d81c46cd8756ddb6db9ec36fa06a6fb71c287fb265232ba516739dc67a5f07d
+     ✔ Cataloged contents                                                                     274a317d88b54f9e67799244a1250cad3fe7080f45249fa9167d1f871218d35f
+       ├── ✔ Packages                        [14 packages]
+       ├── ✔ File digests                    [75 files]
+       ├── ✔ File metadata                   [75 locations]
+       └── ✔ Executables                     [16 executables]
+        ✗ Detected 2 vulnerable packages with a total of 11 vulnerabilities
 deprecated: false
 experimental: false
 experimentalcli: false

docs/docker_scout_policy.yaml

@@ -1,8 +1,11 @@
 command: docker scout policy
 short: |
     Evaluate policies against an image and display the policy evaluation results (experimental)
-long: |
-    The docker scout policy command evaluates policies against an image and displays the policy evaluation results. If the policy results for an image are already available in the Scout platform, they are retrieved from there, otherwise the policies are evaluated locally. It can also compare policy results for a repository in a specific environment.
+long: |-
+    The `docker scout policy` command evaluates policies against an image.
+    The image analysis is uploaded to Docker Scout where policies get evaluated.
+
+    The policy evaluation results may take a few minutes to become available.
 usage: docker scout policy [IMAGE | REPO]
 pname: docker scout
 plink: docker_scout.yaml
@@ -105,7 +108,30 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
-examples: "  Evaluate policies against an image:\n  $ docker scout policy IMAGE\e[0m\n\n  Evaluate policies against an image for a specific organization:\n  $ docker scout policy IMAGE --org ORG\e[0m\n\n  Evaluate policies against an image with a specific platform:\n  $ docker scout policy IMAGE --platform PLATFORM\e[0m\n\n  Compare policy results for a repository in a specific environment:\n  $ docker scout policy REPO --to-env ENV\e[0m"
+examples: |-
+    ### Evaluate policies against an image and display the results
+
+    ```console
+    $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1
+    ```
+
+    ### Evaluate policies against an image for a specific organization
+
+    ```console
+    $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 --org dockerscoutpolicy
+    ```
+
+    ### Evaluate policies against an image with a specific platform
+
+    ```console
+    $ docker scout policy dockerscoutpolicy/customers-api-service:0.0.1 --platform linux/amd64
+    ```
+
+    ### Compare policy results for a repository in a specific environment
+
+    ```console
+    $ docker scout policy dockerscoutpolicy/customers-api-service --to-env production
+    ```
 deprecated: false
 experimental: false
 experimentalcli: true

docs/docker_scout_push.yaml

@@ -1,7 +1,7 @@
 command: docker scout push
 short: Push an image or image index to Docker Scout
 long: |
-    The docker scout push command allows to push an image or image index to Docker Scout.
+    The `docker scout push` command lets you push an image or analysis result to Docker Scout.
 usage: docker scout push IMAGE
 pname: docker scout
 plink: docker_scout.yaml
@@ -103,7 +103,12 @@ inherited_options:
       experimentalcli: false
       kubernetes: false
       swarm: false
-examples: "  Push an image to Docker Scout\n  $ docker scout push --org my-org registry.example.com/repo:tag\e[0m"
+examples: |-
+    ### Push an image to Docker Scout
+
+    ```console
+    $ docker scout push --org my-org registry.example.com/repo:tag
+    ```
 deprecated: false
 experimental: false
 experimentalcli: false