docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #16971 from eunomie/scout-v0.8.5-cli-docs 

DD4.18 scout: update cli documentation
This commit is contained in:
Chris Chinchilla 2023-04-05 16:41:30 +02:00 committed by GitHub
parent 5033fbbc12 79c26e0b78
commit 8f36af3cd4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 638 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
_data/scout-cli/docker_scout.yaml
View File

@ -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

212
_data/scout-cli/docker_scout_compare.yaml Normal file
View File

@ -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 displays 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

6
_data/scout-cli/docker_scout_cves.yaml
View File

@ -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

91
_data/scout-cli/docker_scout_quickview.yaml Normal file
View File

@ -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 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

133
_data/scout-cli/docker_scout_recommendations.yaml Normal file
View File

@ -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

135
_data/scout-cli/docker_scout_sbom.yaml Normal file
View File

@ -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

6
_data/toc.yaml
View File

@ -621,8 +621,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/

13
engine/reference/commandline/scout_compare.md Normal file
View File

@ -0,0 +1,13 @@
---
datafolder: scout-cli
datafile: docker_scout_compare
title: docker scout compare
---
<!--
This page is automatically generated from Docker's source code. If you want to
suggest a change to the text that appears here, open a ticket or pull request
in the source repository on GitHub:
https://github.com/docker/scout-cli-plugin
-->
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

13
engine/reference/commandline/scout_quickview.md Normal file
View File

@ -0,0 +1,13 @@
---
datafolder: scout-cli
datafile: docker_scout_quickview
title: docker scout quickview
---
<!--
This page is automatically generated from Docker's source code. If you want to
suggest a change to the text that appears here, open a ticket or pull request
in the source repository on GitHub:
https://github.com/docker/scout-cli-plugin
-->
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

13
engine/reference/commandline/scout_recommendations.md Normal file
View File

@ -0,0 +1,13 @@
---
datafolder: scout-cli
datafile: docker_scout_recommendations
title: docker scout recommendations
---
<!--
This page is automatically generated from Docker's source code. If you want to
suggest a change to the text that appears here, open a ticket or pull request
in the source repository on GitHub:
https://github.com/docker/scout-cli-plugin
-->
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}

13
engine/reference/commandline/scout_sbom.md Normal file
View File

@ -0,0 +1,13 @@
---
datafolder: scout-cli
datafile: docker_scout_sbom
title: docker scout sbom
---
<!--
This page is automatically generated from Docker's source code. If you want to
suggest a change to the text that appears here, open a ticket or pull request
in the source repository on GitHub:
https://github.com/docker/scout-cli-plugin
-->
{% include cli.md datafolder=page.datafolder datafile=page.datafile %}