diff --git a/docs/docker_scout_compare.yaml b/docs/docker_scout_compare.yaml index 6848456..dfcb4cc 100644 --- a/docs/docker_scout_compare.yaml +++ b/docs/docker_scout_compare.yaml @@ -2,40 +2,39 @@ 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 of both. + The `docker scout compare` command analyzes two images and displays a comparison. - 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 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 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. - If no image is specified, the most recently built image will be used. + If no image is specified, the most recently built image is used + as a comparison target. 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:// use an SBOM as 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://` 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 @@ -337,7 +336,42 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -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" +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 + ``` deprecated: false experimental: false experimentalcli: true diff --git a/docs/docker_scout_cves.yaml b/docs/docker_scout_cves.yaml index 44c84c3..d7bd9bc 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,28 +9,26 @@ 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:// use an SBOM as 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://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file + In case of `sbom://` prefix, if the file is not defined then it will try to read it from the standard input. usage: docker scout cves [OPTIONS] [IMAGE|DIRECTORY|ARCHIVE] pname: docker scout plink: docker_scout.yaml @@ -59,6 +57,7 @@ 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 @@ -399,7 +398,168 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -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" +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 deprecated: false experimental: false experimentalcli: false diff --git a/docs/docker_scout_policy.yaml b/docs/docker_scout_policy.yaml index 1e265eb..077907e 100644 --- a/docs/docker_scout_policy.yaml +++ b/docs/docker_scout_policy.yaml @@ -1,8 +1,11 @@ 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 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. +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. usage: docker scout policy [IMAGE | REPO] pname: docker scout plink: docker_scout.yaml @@ -105,7 +108,30 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -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" +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 + ``` deprecated: false experimental: false experimentalcli: true diff --git a/docs/docker_scout_push.yaml b/docs/docker_scout_push.yaml index ab2d7cd..361b89e 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 allows to push an image or image index to Docker Scout. + The `docker scout push` command lets you push an image or analysis result to Docker Scout. usage: docker scout push IMAGE pname: docker scout plink: docker_scout.yaml @@ -103,7 +103,12 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -examples: " Push an image to Docker Scout\n $ docker scout push --org my-org registry.example.com/repo:tag\e[0m" +examples: |- + ### Push an image to Docker Scout + + ```console + $ docker scout push --org my-org registry.example.com/repo:tag + ``` deprecated: false experimental: false experimentalcli: false diff --git a/docs/docker_scout_quickview.yaml b/docs/docker_scout_quickview.yaml index 3b68f7c..1ff9869 100644 --- a/docs/docker_scout_quickview.yaml +++ b/docs/docker_scout_quickview.yaml @@ -2,9 +2,10 @@ 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 image and the 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 specified image + and 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. @@ -12,27 +13,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 - - sbom:// use an SBOM as 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://` SPDX file or in-toto attestation file with SPDX predicate or `syft` json SBOM file + In case of `sbom://` prefix, if the file is not defined then it will try to read it from the standard input. usage: docker scout quickview [IMAGE|DIRECTORY|ARCHIVE] pname: docker scout plink: docker_scout.yaml @@ -186,7 +186,44 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -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" +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 │ + ``` deprecated: false experimental: false experimentalcli: false diff --git a/docs/docker_scout_sbom.yaml b/docs/docker_scout_sbom.yaml index 87e5203..d51d5d5 100644 --- a/docs/docker_scout_sbom.yaml +++ b/docs/docker_scout_sbom.yaml @@ -1,9 +1,12 @@ 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 a + 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 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. If no image is specified, the most recently built image is used. @@ -11,26 +14,24 @@ 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 @@ -123,7 +124,36 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -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" +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 + ``` deprecated: false experimental: false experimentalcli: false diff --git a/docs/docker_scout_watch.yaml b/docs/docker_scout_watch.yaml index 24e1f68..952c146 100644 --- a/docs/docker_scout_watch.yaml +++ b/docs/docker_scout_watch.yaml @@ -1,8 +1,9 @@ command: docker scout watch short: | Watch repositories in a registry and push images and indexes to Docker Scout -long: | - The docker scout watch command watches repositories in a registry and pushes images or image indexes to Docker Scout. +long: |- + The `docker scout watch` command watches repositories in a registry + and pushes images or analysis results to Docker Scout. usage: docker scout watch pname: docker scout plink: docker_scout.yaml @@ -128,7 +129,90 @@ inherited_options: experimentalcli: false kubernetes: false swarm: false -examples: " Watch for new images from two repositories and push them\n $ docker scout watch --org my-org --repository registry-1.example.com/repo-1 --repository registry-2.example.com/repo-2\e[0m\n\n Only push images with a specific tag\n $ docker scout watch --org my-org --repository registry.example.com/my-service --tag latest\e[0m\n\n Watch all repositories of a registry\n $ docker scout watch --org my-org --registry registry.example.com\e[0m\n\n Push all images and not just the new ones\n $ docker scout watch --org my-org --repository registry.example.com/my-service --all-images\e[0m" +examples: |- + ### Watch for new images from two repositories and push them + + ```console + $ docker scout watch --org my-org --repository registry-1.example.com/repo-1 --repository registry-2.example.com/repo-2 + ``` + + ### Only push images with a specific tag + + ```console + $ docker scout watch --org my-org --repository registry.example.com/my-service --tag latest + ``` + + ### Watch all repositories of a registry + + ```console + $ docker scout watch --org my-org --registry registry.example.com + ``` + + ### Push all images and not just the new ones + + ```console + $ docker scout watch --org my-org --repository registry.example.com/my-service --all-images + ``` + + ### Configure Artifactory integration + + The following example creates a web hook endpoint for Artifactory to push new + image events into: + + ```console + $ export DOCKER_SCOUT_ARTIFACTORY_API_USER=user + $ export DOCKER_SCOUT_ARTIFACTORY_API_PASSWORD=password + $ export DOCKER_SCOUT_ARTIFACTORY_WEBHOOK_SECRET=foo + + $ docker scout watch --registry "type=artifactory,registry=example.jfrog.io,api=https://example.jfrog.io/artifactory,include=*/frontend*,exclude=*/dta/*,repository=docker-local,port=9000,subdomain-mode=true" --refresh-registry + ``` + + This will launch an HTTP server on port `9000` that will receive all `component` web + hook events, optionally validating the HMAC signature. + + ### Configure Harbor integration + + The following example creates a web hook endpoint for Harbor to push new image + events into: + + ```console + $ export DOCKER_SCOUT_HARBOR_API_USER=admin + $ export DOCKER_SCOUT_HARBOR_API_PASSWORD=password + $ export DOCKER_SCOUT_HARBOR_WEBHOOK_AUTH="token foo" + + $ docker scout watch --registry 'type=harbor,registry=demo.goharbor.io,api=https://demo.goharbor.io,include=*/foo/*,exclude=*/bar/*,port=9000' --refresh-registry + ``` + + This will launch an HTTP server on port `9000` that will receive all `component` web + hook events, optionally validating the HMAC signature. + + ### Configure Nexus integration + + The following example shows how to configure Sonartype Nexus integration: + + ```console + $ export DOCKER_SCOUT_NEXUS_API_USER=admin + $ export DOCKER_SCOUT_NEXUS_API_PASSWORD=admin124 + + $ docker scout watch --registry 'type=nexus,registry=localhost:8082,api=http://localhost:8081,include=*/foo/*,exclude=*/bar/*,"repository=docker-test1,docker-test2"' --refresh-registry + ``` + + This ingests all images and tags in Nexus repositories called `docker-test1` + and `docker-test2` that match the `*/foo/*` include and `*/bar/*` exclude glob + pattern. + + You can also create a web hook endpoint for Nexus to push new image events into: + + ```console + $ export DOCKER_SCOUT_NEXUS_API_USER=admin + $ export DOCKER_SCOUT_NEXUS_API_PASSWORD=admin124 + $ export DOCKER_SCOUT_NEXUS_WEBHOOK_SECRET=mysecret + + $ docker scout watch --registry 'type=nexus,registry=localhost:8082,api=http://localhost:8081,include=*/foo/*,exclude=*/bar/*,"repository=docker-test1,docker-test2",port=9000' --refresh-registry + ``` + + This will launch an HTTP server on port `9000` that will receive all `component` web + hook events, optionally validating the HMAC signature. deprecated: false experimental: false experimentalcli: false