Merge pull request #18454 from dvdksn/scout-freshness-q3

scout: q3 refresh

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

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

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

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

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
 
-<div style="position: relative; padding-bottom: 64.86486486486486%; height: 0;"><iframe src="https://www.loom.com/embed/451336c4508c42189532108fc37b2560?sid=f912524b-276d-417d-b44a-c2d39719aa1a" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
+The following is a video walkthrough of the process of setting up the workflow with GitLab.
+
+<iframe class="border-0 w-full aspect-video mb-8" allow="fullscreen" src="https://www.loom.com/embed/451336c4508c42189532108fc37b2560?sid=f912524b-276d-417d-b44a-c2d39719aa1a"></iframe>

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
 

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 <org-name>/scout-demo:v1 .
+   $ docker build -t <ORG_NAME>/scout-demo:v1 .
    ```
 
 4. Create and push the repository on Docker Hub:
 
    ```console
-   $ docker push <org-name>/scout-demo:v1
+   $ docker push <ORG_NAME>/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 <org-name> <org-name>/scout-demo
+   $ docker scout repo enable --org <ORG_NAME> <ORG_NAME>/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 <org-name>/scout-demo:v1
+   $ docker scout cves <ORG_NAME>/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 <org-name>/scout-demo:v2 .
+   $ docker build -t <ORG_NAME>/scout-demo:v2 .
    ```
 
 3. Push the image to the same repository on Docker Hub using a new version tag:
 
    ```console
-   $ docker push <org-name>/scout-demo:v2
+   $ docker push <ORG_NAME>/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 <org-name>/scout-demo:v3 .
+   $ docker build -t <ORG_NAME>/scout-demo:v3 .
    ```
 
 4. Push it to Docker Hub using the new version tag:
 
    ```console
-   $ docker push <org-name>/scout-demo:v3
+   $ docker push <ORG_NAME>/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 <org-name>/scout-demo:v3
+   $ docker scout cves <ORG_NAME>/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 <org-name>/scout-demo:v1 <org-name>/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 <ORG_NAME>/scout-demo:v1 <ORG_NAME>/scout-demo:v3
+```
+
+{{< /tabs >}}
 
 ## What's next?
 

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 <image> --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`.