diff --git a/docs/docker_scout_compare.yaml b/docs/docker_scout_compare.yaml index dfcb4cc..6848456 100644 --- a/docs/docker_scout_compare.yaml +++ b/docs/docker_scout_compare.yaml @@ -2,39 +2,40 @@ 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. + 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 + 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. + 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 built image is used - as a comparison target. + If no image is specified, the most recently built image will be 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 + 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://` 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:// use an SBOM as 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 @@ -336,42 +337,7 @@ inherited_options: 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 - ``` +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" deprecated: false experimental: false experimentalcli: true diff --git a/docs/docker_scout_cves.yaml b/docs/docker_scout_cves.yaml index d7bd9bc..44c84c3 100644 --- a/docs/docker_scout_cves.yaml +++ b/docs/docker_scout_cves.yaml @@ -1,7 +1,7 @@ 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. @@ -9,26 +9,28 @@ long: |- - 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://` 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. + - 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 usage: docker scout cves [OPTIONS] [IMAGE|DIRECTORY|ARCHIVE] pname: docker scout plink: docker_scout.yaml @@ -57,7 +59,6 @@ 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 @@ -398,168 +399,7 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -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 -

:mag: Vulnerabilities of alpine

- -
:package: Image Reference alpine - - - - - -
digestsha256:e3bd82196e98898cae9fe7fbfd6e2436530485974dc4fb3b7ddb69134eda2407
vulnerabilitiescritical: 0 high: 0 medium: 2 low: 0 unspecified: 1
platformlinux/arm64
size3.3 MB
packages19
-
- - ... - ``` - - ### 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 +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" deprecated: false experimental: false experimentalcli: false diff --git a/docs/docker_scout_policy.yaml b/docs/docker_scout_policy.yaml index 077907e..1e265eb 100644 --- a/docs/docker_scout_policy.yaml +++ b/docs/docker_scout_policy.yaml @@ -1,11 +1,8 @@ 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. - The image analysis is uploaded to Docker Scout where policies get evaluated. - - The policy evaluation results may take a few minutes to become available. +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. usage: docker scout policy [IMAGE | REPO] pname: docker scout plink: docker_scout.yaml @@ -108,30 +105,7 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -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 - ``` +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" deprecated: false experimental: false experimentalcli: true diff --git a/docs/docker_scout_push.yaml b/docs/docker_scout_push.yaml index 361b89e..ab2d7cd 100644 --- a/docs/docker_scout_push.yaml +++ b/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 lets you push an image or analysis result to Docker Scout. + The docker scout push command allows to push an image or image index to Docker Scout. usage: docker scout push IMAGE pname: docker scout plink: docker_scout.yaml @@ -103,12 +103,7 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Push an image to Docker Scout - - ```console - $ docker scout push --org my-org registry.example.com/repo:tag - ``` +examples: " Push an image to Docker Scout\n $ docker scout push --org my-org registry.example.com/repo:tag\e[0m" deprecated: false experimental: false experimentalcli: false diff --git a/docs/docker_scout_quickview.yaml b/docs/docker_scout_quickview.yaml index 1ff9869..3b68f7c 100644 --- a/docs/docker_scout_quickview.yaml +++ b/docs/docker_scout_quickview.yaml @@ -2,10 +2,9 @@ command: docker scout quickview aliases: docker scout quickview, docker scout qv 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 specified image - and vulnerabilities from the base image. - If available, it also displays base image refresh and update recommendations. + 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. If no image is specified, the most recently built image is used. @@ -13,26 +12,27 @@ long: |- - 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://` 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. + - 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 usage: docker scout quickview [IMAGE|DIRECTORY|ARCHIVE] pname: docker scout plink: docker_scout.yaml @@ -186,44 +186,7 @@ inherited_options: 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 - ``` - - ### Quick overview of the most recently built image - - ```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 │ │ 1C 2H 8M 0L - digest │ 274a317d88b5 │ - ``` +examples: " Display quick overview of the most recently built image\n$ docker scout quickview qv\e[0m\n ...Pulling\n ✓ Pulled\n ✓ SBOM of image already cached, 278 packages indexed\n\n Your image golang:1.19.4 │ 5C 3H 6M 63L\n Base image buildpack-deps:bullseye-scm │ 5C 1H 3M 48L 6?\n Refreshed base image buildpack-deps:bullseye-scm │ 0C 0H 0M 42L\n │ -5 -1 -3 -6 -6\n Updated base image buildpack-deps:sid-scm │ 0C 0H 1M 29L\n │ -5 -1 -2 -19 -6\n" deprecated: false experimental: false experimentalcli: false diff --git a/docs/docker_scout_sbom.yaml b/docs/docker_scout_sbom.yaml index d51d5d5..87e5203 100644 --- a/docs/docker_scout_sbom.yaml +++ b/docs/docker_scout_sbom.yaml @@ -1,12 +1,9 @@ command: docker scout sbom short: Generate or display SBOM of an image long: |- - The `docker scout sbom` command analyzes a software artifact to generate a - Software Bill Of Materials (SBOM). + The docker scout sbom command analyzes a software artifact to generate the corresponding Software Bill Of Materials (SBOM). - The SBOM contains a list of all packages in the image. - You can use the `--format` flag to filter the output of the command - to display only packages of a specific type. + The SBOM can be used to list all packages, or the ones from a specific type (as dep, maven, etc). If no image is specified, the most recently built image is used. @@ -14,24 +11,26 @@ long: |- - 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 + - 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 usage: docker scout sbom [IMAGE|DIRECTORY|ARCHIVE] pname: docker scout plink: docker_scout.yaml @@ -124,36 +123,7 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -examples: |- - ### Display the list of packages - - ```console - $ docker scout sbom --format list alpine - ``` - - ### Only display packages of a specific type - - ```console - $ docker scout sbom --format list --only-package-type apk alpine - ``` - - ### Display the full SBOM in JSON format - - ```console - $ docker scout sbom alpine - ``` - - ### Display the full SBOM of the most recently built image - - ```console - $ docker scout sbom - ``` - - ### Write SBOM to a file - - ```console - $ docker scout sbom --output alpine.sbom alpine - ``` +examples: " Display the list of packages\n $ docker scout sbom alpine --format list\e[0m\n\n Only display packages of a specific type\n $ docker scout sbom --format list --only-package-type apk alpine\e[0m\n\n Display the full SBOM as json of the most recently built image\n $ docker scout sbom\e[0m\n\n Write SBOM to a file\n $ docker scout sbom --output alpine.sbom alpine\e[0m" deprecated: false experimental: false experimentalcli: false