diff --git a/content/scout/advisory-db-sources.md b/content/scout/advisory-db-sources.md index d0e0f9b988..329169c5dc 100644 --- a/content/scout/advisory-db-sources.md +++ b/content/scout/advisory-db-sources.md @@ -83,7 +83,7 @@ the product name “calendar”. If there is a vulnerability present in an npm package, this CPE match would also return packages and modules for all other languages too. -Instead, Docker Scout matches CVEs to SBOMs using [package URL (PURL) +Instead, Docker Scout matches CVEs to SBOMs using [Package URL (PURL) links](https://github.com/package-url/purl-spec) that are a more precise, universal schema for matching software packages. A PURL link can help you only identify the relevant packages with far less false positives. @@ -95,8 +95,8 @@ language and version. pkg:npm/calendar@12.0.2 ``` -This only matches a node package with the name “calendar” and the version -“12.0.2”. For relevant packages, you can specify architectures and operating +This only matches a node package with the name `calendar` and the version +`12.0.2`. For relevant packages, you can specify architectures and operating system versions to make more precise matches. In summary, Docker Scout’s technique improves matching accuracy and reduces the @@ -104,7 +104,9 @@ number of results that turn out to be false-positives. ## Package ecosystems supported by Docker Scout -By sourcing vulnerability data from the providers above, Docker Scout is able to support analyzing the following package ecosystems: +By sourcing vulnerability data from the [advisory +databases](#docker-scouts-advisory-database-sources), Docker Scout is able to +support analyzing the following package ecosystems: - .NET - GitHub packages diff --git a/content/scout/data-handling.md b/content/scout/data-handling.md index 7e1b4e7f00..0d8ad1f8ad 100644 --- a/content/scout/data-handling.md +++ b/content/scout/data-handling.md @@ -57,15 +57,15 @@ collects the following data points: ### Local analysis For images analyzed locally on a developer's machine, Docker Scout only -transmits PURLs and layer digests. This data is not persistently stored on the +transmits PURLs and layer digests. This data isn't persistently stored on the Docker Scout platform; it's only used to run the analysis. ## Data storage For the purposes of providing the Docker Scout service, data is stored using: -- Amazon Web Services (AWS) on servers located in US-EAST, USA -- Google Cloud Platform (GCP) on servers located in US-EAST, USA +- Amazon Web Services (AWS) on servers located in US East +- Google Cloud Platform (GCP) on servers located in US East Data is used according to the processes described at [docker.com/legal](https://www.docker.com/legal/) to provide the key diff --git a/content/scout/image-details-view.md b/content/scout/image-details-view.md index e4a4c1841a..5ec12f6117 100644 --- a/content/scout/image-details-view.md +++ b/content/scout/image-details-view.md @@ -7,14 +7,10 @@ description: The Docker Scout image detail view analyzes images to show their he --- The image details view shows a breakdown of the Docker Scout analysis. You can -access the image view from within Docker Desktop and from the image tag -page on Docker Hub. The view provides a breakdown of the image hierarchy (base -images), image layers, packages, and vulnerabilities. - -The image view lets you inspect the composition of an image from different -perspectives. The view displays vulnerabilities and packages that an image -contains. You can choose whether you want to see data for the image as a whole, -or for a specific base image or layer. +access the image view from the Docker Scout Dashboard, the Docker Desktop +**Images** view, and from the image tag page on Docker Hub. The image details +show a breakdown of the image hierarchy (base images), image layers, packages, +and vulnerabilities. ![The image details view in Docker Desktop](./images/dd-image-view.png) @@ -24,15 +20,14 @@ in this SBOM to query for matching Common Vulnerabilities and Exposures (CVEs) i ## Image hierarchy -The image you inspect may have one or more base images represented under **Image hierarchy**. -This means the author of the image used other images as starting -points when building the image. Often these base images are either operating -system images such as Debian, Ubuntu, and Alpine, or programming language images -such as PHP, Python, and Java. +The image you inspect may have one or more base images represented under +**Image hierarchy**. This means the author of the image used other images as +starting points when building the image. Often these base images are either +operating system images such as Debian, Ubuntu, and Alpine, or programming +language images such as PHP, Python, and Java. -Selecting each image in the chain -lets you see which layers originate from each base image. Selecting the **ALL** -row reselects all the layers and base images for the entire image. +Selecting each image in the chain lets you see which layers originate from each +base image. Selecting the **ALL** row selects all layers and base images. One or more of the base images may have updates available, which may include updated security patches that remove vulnerabilities from your image. Any base @@ -123,8 +118,8 @@ requires you to update the Dockerfile and re-build the image. #### Refresh base image -This tab shows if the selected base image tag is the latest available -version, or if it's outdated. +This tab shows if the selected base image tag is the latest available version, +or if it's outdated. If the base image tag used to build the current image isn't the latest, then the delta between the two versions shows in this window. The delta information @@ -140,8 +135,9 @@ run to re-build the image using the latest version. #### Change base image -This tab shows different alternative tags that you can use, and -outlines the benefits and disadvantages of each tag version. Selecting the base image shows recommended options for that tag. +This tab shows different alternative tags that you can use, and outlines the +benefits and disadvantages of each tag version. Selecting the base image shows +recommended options for that tag. For example, if the image you're inspecting is using an old version of `debian` as a base image, it shows recommendations for newer and more secure versions diff --git a/content/scout/images/dashboard-compare-overview.png b/content/scout/images/dashboard-compare-overview.png deleted file mode 100644 index ce0a360724..0000000000 Binary files a/content/scout/images/dashboard-compare-overview.png and /dev/null differ diff --git a/content/scout/images/dashboard-compare-select.png b/content/scout/images/dashboard-compare-select.png deleted file mode 100644 index 1e86b73d31..0000000000 Binary files a/content/scout/images/dashboard-compare-select.png and /dev/null differ diff --git a/content/scout/images/dashboard-diff-bottom.png b/content/scout/images/dashboard-diff-bottom.png deleted file mode 100644 index a0e2be6230..0000000000 Binary files a/content/scout/images/dashboard-diff-bottom.png and /dev/null differ diff --git a/content/scout/images/dashboard-diff-select.png b/content/scout/images/dashboard-diff-select.png deleted file mode 100644 index dc44889358..0000000000 Binary files a/content/scout/images/dashboard-diff-select.png and /dev/null differ diff --git a/content/scout/images/dashboard-diff-top.png b/content/scout/images/dashboard-diff-top.png deleted file mode 100644 index d8d04745b8..0000000000 Binary files a/content/scout/images/dashboard-diff-top.png and /dev/null differ diff --git a/content/scout/images/dashboard-pandd.png b/content/scout/images/dashboard-pandd.png deleted file mode 100644 index f69d70504b..0000000000 Binary files a/content/scout/images/dashboard-pandd.png and /dev/null differ diff --git a/content/scout/images/dashboard-suggested-fix.png b/content/scout/images/dashboard-suggested-fix.png deleted file mode 100644 index 5e1ed0df35..0000000000 Binary files a/content/scout/images/dashboard-suggested-fix.png and /dev/null differ diff --git a/content/scout/images/dashboard-vulns-details.png b/content/scout/images/dashboard-vulns-details.png deleted file mode 100644 index a57ace0395..0000000000 Binary files a/content/scout/images/dashboard-vulns-details.png and /dev/null differ diff --git a/content/scout/images/dashboard-vulns.png b/content/scout/images/dashboard-vulns.png deleted file mode 100644 index 92e4992312..0000000000 Binary files a/content/scout/images/dashboard-vulns.png and /dev/null differ diff --git a/content/scout/images/webapp-hierachy.png b/content/scout/images/webapp-hierachy.png deleted file mode 100644 index 50d28a99b0..0000000000 Binary files a/content/scout/images/webapp-hierachy.png and /dev/null differ diff --git a/content/scout/images/webapp-images.png b/content/scout/images/webapp-images.png deleted file mode 100644 index 2c838d0b32..0000000000 Binary files a/content/scout/images/webapp-images.png and /dev/null differ diff --git a/content/scout/images/webapp-overview.png b/content/scout/images/webapp-overview.png deleted file mode 100644 index 9fe863b17d..0000000000 Binary files a/content/scout/images/webapp-overview.png and /dev/null differ diff --git a/content/scout/images/webapp-pandd.png b/content/scout/images/webapp-pandd.png deleted file mode 100644 index f69d70504b..0000000000 Binary files a/content/scout/images/webapp-pandd.png and /dev/null differ diff --git a/content/scout/images/webapp-suggested-fix.png b/content/scout/images/webapp-suggested-fix.png deleted file mode 100644 index 5e1ed0df35..0000000000 Binary files a/content/scout/images/webapp-suggested-fix.png and /dev/null differ diff --git a/content/scout/images/webapp-vulns.png b/content/scout/images/webapp-vulns.png deleted file mode 100644 index 35dd26d68f..0000000000 Binary files a/content/scout/images/webapp-vulns.png and /dev/null differ diff --git a/content/scout/integrations/ci/gha.md b/content/scout/integrations/ci/gha.md index d52dc15a90..2fd80d0bd0 100644 --- a/content/scout/integrations/ci/gha.md +++ b/content/scout/integrations/ci/gha.md @@ -122,7 +122,7 @@ Add the following to the YAML file: - name: Docker Scout id: docker-scout if: ${{ github.event_name == 'pull_request' }} - uses: docker/scout-action@dd36f5b0295baffa006aa6623371f226cc03e506 + uses: docker/scout-action@v1 with: command: compare image: ${{ steps.meta.outputs.tags }} diff --git a/content/scout/integrations/ci/gitlab.md b/content/scout/integrations/ci/gitlab.md index 9b3b819238..5296f9f7e4 100644 --- a/content/scout/integrations/ci/gitlab.md +++ b/content/scout/integrations/ci/gitlab.md @@ -10,10 +10,12 @@ image. If the commit was to the default branch, it uses Docker Scout to get a CVE report. If the commit was to a different branch, it uses Docker Scout to compare the new version to the current published version. +## Steps + First, set up the rest of the workflow. There's a lot that's not specific to Docker Scout but needed to create the images to compare. -Add the following to a _.gitlab-ci.yml_ file at the root of your repository. +Add the following to a `.gitlab-ci.yml` file at the root of your repository. ```yaml docker-build: @@ -34,16 +36,14 @@ docker-build: - docker login -u "$DOCKER_HUB_USER" -p "$DOCKER_HUB_PAT" ``` -This sets up the workflow to build Docker images with GitLab's -"Docker-in-Docker" mode to run Docker inside a container. +This sets up the workflow to build Docker images with Docker-in-Docker mode, +running Docker inside a container. -It then downloads curl and the Docker CLI and logs into the GitLab CI registry -and the Docker registry using environment variables defined in your repository's -settings. +It then downloads `curl` and the Docker Scout CLI plugin, logs into the Docker +registry using environment variables defined in your repository's settings. Add the following to the YAML file: - ```yaml script: - | @@ -67,7 +67,6 @@ script: - docker push "$CI_REGISTRY_IMAGE${tag}" ``` - This creates the flow mentioned previously. If the commit was to the default branch, Docker Scout generates a CVE report. If the commit was to a different branch, Docker Scout compares the new version to the current published version. @@ -86,6 +85,8 @@ rules: These final lines ensure that the pipeline only runs if the commit contains a Dockerfile and if the commit was to the CI branch. -_The following is a video walkthrough of the process of setting up the workflow with GitLab._ +## Video walkthrough -
+The following is a video walkthrough of the process of setting up the workflow with GitLab. + + diff --git a/content/scout/local-fs.md b/content/scout/local-fs.md index 4646187d4d..a5a18e6277 100644 --- a/content/scout/local-fs.md +++ b/content/scout/local-fs.md @@ -113,8 +113,8 @@ The previous example is truncated. The full output also includes a full package delta for the comparison. The delta shows what packages were added, removed, and changed between the versions. -The compare output includes VCS provenance for both the local source code and -the compare target, when available. +The compare output includes version control provenance for both the local +source code and the compare target, when available. ## Learn more diff --git a/content/scout/quickstart.md b/content/scout/quickstart.md index 22f541a16e..32d979a3a2 100644 --- a/content/scout/quickstart.md +++ b/content/scout/quickstart.md @@ -20,7 +20,7 @@ The following video shows an end-to-end workflow of using Docker Scout to remedi ## Step 1: Setup -[This example project](https://github.com/docker/scout-demo-service) contains +[This example project](https://github.com/docker/scout-demo-service) contains a vulnerable Node.js application that you can use to follow along. 1. Clone its repository: @@ -35,17 +35,17 @@ a vulnerable Node.js application that you can use to follow along. $ cd scout-demo-service ``` -3. Build the image, naming it to match the organization you will push it to, - and tag it as "v1": +3. Build the image, naming it to match the organization you will push it to, + and tag it as `v1`: ```console - $ docker build -t /scout-demo:v1 . + $ docker build -t /scout-demo:v1 . ``` 4. Create and push the repository on Docker Hub: ```console - $ docker push /scout-demo:v1 + $ docker push /scout-demo:v1 ``` > **Important** @@ -66,27 +66,27 @@ You can do this from Docker Hub, the Docker Scout Dashboard, and CLI. command to enable analysis on an existing repository: ```console - $ docker scout repo enable --org /scout-demo + $ docker scout repo enable --org /scout-demo ``` ## Step 3: Analyze image vulnerabilities -After building, you can use Docker Desktop or the `docker scout` CLI command +After building, you can use Docker Desktop or the `docker scout` CLI command to see vulnerabilities detected by Docker Scout. -1. Using Docker Desktop, select the image name in the **Images** view to see - the image layer view. In the image hierarchy section, you can see which layers +1. Using Docker Desktop, select the image name in the **Images** view to see + the image layer view. In the image hierarchy section, you can see which layers introduce vulnerabilities and the details of those. 2. Select layer 5 to focus on the vulnerability introduced in that layer. -3. Toggle the disclosure triangle next to **express 4.17.1** and then the CVE ID (in this case, "CVE-2022-24999⁠") to see details of the +3. Toggle the disclosure triangle next to **express 4.17.1** and then the CVE ID (in this case, `CVE-2022-24999`) to see details of the vulnerability. You can also use the Docker CLI to see the same results. ```console - $ docker scout cves /scout-demo:v1 + $ docker scout cves /scout-demo:v1 ``` ![Screenshot showing highlighting a CVE in Docker Desktop](./images/scout-onboarding-dd-v1-cvve-focus.png) @@ -99,7 +99,7 @@ You can find more details in the [advisory database](./advisory-db-sources.md) d > **Tip** > > Find out how to filter results using the CLI command [`scout cves`](/engine/reference/commandline/scout_cves). -{ .tip } +> { .tip } ## Step 4: Fix application vulnerabilities @@ -119,13 +119,13 @@ the underlying vulnerable express version to 4.17.3 or later. 2. Rebuild the image, giving it a new version tag: ```console - $ docker build -t /scout-demo:v2 . + $ docker build -t /scout-demo:v2 . ``` 3. Push the image to the same repository on Docker Hub using a new version tag: ```console - $ docker push /scout-demo:v2 + $ docker push /scout-demo:v2 ``` Now, viewing the latest tag of the image in Docker Desktop, the Docker Scout @@ -147,13 +147,13 @@ base images your images use. 3. Rebuild the image, again with a new tag: ```console - $ docker build -t /scout-demo:v3 . + $ docker build -t /scout-demo:v3 . ``` 4. Push it to Docker Hub using the new version tag: ```console - $ docker push /scout-demo:v3 + $ docker push /scout-demo:v3 ``` 5. Select the new image tag in Docker Desktop or the Docker Scout Dashboard and you @@ -162,7 +162,7 @@ base images your images use. You can see the same using the Docker CLI command: ```console - $ docker scout cves /scout-demo:v3 + $ docker scout cves /scout-demo:v3 ``` ## Step 6: Collaborate on vulnerabilities @@ -176,8 +176,8 @@ security, compliance, and operations to know what vulnerabilities and issues to 1. Select the **Images** tab on the [Docker Scout Dashboard](https://scout.docker.com). 2. Select any of the tags under - the **Most Recent Image** column, and you can see the same vulnerability - information as you saw in Docker Desktop and the Docker CLI and share this link with anyone else in your organization. + the **Most Recent Image** column, and you can see the same vulnerability + information as you saw in Docker Desktop and the Docker CLI and share this link with anyone else in your organization. > **Tip** > @@ -192,26 +192,38 @@ Over time as you build and push new tags of images, you can use the Docker Scout CLI and Dashboard to compare the changes to vulnerabilities and packages in different tags of the same image. -1. On the Docker Scout Dashboard, select the repository to compare from the - **Images** list. In this case, **scout-demo**. -2. Choose two of the tags you - pushed in the last steps, for example, **v1** and **v3**, and then select **Compare images**. +{{< tabs >}} +{{< tab name="Dashboard" >}} - The **Image comparison** view shows you the differences between the two tags. - The page's top part summarizes the two tags, including the differences between - vulnerabilities and base image tags. +On the Docker Scout Dashboard, select the repository to compare from the +**Images** list. In this case, **scout-demo**. - In the bottom part of the page, you can see the changes in packages and - vulnerabilities between the two tags. In the row for "express", you can see the - version change from 4.17.1 to 4.17.3. Switch to the **Vulnerabilities** tab to - see the changes in vulnerabilities between the two tags. You can see that - "CVE-2022-24999⁠" isn't present under the **v3** tag. +Choose two of the tags you pushed in the last steps, for example, **v1** and +**v3**, and then select **Compare images**. -3. You can also use the `scout compare` CLI command to see the same results. +The **Image comparison** view shows you the differences between the two tags. +The page's top part summarizes the two tags, including the differences between +vulnerabilities and base image tags. - ```console - $ docker scout compare --to /scout-demo:v1 /scout-demo:v3 - ``` +In the bottom part of the page, you can see the changes in packages and +vulnerabilities between the two tags. In the row for "express", you can see the +version change from 4.17.1 to 4.17.3. Switch to the **Vulnerabilities** tab to +see the changes in vulnerabilities between the two tags. You can see that +`CVE-2022-24999` isn't present under the **v3** tag. + +{{< /tab >}} +{{< tab name="CLI" >}} +{{< /tab >}} + +Use the `docker scout compare` command to see the compare two image versions. +Pass the image that you want to compare as a positional argument to the +command, and specify the base image to compare with using the `--to` flag. + +```console +$ docker scout compare --to /scout-demo:v1 /scout-demo:v3 +``` + +{{< /tabs >}} ## What's next? diff --git a/content/scout/sbom.md b/content/scout/sbom.md index c15407ec25..fe227dfaad 100644 --- a/content/scout/sbom.md +++ b/content/scout/sbom.md @@ -21,7 +21,7 @@ By default, this prints the SBOM in a JSON format to stdout. > **Note** > -> The JSON format produced by `docker scout sbom` is not SPDX-JSON. To generate +> The JSON format produced by `docker scout sbom` isn't SPDX-JSON. To generate > SPDX, use the SBOM generator plugin for BuildKit, see [Attach the SBOM as a > build attestation](#attest). @@ -84,7 +84,7 @@ the [containerd image store](../desktop/containerd/_index.md) feature, or use a ## Extract to file -The command for extracting the SBOM of an image to an SDPX JSON file is +The command for extracting the SBOM of an image to an SPDX JSON file is different depending on whether the image has been pushed to a registry or if it's a local image. @@ -100,7 +100,7 @@ $ docker buildx imagetools inspect --format "{{ json .SBOM }}" > sbom.sp ### Local image -To extract the SDPX file for a local image, build the image with the `local` +To extract the SPDX file for a local image, build the image with the `local` exporter and use the `scout-sbom-indexer` SBOM generator plugin. The following command saves the SBOM to a file at `build/sbom.spdx.json`.