From 117d7ea5a846771002ece035f9f99cfe816ccb0f Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Wed, 30 Aug 2023 09:48:55 +0200 Subject: [PATCH] scout: image analysis refresh Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/develop/security-best-practices.md | 4 +- content/docker-hub/vulnerability-scanning.md | 10 +- content/scout/_index.md | 75 +------ content/scout/advanced-image-analysis.md | 116 ---------- content/scout/advisory-db-sources.md | 4 +- content/scout/dashboard.md | 4 +- content/scout/image-analysis.md | 210 +++++++++++++++++++ content/scout/policy.md | 10 +- data/toc.yaml | 4 +- 9 files changed, 232 insertions(+), 205 deletions(-) delete mode 100644 content/scout/advanced-image-analysis.md create mode 100644 content/scout/image-analysis.md diff --git a/content/develop/security-best-practices.md b/content/develop/security-best-practices.md index 12d9e3fba9..963b5a5b33 100644 --- a/content/develop/security-best-practices.md +++ b/content/develop/security-best-practices.md @@ -128,7 +128,7 @@ that affect images that you build or use. which when enabled automatically scans images when you push them to a Docker Hub repository. Requires a [Docker subscription](../subscription/index.md). - Docker Hub also supports an early-access - [advanced image analysis](../scout/advanced-image-analysis.md) feature, which extends + [advanced image analysis](../scout/image-analysis.md) feature, which extends the "core" vulnerability scanning solution with enhanced capabilities and more detailed and actionable insights. - For the CLI, there's the @@ -158,4 +158,4 @@ To summarize the topics covered in this guide: - Ensure you carefully monitor and manage the tools and dependencies you add to your image. - Ensure you scan images at multiple stages during your development lifecycle. -- Check your images frequently for vulnerabilities. \ No newline at end of file +- Check your images frequently for vulnerabilities. diff --git a/content/docker-hub/vulnerability-scanning.md b/content/docker-hub/vulnerability-scanning.md index 396d250fb5..2235592141 100644 --- a/content/docker-hub/vulnerability-scanning.md +++ b/content/docker-hub/vulnerability-scanning.md @@ -43,10 +43,10 @@ There is no action required on your part. Scans continue to run as usual with no interruption or changes to pricing. Historical data continues to be available. -This page describes the Basic Hub vulnerability scanning feature. Docker Scout -also supports an [Advanced image analysis](../scout/advanced-image-analysis.md) -feature that provides more in-depth results and guided remediation steps for -improving your security posture. +This page describes the Basic Hub vulnerability scanning feature. There's also +the [Docker Scout image analysis](../scout/image-analysis.md) feature, that +provides more in-depth results and guided remediation steps for improving your +security posture. ## Scan images with Basic vulnerability scanning @@ -166,4 +166,4 @@ a repository. To disable scanning: 2. Go to **Repositories** and then select a repository from the list. 3. Go to the **Settings** tab. 4. Under **Image insight settings**, select **None**. -5. Select **Save**. \ No newline at end of file +5. Select **Save**. diff --git a/content/scout/_index.md b/content/scout/_index.md index 17b6b206bd..733c63885c 100644 --- a/content/scout/_index.md +++ b/content/scout/_index.md @@ -25,9 +25,10 @@ packages and layers called a [Software bill of materials (SBOM)](https://ntia.go It then correlates this inventory with a continuously updated vulnerability database to identify vulnerabilities in your images. -You can use Docker Scout in [Docker Desktop](#docker-desktop), [Docker Hub](#docker-hub), the [Docker CLI](#docker-scout-cli), -and in the [Docker Scout Dashboard](./dashboard.md). Docker Scout also supports integrations with third-party systems, -refer to [Integrating Docker Scout](./integrations/index.md) for more information. +You can use Docker Scout in Docker Desktop, Docker Hub, the Docker CLI, and in +the [Docker Scout Dashboard](./dashboard.md). Docker Scout also supports +integrations with third-party systems, refer to [Integrating Docker +Scout](./integrations/index.md) for more information. {{< include "scout-plans.md" >}} @@ -47,71 +48,3 @@ _The following video shows an end-to-end workflow of using Docker Scout to remed _The following video shows how to enable Docker Scout on your repositories_.
- -### Docker Desktop - -> **Note** -> -> There is a 3 GB size limit on images analyzed by Docker Scout in Docker Desktop. - -Docker Scout analyzes all images stored locally in Docker Desktop, providing you -with up-to-date vulnerability information as you build your images. - -For more information, read the [Advanced image analysis guide](./advanced-image-analysis.md). - -### Docker Hub - -If you enable [Advanced image analysis](./advanced-image-analysis.md) for a -repository in Docker Hub, Docker Scout analyzes your images every time you push -them to Docker Hub. Docker Scout shows analysis results on every tag view for -that repository. - -The analysis updates continuously, meaning that the vulnerability report for an -image is always up to date as Docker Scout becomes aware of new CVEs. No need to -re-analyze an image. - -For more information, read the [Advanced image analysis guide](./advanced-image-analysis.md). - -### Docker Scout CLI plugin {#docker-scout-cli} - -The `docker scout` CLI plugin provides a terminal interface for using Docker -Scout with local and remote images. - -Using the CLI, you can analyze images and view the analysis report in text -format. You can print the results directly to stdout, or export them to a file -using a structured format, such as Static Analysis Results Interchange Format -(SARIF). - -For more information about how to use the `docker scout` CLI, see the -[reference documentation](../engine/reference/commandline/scout.md). - -The plugin is available in Docker Desktop starting with version 4.17 and -available as a standalone binary. - -To install the plugin, run the following command: - -```console -$ curl -fsSL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh -o install-scout.sh -$ sh install-scout.sh -``` - -> **Note** -> -> Always examine scripts downloaded from the internet before running them locally. -> Before installing, make yourself familiar with potential risks and limitations -> of the convenience script. - -If you want to install the plugin manually, you can find full instructions in -the [plugin's repository](https://github.com/docker/scout-cli). - -The plugin is also available as [a container image](https://hub.docker.com/r/docker/scout-cli) -and as [a GitHub action](https://github.com/docker/scout-action). - -### Docker Scout Dashboard - -The [Docker Scout Dashboard](https://scout.docker.com) -helps you share the analysis and security status of images in -an organization with your team. You can also use the dashboard settings to enable -Docker Scout on multiple images from Docker Hub at once. - -For more information, read the [Docker Scout Dashboard guide](./dashboard.md). diff --git a/content/scout/advanced-image-analysis.md b/content/scout/advanced-image-analysis.md deleted file mode 100644 index e94c42d651..0000000000 --- a/content/scout/advanced-image-analysis.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -description: Advanced image analysis is a Docker Scout feature for Docker Hub -keywords: scanning, vulnerabilities, Hub, supply chain, security -title: Advanced image analysis ---- - -{{< include "scout-early-access.md" >}} - -Advanced image analysis is a Docker Scout feature for Docker Hub. - -When you activate Advanced image analysis for a repository, Scout analyzes new tags -automatically when you push to that repository. Advanced image analysis -is more than point-in-time scanning, the analysis gets reevaluated -continuously, meaning you don't need to re-scan the image to see an updated -vulnerability report. - -The **General** tab of an image page on Docker Hub shows a summary of common vulnerabilities and -exposures (CVEs) for the image in the **Tags** section. The **Tags** tab shows all analysis results. - -The **Images** section of Docker Desktop shows an overview of CVEs for an image and the details view shows all vulnerabilities. - -## Activate Advanced image analysis - -Advanced image analysis is an early access feature and activated on a -per-repository basis for organizations with a -[Docker Pro, Team, or Business subscription](../subscription/index.md). - -> **Note** -> -> Only repository owners and administrators can activate Advanced image analysis -> on a repository. - -To activate Advanced image analysis: - -1. Log into your Docker Hub account. -2. Click **Repositories** from the main menu and select a repository from the - list. -3. Go to the **Settings** tab -4. Under **Image insight settings**, select **Advanced image analysis provided - by Docker Scout**. -5. Select **Save**. - -> **Tip** -> -> You can enable Advanced image analysis on repositories in bulk from -> the [Docker Scout Dashboard settings](./dashboard.md#repository-settings). -{ .tip } - -## Analyze an image - -To trigger Advanced image analysis, push an image to a Docker Hub repository -with Advanced image analysis active: - -1. Sign in with your Docker ID, either using the `docker login` command or the - **Sign in** button in Docker Desktop. -2. Tag the image to analyze. For example, to tag a Redis image, run: - - ```console - $ docker tag redis /:latest - ``` - -3. Push the image to Docker Hub to trigger analysis of the image: - - ```console - $ docker push /:latest - ``` - -## View the vulnerability report - -To view the vulnerability report on Docker Hub: - -1. Go to Docker Hub and open the repository page. The **Tags** section - displays a vulnerability summary. - - It may take a few minutes for the vulnerability report to appear. If your vulnerability summary doesn't display, wait a moment - and then refresh the page. - -2. Click on the tag in the table. This opens the details page for the tag. - -3. Select the **Vulnerabilities** tab on the right side of the page. - - This tab displays a deep-dive view of the image's packages and any known vulnerabilities. - - For more information about how to interpret the vulnerability report, see - [Image details view](./image-details-view.md). - -Expanding any of the packages in the list shows you more information about the -vulnerabilities that affect a given package. Expanding the vulnerability shows a summary of it's details and -selecting the vulnerability name opens Docker's image vulnerability database, which provides -more information on the vulnerability and what images it affects. - -## Deactivate Advanced image analysis - -> **Note** -> -> Only repository owners and administrators can deactivate Advanced image -> analysis on a repository. - -To deactivate Advanced image analysis: - -1. Go to Docker Hub and sign in. -2. Select **Repositories** from the main menu and select a repository from the - list. -3. Go to the **Settings** tab. -4. Under **Image insight settings**, select one of the following options: - - - **Basic Hub vulnerability scanning** to use the basic scanning feature. - - **None** to turn off vulnerability detection. - -5. Select **Save**. - -## Feedback - -Thank you for trying out the Advanced image analysis feature. Give feedback or -report any bugs you may find through the issues tracker on the -[hub-feedback](https://github.com/docker/hub-feedback/issues) GitHub repository. \ No newline at end of file diff --git a/content/scout/advisory-db-sources.md b/content/scout/advisory-db-sources.md index 0f3d0ab81d..34867efc41 100644 --- a/content/scout/advisory-db-sources.md +++ b/content/scout/advisory-db-sources.md @@ -60,7 +60,7 @@ it can identify the artifact that’s now vulnerable, why, and where it’s in u When a customer enrolls with Docker Scout, the organization receives their own instance of the database. This database tracks timestamped metadata about your images that Docker Scout can then match to CVEs. Find more details on how this -works in the [Advanced image analysis document](./advanced-image-analysis.md). +works in the [image analysis page](./image-analysis.md). Docker Scout is ideal for analyzing images in Docker Desktop and Docker Hub, but the flexibility of the approach also means it can integrate with other systems, @@ -118,4 +118,4 @@ By sourcing vulnerability data from the providers above, Docker Scout is able to - Ruby - `alpm` (Arch Linux) - `apk` (Alpine Linux) -- `deb` (Debian Linux and derivatives) \ No newline at end of file +- `deb` (Debian Linux and derivatives) diff --git a/content/scout/dashboard.md b/content/scout/dashboard.md index be0143c720..f64c6ee60b 100644 --- a/content/scout/dashboard.md +++ b/content/scout/dashboard.md @@ -27,7 +27,7 @@ Select the checkboxes for the repositories on which you want to enable Docker Sc select **Enable image analysis**. When you enable image analysis for a repository, Docker Scout analyzes new tags -automatically when you push to that repository. Find out more in the [Advanced image analysis](./advanced-image-analysis.md) documentation. +automatically when you push to that repository. Find out more in the [image analysis](./image-analysis.md) documentation. Disable Docker Scout analysis on selected repositories by selecting **Disable image analysis**. @@ -171,4 +171,4 @@ Following this information is a list of all repositories affected by the vulnera - The current tag version of the image. Selecting the link for the tag name opens [the repository tag list layer view](#image-layer-view). - The date the image was last pushed. - The registry where the image is stored. -- The affected package name and version in the image. \ No newline at end of file +- The affected package name and version in the image. diff --git a/content/scout/image-analysis.md b/content/scout/image-analysis.md new file mode 100644 index 0000000000..9d13d60216 --- /dev/null +++ b/content/scout/image-analysis.md @@ -0,0 +1,210 @@ +--- +title: Docker Scout image analysis +description: + Docker Scout image analysis provides a detailed view into the composition of + your images and the vulnerabilities that they contain +keywords: scanning, vulnerabilities, supply chain, security, analysis +aliases: + - /scout/advanced-image-analysis/ +--- + +{{< include "scout-early-access.md" >}} + +When you activate image analysis for a repository, Docker Scout analyzes new +images automatically when you push to that repository. Docker Scout image +analysis is more than point-in-time scanning, the analysis gets reevaluated +continuously, meaning you don't need to re-scan the image to see an updated +vulnerability report. + +Docker Scout image analysis is available by default for Docker Hub +repositories. You can also integrate third-party registries, such as Amazon ECR +and JFrog Artifactory, and even run image analysis locally on your development +machine. + +The following video shows how to activate Docker Scout image analysis on your +repositories. + + + +## Activate image analysis + +The free tier of Docker Scout lets you use Docker Scout for up to 3 +repositories per Docker organization. You can update your Docker Scout plan if +you need additional repositories, see [Docker Scout +billing](../billing/scout-billing.md). + +> **Note** +> +> You must have the **Editor** or **Owner** role in the Docker organization to +> activate image analysis on a repository. + +To activate image analysis: + +1. Go to the [Docker Scout Dashboard](https://scout.docker.com/) +2. Sign in with your Docker ID. +3. Make sure that the correct Docker organization is selected. +4. Open the settings menu and select **Repository settings**. +5. Select the repositories that you want to enable. +6. Select **Enable image analysis**. + +## Analyze registry images + +To trigger image analysis for an image in a registry, push the image to a registry that's +integrated with Docker Scout, to a repository where image analysis is +activated. + +Prerequisites: + +- The registry must be integrated with Docker Scout. Docker Hub is integrated + by default. +- You must [activate Docker Scout](#activate-image-analysis) for the + repository, before pushing the image. + +1. Sign in with your Docker ID, either using the `docker login` command or the + **Sign in** button in Docker Desktop. +2. Build and tag the image that you want to analyze. + + ```console + $ docker build --tag /:latest --provenance=true --sbom=true . + ``` + + > **Note** + > + > Building with the `--provenance=true` and `--sbom=true` flags attach + > [build attestations](../build/attestations/_index.md) to the image, which + > yields more precise analysis results. + +3. Push the image to Docker Hub to trigger analysis of the image: + + ```console + $ docker push /:latest + ``` + +4. Go to the [Docker Scout Dashboard](https://scout.docker.com/) +5. Sign in with your Docker ID. +6. Select the Docker organization that contains the image you just pushed. +7. Go to the **Images** tab. The image appears in the list shortly after you + push it to the registry. + + It may take a few minutes for the analysis report to appear. If the analysis + report is not available, wait a moment and then refresh the page. + +## Analyze images locally + +You can analyze local images with Docker Scout using Docker Desktop or the +`docker scout quickview` and `docker scout cves` commands for the Docker CLI. + +### Docker Desktop + +> **Note** +> +> There is a 3 GB size limit on images analyzed by Docker Scout in Docker +> Desktop. + +To analyze an image locally using the Docker Desktop GUI: + +1. Pull or build the image that you want to analyze. +2. Go to the **Images** view in the Docker Dashboard. +3. Select one of your local images in the list. + + This opens the [Image details view](./image-details-view.md), showing a + breakdown of packages and vulnerabilities found by the Docker Scout analysis + for the image you selected. + +### CLI + +The `docker scout` CLI commands provide a terminal interface for using Docker +Scout with local and remote images. + +Using the `docker scout quickview` and `docker scout cves` CLI commands, you +can analyze images locally and view the analysis report in text format. You can +print the results directly to stdout, or export them to a file using a +structured format, such as Static Analysis Results Interchange Format (SARIF). + +#### Install + +The Docker Scout CLI plugin is available in Docker Desktop starting with +version 4.17 and available as a standalone binary. + +To install the latest version of the plugin manually, run the following +commands: + +```console +$ curl -fsSL https://raw.githubusercontent.com/docker/scout-cli/main/install.sh -o install-scout.sh +$ sh install-scout.sh +``` + +> **Note** +> +> Always examine scripts downloaded from the internet before running them +> locally. Before installing, make yourself familiar with potential risks and +> limitations of the convenience script. + +If you want to install the plugin manually, you can find full instructions in +the [plugin's repository](https://github.com/docker/scout-cli). + +The plugin is also available as [a container image](https://hub.docker.com/r/docker/scout-cli) +and as [a GitHub action](https://github.com/docker/scout-action). + +#### Quickview + +The `docker scout quickview` command provides an overview of the +vulnerabilities found in a given image and its base image. + +```console +$ docker scout quickview traefik:latest + ✓ SBOM of image already cached, 311 packages indexed + + Your image traefik:latest │ 0C 2H 8M 1L + Base image alpine:3 │ 0C 0H 0M 0L +``` + +If your the base image is out of date, the `quickview` command also shows how +updating your base image would change the vulnerability exposure of your image. + +```console +$ docker scout quickview postgres:13.1 + ✓ Pulled + ✓ Image stored for indexing + ✓ Indexed 187 packages + + Your image postgres:13.1 │ 17C 32H 35M 33L + Base image debian:buster-slim │ 9C 14H 9M 23L + Refreshed base image debian:buster-slim │ 0C 1H 6M 29L + │ -9 -13 -3 +6 + Updated base image debian:stable-slim │ 0C 0H 0M 17L + │ -9 -14 -9 -6 +``` + +#### CVEs + +The `docker scout cves` command gives you a complete view of all the +vulnerabilities in the image. This command supports several flags that lets you +specify more precisely which vulnerabilities you're interested in, for example, +by severity or package type: + +```console +$ docker scout cves --format only-packages --only-vuln-packages \ + --only-severity critical postgres:13.1 + ✓ SBOM of image already cached, 187 packages indexed + ✗ Detected 10 vulnerable packages with a total of 17 vulnerabilities + + Name Version Type Vulnerabilities +─────────────────────────────────────────────────────────────────────────── + dpkg 1.19.7 deb 1C 0H 0M 0L + glibc 2.28-10 deb 4C 0H 0M 0L + gnutls28 3.6.7-4+deb10u6 deb 2C 0H 0M 0L + libbsd 0.9.1-2 deb 1C 0H 0M 0L + libksba 1.3.5-2 deb 2C 0H 0M 0L + libtasn1-6 4.13-3 deb 1C 0H 0M 0L + lz4 1.8.3-1 deb 1C 0H 0M 0L + openldap 2.4.47+dfsg-3+deb10u5 deb 1C 0H 0M 0L + openssl 1.1.1d-0+deb10u4 deb 3C 0H 0M 0L + zlib 1:1.2.11.dfsg-1 deb 1C 0H 0M 0L +``` + +For more information about these commands and how to use them, refer to the CLI +reference documentation: + +- [`docker scout quickview`](../engine/reference/commandline/scout_quickview.md) +- [`docker scout cves`](../engine/reference/commandline/scout_cves.md) diff --git a/content/scout/policy.md b/content/scout/policy.md index 700f840f64..d28e01bc7e 100644 --- a/content/scout/policy.md +++ b/content/scout/policy.md @@ -29,11 +29,11 @@ with established best practices. ## How it works When you activate Docker Scout for a repository, images that you push are -[automatically analyzed](../advanced-image-analysis.md). The analysis gives you -insights about the composition of your images, including what packages they -contain, and what vulnerabilities they're exposed to. Policy Evaluation builds -on top of the image analysis feature, interpreting the analysis results against -the rules defined by policies. +[automatically analyzed](./image-analysis.md). The analysis gives you insights +about the composition of your images, including what packages they contain and +what vulnerabilities they're exposed to. Policy Evaluation builds on top of the +image analysis feature, interpreting the analysis results against the rules +defined by policies. A policy defines one or more criteria that your artifacts should fulfill. For example, one of the default policies in Docker Scout is the **Critical diff --git a/data/toc.yaml b/data/toc.yaml index 9fafdfcf54..42c6796c8c 100644 --- a/data/toc.yaml +++ b/data/toc.yaml @@ -1901,8 +1901,8 @@ Manuals: title: Quickstart - path: /scout/image-details-view/ title: Image details view - - path: /scout/advanced-image-analysis/ - title: Advanced image analysis + - path: /scout/image-analysis/ + title: Image analysis - path: /scout/dashboard/ title: Dashboard - path: /scout/advisory-db-sources/