Docker now ships with built-in security scanning support. You can locally scan your container images to identify possible vulnerabilities. This accelerates the development cycle by providing more immediate feedback compared to CI pipelines and cloud services.

The scan command is available by default in Docker version 20.10. Docker is partnered with Snyk to bring security scans to its CLI. A one-time consent prompt will appear the first time that you run the command. Type “y” and press enter to confirm the Snyk integration.

In addition to consenting to Snyk, container scanning also requires a Docker Hub login. Run docker login to supply your username and password before you start scanning.

Try running docker scan –version to check your installation. You’ll see the version number of the scan plugin. The output also names the security scanning provider that scan will use (currently Snyk). Additional providers could be added in the future.

How Scans Work

docker scan accepts an image name as a parameter. It will scan the image against the Snyk database of container vulnerabilities. A wide range of issues is covered, ranging from outdated base images to exploits against open-source software libraries that you’re using.

Snyk can show you the Dockerfile line that introduces a vulnerability. This gives you an immediate starting point as you resolve each issue. The results will show up right in your terminal after the scan completes.

The Snyk database is continually updated with new vulnerabilities. Don’t assume that an image that passes a scan once will always get the same result in the future. It’s a good practice to regularly scan images so that your workloads stay secure.

Scanning an Image

The simplest way to scan an image is to pass a tag to docker scan:

The scan might take a few seconds to complete. Larger images will need more time. The results will be shown in your terminal once they’re available. Example output from a successful scan is shown above.

While getting the all-clear might be comforting, the docker scan output is much more interesting when vulnerabilities are detected. Here’s a scan that found some issues.

Each issue has a brief description, an indication of its severity, and a link to get more information on the Snyk website.

More Advanced Scans

docker scan has much more functionality than the basic example above. You can customize the scan’s behavior using several flags.

Arguably, the most useful flag is –file. This takes the path to the image’s Dockerfile. When you provide Snyk with a Dockerfile, it can perform a more detailed analysis based on its contents. Some scanning features, such as outdated base image detection, are only available when you supply your image’s Dockerfile.

This will produce output similar to the following:

The last line will indicate whether your base image—the FROM instruction in your Dockerfile—is secure. Alternative tag suggestions will be displayed if the image is outdated or contains vulnerabilities that have since been resolved.

Sometimes, you might want to run a scan that ignores vulnerabilities in your base image. Pass the –exclude-base flag to achieve this. This is helpful if the base image contains many low-severity issues and there is no upgrade path available. Excluding the noise helps you focus on the resolvable problems within your image layers.

Customizing Scan Output

docker scan accepts a few different formatting options. So far, we’ve seen the default output. It presents issues as a human-readable list within your terminal.

Passing the –json flag instructs the command to emit the raw JSON it receives. This is ideal when you’re using docker scan programmatically in CI scripts or third-party tools. You can process the JSON yourself to extract just the information that you need.

Another option is –dependency-tree. This will emit a tree view of your image’s dependencies above the list of vulnerabilities. This can help you visualize how different packages are getting pulled in, letting you pinpoint where issues arise.

Finally, you can use the –severity flag to filter out unwanted vulnerabilities. Use low, medium, or high to indicate the severity that you’re interested in. The command will only report vulnerabilities rated at or above the given level.

Limitations

docker scan currently lacks support for Alpine Linux distributions. In addition, plugin version 0.7 has a serious bug that causes local scans to fail with an “image not found” error. v0.7 can only scan images that exist in Docker Hub and other public registries. The issue has been fixed in v0.8, but v0.7 remains the version that’s broadly distributed with Docker releases on Linux.

Beyond technical issues, the Snyk service imposes stringent rate limits on your use of docker scan. You can perform 10 scans for free each month. If you log in with Snyk, that increases to 200 scans per month.

Run docker scan –login to get your unique login URL. Copy it into your browser and follow the prompts to authenticate yourself. You can log in using Docker Hub or several third-party providers. Once you’re logged in, an “Authenticate” button will appear. Click this to return to your terminal. You should see a “Snyk is now ready to be used” message.

Summary

Docker’s built-in image scanning makes container vulnerabilities easier to discover and resolve. Any developer with access to the Docker CLI and a container image can now scan for vulnerabilities without having to push to a registry.

Regular scans help you guard your containers against potential threats. Outdated base images and vulnerabilities in dependencies significantly impact your security posture but can easily go unnoticed. docker scan gives you greater confidence in your containers by revealing issues that you’d have otherwise overlooked.