Snyk CLI Docker Plugin

9.6.5 · active · verified Wed Apr 22

The `snyk-docker-plugin` is a specialized component designed to extend the capabilities of the Snyk CLI, enabling it to detect vulnerabilities within Docker images. It currently stands at version 9.6.5 and exhibits a rapid release cadence, with multiple patches and minor versions released weekly or bi-weekly, indicating active development and maintenance. This plugin is crucial for scanning a wide array of Linux-based operating systems (Debian, Red Hat, Alpine, etc.), including distroless and scratch images, across various architectures (ARM, AMD, PPC). A key differentiator is its ability to identify vulnerabilities not only through package managers (rpm, apk, deb) but also by detecting Node and Java binaries installed outside of standard package management, and by analyzing Dockerfiles directly. It supports various image protocols and container registries, providing comprehensive security analysis for containerized applications.

Common errors

```
Error: Node.js v18.x.x is not supported. Please upgrade to Node.js v20.19.x or higher.
```
cause The Snyk CLI and its plugins have updated their minimum Node.js version requirement.

fix Update your Node.js environment to version 20.19 or newer. Use `nvm install 20` and `nvm use 20` if using Node Version Manager.
```
Cannot find module 'snyk-docker-plugin'
```
cause Attempting to import the plugin as a regular Node.js module.

fix This package is a CLI plugin, not a library for programmatic import. Use the `snyk container test` command via the Snyk CLI instead of trying to import it directly.
```
ERROR: Could not find image 'my-image:latest'. Please ensure the image is available locally or in a configured registry.
```
cause The specified Docker image is not found in the local Docker daemon or accessible via configured registries.

fix Verify the image name and tag are correct. Ensure the image is pulled locally (`docker pull my-image:latest`) or that the Snyk CLI has correct registry authentication configured (`snyk config set dockerToken=...`).
```
Permission denied while accessing Docker socket.
```
cause The user running the Snyk CLI does not have appropriate permissions to interact with the Docker daemon socket.

fix Ensure your user is part of the `docker` group (`sudo usermod -aG docker $USER && newgrp docker`) or configure Docker daemon access appropriately. If running in CI, ensure the CI runner has necessary Docker permissions.

Warnings

breaking The minimum Node.js engine requirement was updated to `>=20.19`. Running the Snyk CLI (and thus this plugin) with older Node.js versions will result in errors.
Fix: Upgrade your Node.js environment to version 20.19 or higher. Use a tool like `nvm` to manage multiple Node.js versions: `nvm install 20 && nvm use 20`.
gotcha The `snyk-docker-plugin` is not a standalone library for direct programmatic use. Attempting to `import` or `require` it in your Node.js application will lead to errors as its API is internal and exposed solely via the Snyk CLI.
Fix: Interact with Docker image scanning functionality exclusively through the Snyk CLI by running `snyk container test ...` commands in your terminal or CI/CD pipelines.
gotcha When testing container images, it's crucial to specify the `--file` flag pointing to your Dockerfile for accurate base image detection and recommendations. Omitting it might lead to less precise results.
Fix: Always include `--file=<path/to/Dockerfile>` when running `snyk container test <IMAGE>` to enable full Dockerfile analysis and improve the accuracy of Snyk's recommendations.
deprecated Older versions of the Snyk CLI might require specific Docker daemon access or configurations. The plugin has continuously improved its ability to scan images from various sources, including archives or registries without direct daemon access. Relying on direct Docker daemon access for scanning might become less necessary or supported in future versions.
Fix: Ensure you are using the latest Snyk CLI version (`npm install -g snyk@latest`). Explore options like `snyk container test --file=./my-image.tar` or direct registry pulling which reduce dependencies on local Docker daemon setup.

Install

npm install snyk-docker-plugin npm
yarn add snyk-docker-plugin yarn
pnpm add snyk-docker-plugin pnpm

Imports

Snyk CLI usage
wrong:
```
import { DockerPlugin } from 'snyk-docker-plugin'
```
correct:
```
snyk container test <IMAGE_NAME>:<TAG>
```
This package is a plugin for the Snyk CLI and is not designed for direct programmatic import into user applications. Its functionality is exposed via the Snyk CLI commands, specifically `snyk container test`.
Snyk CLI type definitions
wrong:
```
import type { DockerScanResult } from 'snyk-docker-plugin'
```
correct:
```
import type { SnykTestOptions } from 'snyk'
```
While this plugin ships its own TypeScript types, they are internal to the Snyk CLI's architecture. Developers typically interact with the Snyk CLI's public API and types, rather than directly with the plugin's internal types. The main interaction is through CLI commands, not direct TypeScript imports.

Quickstart

Demonstrates the installation of the Snyk CLI and how to use the `snyk container test` command with a local or remote Docker image to scan for vulnerabilities, including options for specifying a Dockerfile or excluding application vulnerabilities.

npm install -g snyk

# Authenticate your Snyk CLI with your Snyk account
snyk auth

# Build a sample Docker image (assuming you have a Dockerfile in your current directory)
# For example, create a Dockerfile with:
# FROM node:20-alpine
# WORKDIR /app
# COPY package*.json ./
# RUN npm install
# COPY . .
# CMD ["node", "server.js"]
docker build -t my-vulnerable-app:latest .

# Test your Docker image for vulnerabilities using the Snyk Docker plugin
snyk container test my-vulnerable-app:latest \
  --file=./Dockerfile \
  --exclude-app-vulns \
  --severity-threshold=high

# Alternatively, test a remote image from Docker Hub
snyk container test node:20-alpine

# Scan a local Docker archive
docker save -o my-app.tar my-vulnerable-app:latest
snyk container test --file=./my-app.tar

view raw JSON →