From df7dfffa2440e4d8ff18ead2e9d0933277438651 Mon Sep 17 00:00:00 2001 From: Yves Brissaud Date: Fri, 24 Mar 2023 19:43:06 +0100 Subject: [PATCH 1/3] scout: update cli documentation Signed-off-by: Yves Brissaud --- _data/scout-cli/docker_scout.yaml | 6 + _data/scout-cli/docker_scout_compare.yaml | 212 ++++++++++++++++++ _data/scout-cli/docker_scout_cves.yaml | 6 +- _data/scout-cli/docker_scout_quickview.yaml | 91 ++++++++ .../docker_scout_recommendations.yaml | 133 +++++++++++ _data/scout-cli/docker_scout_sbom.yaml | 135 +++++++++++ engine/reference/commandline/scout_compare.md | 13 ++ .../reference/commandline/scout_quickview.md | 13 ++ .../commandline/scout_recommendations.md | 13 ++ engine/reference/commandline/scout_sbom.md | 13 ++ 10 files changed, 632 insertions(+), 3 deletions(-) create mode 100644 _data/scout-cli/docker_scout_compare.yaml create mode 100644 _data/scout-cli/docker_scout_quickview.yaml create mode 100644 _data/scout-cli/docker_scout_recommendations.yaml create mode 100644 _data/scout-cli/docker_scout_sbom.yaml create mode 100644 engine/reference/commandline/scout_compare.md create mode 100644 engine/reference/commandline/scout_quickview.md create mode 100644 engine/reference/commandline/scout_recommendations.md create mode 100644 engine/reference/commandline/scout_sbom.md diff --git a/_data/scout-cli/docker_scout.yaml b/_data/scout-cli/docker_scout.yaml index bf884ac855..9e06255a14 100644 --- a/_data/scout-cli/docker_scout.yaml +++ b/_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 diff --git a/_data/scout-cli/docker_scout_compare.yaml b/_data/scout-cli/docker_scout_compare.yaml new file mode 100644 index 0000000000..a22f4473c1 --- /dev/null +++ b/_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 display 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 + diff --git a/_data/scout-cli/docker_scout_cves.yaml b/_data/scout-cli/docker_scout_cves.yaml index c852b528a6..bb5bf4f596 100644 --- a/_data/scout-cli/docker_scout_cves.yaml +++ b/_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 diff --git a/_data/scout-cli/docker_scout_quickview.yaml b/_data/scout-cli/docker_scout_quickview.yaml new file mode 100644 index 0000000000..602013ba79 --- /dev/null +++ b/_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 one specifically in 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 + diff --git a/_data/scout-cli/docker_scout_recommendations.yaml b/_data/scout-cli/docker_scout_recommendations.yaml new file mode 100644 index 0000000000..5200ca30ea --- /dev/null +++ b/_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 + diff --git a/_data/scout-cli/docker_scout_sbom.yaml b/_data/scout-cli/docker_scout_sbom.yaml new file mode 100644 index 0000000000..205c7b52c5 --- /dev/null +++ b/_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 + diff --git a/engine/reference/commandline/scout_compare.md b/engine/reference/commandline/scout_compare.md new file mode 100644 index 0000000000..f3c365159b --- /dev/null +++ b/engine/reference/commandline/scout_compare.md @@ -0,0 +1,13 @@ +--- +datafolder: scout-cli +datafile: docker_scout_compare +title: docker scout compare +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/scout_quickview.md b/engine/reference/commandline/scout_quickview.md new file mode 100644 index 0000000000..ec6821b938 --- /dev/null +++ b/engine/reference/commandline/scout_quickview.md @@ -0,0 +1,13 @@ +--- +datafolder: scout-cli +datafile: docker_scout_quickview +title: docker scout quickview +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/scout_recommendations.md b/engine/reference/commandline/scout_recommendations.md new file mode 100644 index 0000000000..2e7c7226ef --- /dev/null +++ b/engine/reference/commandline/scout_recommendations.md @@ -0,0 +1,13 @@ +--- +datafolder: scout-cli +datafile: docker_scout_recommendations +title: docker scout recommendations +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/scout_sbom.md b/engine/reference/commandline/scout_sbom.md new file mode 100644 index 0000000000..09e7068915 --- /dev/null +++ b/engine/reference/commandline/scout_sbom.md @@ -0,0 +1,13 @@ +--- +datafolder: scout-cli +datafile: docker_scout_sbom +title: docker scout sbom +--- + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} From ab957ffbc2a5c78344b164d2ebb28312cc06a31f Mon Sep 17 00:00:00 2001 From: Chris Chinchilla Date: Mon, 27 Mar 2023 09:53:22 +0100 Subject: [PATCH 2/3] Add menu items --- _data/toc.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_data/toc.yaml b/_data/toc.yaml index 1dd9d1ffb1..d4eb5cf89c 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -609,8 +609,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/ From 79c26e0b78d72d42722d483499ed38d3fbdafd0b Mon Sep 17 00:00:00 2001 From: Yves Brissaud Date: Wed, 5 Apr 2023 16:02:36 +0200 Subject: [PATCH 3/3] small fixes Signed-off-by: Yves Brissaud --- _data/scout-cli/docker_scout_compare.yaml | 2 +- _data/scout-cli/docker_scout_quickview.yaml | 2 +- _data/scout-cli/docker_scout_sbom.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_data/scout-cli/docker_scout_compare.yaml b/_data/scout-cli/docker_scout_compare.yaml index a22f4473c1..cf01b4d5bf 100644 --- a/_data/scout-cli/docker_scout_compare.yaml +++ b/_data/scout-cli/docker_scout_compare.yaml @@ -1,7 +1,7 @@ command: docker scout compare short: '[early preview] Compare two images and display differences' long: |- - The `docker scout compare` command analyzes two images and display a comparison of both. + 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 diff --git a/_data/scout-cli/docker_scout_quickview.yaml b/_data/scout-cli/docker_scout_quickview.yaml index 602013ba79..9c8c2346bb 100644 --- a/_data/scout-cli/docker_scout_quickview.yaml +++ b/_data/scout-cli/docker_scout_quickview.yaml @@ -2,7 +2,7 @@ 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 one specifically in the base 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 diff --git a/_data/scout-cli/docker_scout_sbom.yaml b/_data/scout-cli/docker_scout_sbom.yaml index 205c7b52c5..7a1d3e99e1 100644 --- a/_data/scout-cli/docker_scout_sbom.yaml +++ b/_data/scout-cli/docker_scout_sbom.yaml @@ -1,7 +1,7 @@ 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 `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).