diff --git a/_config.yml b/_config.yml index 5831d1b0d5..ec1a4ecb80 100644 --- a/_config.yml +++ b/_config.yml @@ -280,3 +280,11 @@ fetch-remote: - dest: "build/bake/reference.md" src: - "docs/bake-reference.md" + + - repo: "https://github.com/docker/scout-cli" + default_branch: "main" + ref: "main" + paths: + - dest: "_data/scout-cli" + src: + - "docs/*.yaml" diff --git a/_data/scout-cli/docker_scout.yaml b/_data/scout-cli/docker_scout.yaml deleted file mode 100644 index 9e06255a14..0000000000 --- a/_data/scout-cli/docker_scout.yaml +++ /dev/null @@ -1,24 +0,0 @@ -command: docker scout -short: Command line tool for Docker Scout -long: Command line tool for Docker Scout -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 -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/scout-cli/docker_scout_compare.yaml b/_data/scout-cli/docker_scout_compare.yaml deleted file mode 100644 index dc3891e69f..0000000000 --- a/_data/scout-cli/docker_scout_compare.yaml +++ /dev/null @@ -1,212 +0,0 @@ -command: docker scout compare -short: '[experimental] Compare two images and display differences' -long: |- - 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 - - 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 deleted file mode 100644 index bb5bf4f596..0000000000 --- a/_data/scout-cli/docker_scout_cves.yaml +++ /dev/null @@ -1,225 +0,0 @@ -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 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 cves [OPTIONS] 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: details - value_type: bool - default_value: "false" - description: Print details on default text output - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: exit-code - shorthand: e - value_type: bool - default_value: "false" - description: Return exit code '2' if vulnerabilities are detected - deprecated: false - hidden: false - experimental: false - experimentalcli: false - kubernetes: false - swarm: false - - option: format - value_type: string - default_value: packages - description: |- - Output format of the generated vulnerability report: - - packages: default output, plain text with vulnerabilities grouped by packages - - sarif: json Sarif 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-cve-id - value_type: stringSlice - default_value: '[]' - description: | - Comma separated list of CVE ids (like CVE-2021-45105) to search for - 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: 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 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 --type 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 --type oci-dir alpine - Analyzing OCI directory alpine - ✓ OCI directory read - ✓ Image stored for indexing - ✓ Indexed 19 packages - ✓ No vulnerable package detected - ``` - - ### 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 - ``` -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/scout-cli/docker_scout_quickview.yaml b/_data/scout-cli/docker_scout_quickview.yaml deleted file mode 100644 index 9c8c2346bb..0000000000 --- a/_data/scout-cli/docker_scout_quickview.yaml +++ /dev/null @@ -1,91 +0,0 @@ -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 - diff --git a/_data/scout-cli/docker_scout_recommendations.yaml b/_data/scout-cli/docker_scout_recommendations.yaml deleted file mode 100644 index 5200ca30ea..0000000000 --- a/_data/scout-cli/docker_scout_recommendations.yaml +++ /dev/null @@ -1,133 +0,0 @@ -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 deleted file mode 100644 index 7a1d3e99e1..0000000000 --- a/_data/scout-cli/docker_scout_sbom.yaml +++ /dev/null @@ -1,135 +0,0 @@ -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/_data/scout-cli/docker_scout_version.yaml b/_data/scout-cli/docker_scout_version.yaml deleted file mode 100644 index 040951e56f..0000000000 --- a/_data/scout-cli/docker_scout_version.yaml +++ /dev/null @@ -1,18 +0,0 @@ -command: docker scout version -short: Show Docker Scout version information -long: Show Docker Scout version information -usage: docker scout version -pname: docker scout -plink: docker_scout.yaml -examples: |- - ```console - $ docker scout version - version: v0.2.2 (go1.19.5 - darwin/arm64) - git commit: c15f374b9a39d993da2e8a1db7edc4be4f7c0c1e - ``` -deprecated: false -experimental: false -experimentalcli: false -kubernetes: false -swarm: false - diff --git a/_data/toc.yaml b/_data/toc.yaml index b88067b76e..0bc962ca90 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -591,10 +591,16 @@ reference: title: docker scout compare - path: /engine/reference/commandline/scout_cves/ title: docker scout cves + - path: /engine/reference/commandline/scout_entitlement/ + title: docker scout entitlement - 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_sbom/ + title: docker scout sbom + - path: /engine/reference/commandline/scout_stream/ + title: docker scout stream - path: /engine/reference/commandline/scout_version/ title: docker scout version - path: /engine/reference/commandline/search/ diff --git a/engine/reference/commandline/scout_entitlement.md b/engine/reference/commandline/scout_entitlement.md new file mode 100644 index 0000000000..2ed73e771c --- /dev/null +++ b/engine/reference/commandline/scout_entitlement.md @@ -0,0 +1,16 @@ +--- +datafolder: scout-cli +datafile: docker_scout_entitlement +title: docker scout entitlement +--- + + +{% include scout-early-access.md %} + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %} diff --git a/engine/reference/commandline/scout_stream.md b/engine/reference/commandline/scout_stream.md new file mode 100644 index 0000000000..96c8f06aed --- /dev/null +++ b/engine/reference/commandline/scout_stream.md @@ -0,0 +1,16 @@ +--- +datafolder: scout-cli +datafile: docker_scout_stream +title: docker scout stream +--- + + +{% include scout-early-access.md %} + +{% include cli.md datafolder=page.datafolder datafile=page.datafile %}