Start With Docker Scout

Docker Scout analyzes image contents and generates a detailed report of packages and vulnerabilities that it detects. It can provide you with suggestions for how to remediate issues discovered by image analysis.

This guide takes a vulnerable container image and shows you how to use Docker Scout to identify and fix the vulnerabilities, compare image versions over time, and share the results with your team.

Prerequisites

• Docker installed on your system.

• Docker Scout set up. If not, initialize it using the command below:

$ docker scout init

👉 Step 1: Setup

Clone its repository:

$ git clone https://github.com/docker/scout-demo-service.git

Move into the directory:

$ cd scout-demo-service

Make sure you’re signed in to your Docker account, either by running the docker login command or by signing in with Docker Desktop.

Build the image and push it to a <ORG_NAME>/scout-demo:v1, where <ORG_NAME> is the Docker Hub namespace you push to.

$ docker build --push -t <ORG_NAME>/scout-demo:v1 .

👉 Step 2: Enable Docker Scout

Docker Scout analyzes all local images by default. To analyze images in remote repositories, you need to enable it first. You can do this from Docker Hub, the Docker Scout Dashboard, and CLI.

1. Sign in to your Docker account with the docker login command or use the Sign in button in Docker Desktop.

2. Next, enroll your organization with Docker Scout, using the docker scout enroll command.

$ docker scout enroll ORG_NAME
     ✓ Successfully enrolled organization ORG_NAME with Docker Scout Free

3. Enable Docker Scout for your image repository with the docker scout repo enable command.

$ docker scout repo enable --org <ORG_NAME> <ORG_NAME>/scout-demo

👉 Step 3: Analyze image vulnerabilities

After building, use the docker scout CLI command to see vulnerabilities detected by Docker Scout.

Use Docker Scout to scan the Docker image for known vulnerabilities. Replace IMAGE_NAME:TAG with the name and tag of the Docker image you pulled in the previous step.

For Example application for this guide uses a vulnerable version of Express. The following command shows all CVEs affecting Express in the image you just built:

$ docker scout cves --only-package express

Docker Scout analyzes the image you built most recently by default, so there’s no need to specify the name of the image in this case.

👉 Step 4: Fix application vulnerabilities

The fix suggested by Docker Scout is to update the underlying vulnerable express version to 4.17.3 or later.

One of the most effective ways to fix vulnerabilities is by updating the vulnerable packages to their latest, patched versions. In the case of Node.js and Express, you can update the package.json file and run npm install

Open the package.json file in a text editor and update the version of Express to the latest version.

   "dependencies": {
-    "express": "4.17.1"
+    "express": "4.17.3"
   }

Run npm install to install the updated packages.

npm install

Rebuild the image with a new tag and push it to your Docker Hub repository:

$ docker build --push -t <ORG_NAME>/scout-demo:v2 .

Now, viewing the latest tag of the image in Docker Desktop, the Docker Scout Dashboard, or CLI, you can see that you have fixed the vulnerability.

$ docker scout cves --only-package express
    ✓ Provenance obtained from attestation
    ✓ Image stored for indexing
    ✓ Indexed 79 packages
    ✓ No vulnerable package detecte

   ## Overview

          │                  Analyzed Image                   
  ────────────────────┼───────────────────────────────────────────────────
    Target            │  mobywhale/scout-demo:v2                   
      digest          │  ef68417b2866                                     
      platform        │ linux/arm64                                       
      provenance      │ https://github.com/docker/scout-demo-service.git  
                      │  7c3a06793fc8f97961b4a40c73e0f7ed85501857         
      vulnerabilities │    0C     0H     0M     0L                        
      size            │ 19 MB                                             
      packages        │ 1                 


 ## Packages and Vulnerabilities

  No vulnerable packages detected

👉 Step 5: Evaluate policy compliance

While inspecting vulnerabilities based on specific packages can be useful, it isn’t the most effective way to improve your supply chain conduct.

Docker Scout also supports policy evaluation, a higher-level concept for detecting and fixing issues in your images. Policies are a set of customizable rules that let organizations track whether images are compliant with their supply chain requirements.

Because policy rules are specific to each organization, you must specify which organization’s policy you’re evaluating against. Use the docker scout config command to configure your Docker organization.

$ docker scout config organization ORG_NAME

 ✓ Successfully set organization to ORG_NAME

Now you can run the quickview command to get an overview of the compliance status for the image you just built. The image is evaluated against the default, out-of-the-box policies.

$ docker scout quickview

...
Policy status  FAILED  (2/6 policies met, 2 missing data)

  Status │                  Policy                   │           Results
─────────┼───────────────────────────────────────────┼──────────────────────────────

  ✓      │ Copyleft licenses                         │    0 packages
  !      │ Default non-root user                     │
  !      │ Fixable critical and high vulnerabilities │    2C    16H     0M     0L
  ✓      │ High-profile vulnerabilities              │    0C     0H     0M     0L
  ?      │ Outdated base images                      │    No data
  ?      │ Supply chain attestations                 │    No data

Exclamation marks in the status column indicate a violated policy. Question marks indicate that there isn’t enough metadata to complete the evaluation. A check mark indicates compliance.

👉 Step 6: Improve compliance

The output of the quickview command shows that there's room for improvement. Some of the policies couldn't evaluate successfully (No data) because the image lacks provenance and SBOM attestations. The image also failed the check on a few of the evaluations.

Policy evaluation does more than just check for vulnerabilities. Take the Default non-root user policy for example. This policy helps improve runtime security by ensuring that images aren't set to run as the root superuser by default.

To address this policy violation, edit the Dockerfile by adding a USER instruction, specifying a non-root user:

  CMD ["node","/app/app.js"]
  EXPOSE 3000
+ USER appuser

Additionally, to get a more complete policy evaluation result, your image should have SBOM and provenance attestations attached to it. Docker Scout uses the provenance attestations to determine how the image was built so that it can provide a better evaluation result.

Before you can build an image with attestations, you must enable the containerd image store (or create a custom builder using the docker-container driver). The default image store doesn't support manifest lists, which is how the provenance attestations are attached to an image.

Open Settings in Docker Desktop. Under the General section, check the Use containerd for pulling and storing images option. Note that changing the image store hides existing images and containers until you switch back.

With the containerd image store enabled, rebuild the image with a new v3 tag. This time, add the --provenance=true and --sbom=true flags.

$ docker build --provenance=true --sbom=true --push -t <ORG_NAME>/scout-demo:v3 .

Replace <ORG_NAME> with your organization's name.

• --provenance=true: This option indicates that you want to include provenance information in the build. Provenance information includes details about the build context, such as the source repository and commit hash.

• --sbom=true: This option tells Docker to generate a Software Bill of Materials (SBOM) during the build process. An SBOM lists all the components and dependencies used in the image, which is useful for tracking and managing software supply chain security.

• --push: This option instructs Docker to push the built image to a remote repository after the build is complete.

• -t <ORG_NAME>/scout-demo:v3: This option specifies the tag for the built image. Replace <ORG_NAME> with your organization's name. The tag v3 indicates the version of the image.

After the build is successful, you can push the image to a remote repository using the following command:

$ docker push <ORG_NAME>/scout-demo:v3

Replace <ORG_NAME> with your organization's name.

👉 Step 7: View in Dashboard

After pushing the updated image with attestations, it’s time to view the results through a different lens: the Docker Scout Dashboard.

1. Open the Docker Scout Dashboard.

2. Sign in with your Docker account.

3. Select Images in the left-hand navigation.

The images page lists your Scout-enabled repositories. Select the image in the list to open the Image details sidebar. The sidebar shows a compliance overview for the last pushed tag of a repository.

Inspect the Outdated base images policy. This policy checks whether base images you use are up-to-date. It currently has a non-compliant status, because the example image uses an old version alpine as a base image.

Select the View fix button next to the policy name for details about the violation, and recommendations on how to address it. In this case, the recommended action is to enable Docker Scout’s GitHub integration, which helps keep your base images up-to-date automatically.

Summary:

This guide has scratched the surface on some of the ways Docker Scout can support software supply chain management:

• How to enable Docker Scout for your repositories

• Analyzing images for vulnerabilities

• Policy and compliance

• Fixing vulnerabilities and improving compliance