Merge a239655 into 471c526

dist/docker-scout_1.6.0_checksums.txt

@@ -0,0 +1,6 @@
+3cbe1b2dd9d4fed18e4ffc2f6fc82b327d7d647a1b3a30b26db338714d5426e9  docker-scout_1.6.0_darwin_amd64.tar.gz
+6dff55b9f5c4740a4e460168ed070d09096e7deb214c6c1c292dc33e25e1d243  docker-scout_1.6.0_darwin_arm64.tar.gz
+4f8b506542a60581345b6480bea7c5f35dba29dd98116ee8781bae4f32e30b43  docker-scout_1.6.0_linux_amd64.tar.gz
+a5120d1f4ef9cf0c67620e2da3f32f53b4c625a3a35d8e71523b03f20c766b1f  docker-scout_1.6.0_linux_arm64.tar.gz
+997d970c7ab55df29571ea2c59faa1912418a18afa320bfb2a5be780f3bf0854  docker-scout_1.6.0_windows_amd64.zip
+2373583ffd9731825d3b92054e58c38d290458ba4a2abffab2b60d8ac6e7a9fd  docker-scout_1.6.0_windows_arm64.zip

docs/docker_scout_attestation_add.yaml

@@ -1,4 +1,5 @@
 command: docker scout attestation add
+aliases: docker scout attestation add, docker scout attest add
 short: Add attestation to image
 long: The docker scout attestation add command adds attestations to images.
 usage: docker scout attestation add OPTIONS IMAGE [IMAGE...]

docs/docker_scout_cache_prune.yaml

@@ -9,6 +9,16 @@ usage: docker scout cache prune
 pname: docker scout cache
 plink: docker_scout_cache.yaml
 options:
+    - option: epss
+      value_type: bool
+      default_value: "false"
+      description: Prune cached EPSS scores
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: force
       shorthand: f
       value_type: bool

docs/docker_scout_cves.yaml

@@ -27,6 +27,8 @@ long: |-
     - `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
@@ -50,6 +52,49 @@ options:
       experimentalcli: false
       kubernetes: false
       swarm: false
+    - option: epss
+      value_type: bool
+      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
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: epss-date
+      value_type: string
+      description: Date to use for EPSS scores
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: epss-percentile
+      value_type: float32
+      default_value: "0"
+      description: |
+        Exclude CVEs with EPSS scores less than the specified percentile (0 to 1)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
+    - option: epss-score
+      value_type: float32
+      default_value: "0"
+      description: |
+        Exclude CVEs with EPSS scores less than the specified value (0 to 1)
+      deprecated: false
+      hidden: false
+      experimental: false
+      experimentalcli: false
+      kubernetes: false
+      swarm: false
     - option: exit-code
       shorthand: e
       value_type: bool
@@ -311,9 +356,9 @@ examples: |-
     ```console
     $ docker scout cves alpine
     Analyzing image alpine
-        ✓ Image stored for indexing
-        ✓ Indexed 18 packages
-        ✓ No vulnerable package detected
+    ✓ Image stored for indexing
+    ✓ Indexed 18 packages
+    ✓ No vulnerable package detected
     ```
 
     ### Display vulnerabilities from a `docker save` tarball
@@ -323,9 +368,9 @@ examples: |-
 
     $ docker scout cves archive://alpine.tar
     Analyzing archive alpine.tar
-        ✓ Archive read
-        ✓ SBOM of image already cached, 18 packages indexed
-        ✓ No vulnerable package detected
+    ✓ Archive read
+    ✓ SBOM of image already cached, 18 packages indexed
+    ✓ No vulnerable package detected
     ```
 
     ### Display vulnerabilities from an OCI directory
@@ -335,10 +380,10 @@ examples: |-
 
     $ docker scout cves oci-dir://alpine
     Analyzing OCI directory alpine
-        ✓ OCI directory read
-        ✓ Image stored for indexing
-        ✓ Indexed 19 packages
-        ✓ No vulnerable package detected
+    ✓ OCI directory read
+    ✓ Image stored for indexing
+    ✓ Indexed 19 packages
+    ✓ No vulnerable package detected
     ```
 
     ### Display vulnerabilities from the current directory
@@ -352,9 +397,9 @@ examples: |-
     ```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
+    ✓ SBOM of image already cached, 18 packages indexed
+    ✓ No vulnerable package detected
+    ✓ Report written to alpine.sarif.json
     ```
 
     ### Display markdown output
@@ -363,9 +408,9 @@ examples: |-
 
     ```console
     $ docker scout cves --format markdown alpine
-        ✓ Pulled
-        ✓ SBOM of image already cached, 19 packages indexed
-        ✗ Detected 1 vulnerable package with 3 vulnerabilities
+    ✓ 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>
@@ -387,14 +432,86 @@ examples: |-
 
     ```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
+    ✓ Pulled
+    ✓ SBOM of image already cached, 296 packages indexed
+    ✗ Detected 1 vulnerable package with 40 vulnerabilities
 
-       Name   Version   Type         Vulnerabilities
+    Name   Version   Type         Vulnerabilities
     ───────────────────────────────────────────────────────────
-      stdlib  1.18     golang     2C    29H     8M     1L
+    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_quickview.yaml

@@ -31,6 +31,8 @@ long: |-
     - `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 quickview [IMAGE|DIRECTORY|ARCHIVE]
 pname: docker scout
 plink: docker_scout.yaml
@@ -145,6 +147,22 @@ examples: |-
     ```console
     $ docker scout qv
     ```
+
+    ### Quick overview from an SPDX file
+
+    ```console
+    $  syft -o spdx-json alpine:3.16.1 | docker scout quickview sbom://
+     ✔ 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]
+
+      Target   │ <stdin>        │    1C     2H     8M     0L
+        digest │  274a317d88b5  │
+    ```
 deprecated: false
 experimental: false
 experimentalcli: false

docs/scout_attestation_add.md

@@ -3,6 +3,10 @@
 <!---MARKER_GEN_START-->
 Add attestation to image
 
+### Aliases
+
+`docker scout attestation add`, `docker scout attest add`
+
 ### Options
 
 | Name               | Type          | Default | Description                             |

docs/scout_cache_prune.md

@@ -7,6 +7,7 @@ Remove temporary or cached data
 
 | Name            | Type | Default | Description                    |
 |:----------------|:-----|:--------|:-------------------------------|
+| `--epss`        |      |         | Prune cached EPSS scores       |
 | `-f`, `--force` |      |         | Do not prompt for confirmation |
 | `--sboms`       |      |         | Prune cached SBOMs             |