Dockle is an open-source container image linter written in Go that audits already-built Docker images against security and best-practice checkpoints, aimed at developers and DevSecOps teams who ship containers and want that audit to run automatically.

What it is

Dockle is a container image linter that lives in the Docker and Kubernetes tooling ecosystem, where images are the artifact everyone builds, ships and runs. It inspects a built image rather than the Dockerfile that produced it, and it reports its findings as checkpoints, a set that includes the CIS Benchmarks. Its stated goals are narrow and practical: help build Docker images that follow Docker's own best-practice guidance, and help build secure images. It is distributed as a single binary with no dependencies, which is the shape that makes it usable as a pipeline step rather than a separate piece of infrastructure.

The problem it solves is the gap between linting a recipe and auditing the meal. Dockerfile linters read the source text and never see what actually landed in the image, while host-level security scripts inspect the Docker daemon, its containers and its runtime instead of the artifact an operator is about to push. Dockle targets the image itself, in the same place where vulnerability scanners such as Clair operate, and it does so from a binary that is marked as suitable for CI. That combination is the specific role it fills: an image-scoped, dependency-free checkpoint audit that a build pipeline can run and gate on, where Docker Bench for Security is a shell script with its own dependencies and is not CI suitable.

Key capabilities

• Detects container image vulnerabilities and reports checkpoint results that include CIS Benchmarks coverage.
• Simple invocation: pass only the image name, as in dockle [YOUR_IMAGE_NAME].
• Scans an image by name or scans an image file.
• Emits results as JSON or as SARIF, and supports specifying the exit code and the exit level for pipeline gating.
• Ignores specified checkpoints, and can accept or reject suspicious environment variables, files and file extensions.
• Authorizes against private registries including Docker Hub, Amazon ECR, Google Container Registry and self-hosted registries using BasicAuth.
• Integrates with continuous integration through a GitHub Action and configurations for Travis CI, CircleCI and GitLab CI.
• Installs through Homebrew, RHEL/CentOS, Debian/Ubuntu and Arch Linux packages, Windows PowerShell 7, a standalone binary, asdf, mise, from source, or by running it as a Docker image.

Who uses it and how

• DevSecOps teams run it as a pipeline gate alongside Travis CI, CircleCI, Jenkins and GitLab CI so that an image is checked before it is promoted.
• Teams publishing to private registries point it at Docker Hub, Amazon ECR, Google Container Registry or a self-hosted registry protected by BasicAuth, so the audit works on internal images and not only public ones.
• Image maintainers use it to check adherence to Docker's documented Dockerfile best practices without reading the Dockerfile manually.
• Organizations adopting CIS Benchmarks as their baseline use the checkpoint output as the concrete evidence trail for image review.

Getting started

Install with Homebrew using brew install goodwithtech/r/dockle, noting that versions 0.1.16 and older should first be removed with brew untap goodwithtech/dockle. Then run dockle [YOUR_IMAGE_NAME]; the README also documents a Docker image, a standalone binary, and asdf and mise as installation routes.

How it compares

Hadolint lints a Dockerfile, while Dockle lints the image that Dockerfile produced, so the two answer different questions and are commonly run together. Docker Bench for Security is a shell script aimed at the host Docker daemon, containers and runtime and carries dependencies, whereas Dockle is a dependency-free binary aimed at the image and is marked CI suitable. Clair also scans images from a binary, but it is not marked as CI suitable, which is the axis on which Dockle positions itself.

When to use it — and when not to

Choose Dockle when the audit target is a built image and the audit must run unattended inside CI, because it is a single binary with no dependencies to operate and nothing to host. Do not choose it as a substitute for Dockerfile linting, since its target is the image and not the Dockerfile source, and do not expect it to cover the host daemon and runtime layer that Docker Bench for Security addresses. One caveat must be checked before adoption: the registry metadata lists the licence as Apache-2.0 while the README badge states AGPL v3, so the actual licensing terms should be confirmed for the specific version in use rather than assumed.

$ brew untap goodwithtech/dockle # who use 0.1.16 or older version
$ brew install goodwithtech/r/dockle
$ dockle [YOUR_IMAGE_NAME]

$ brew install goodwithtech/r/dockle

VERSION=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
) && rpm -ivh https://github.com/goodwithtech/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.rpm

VERSION=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
) && curl -L -o dockle.deb https://github.com/goodwithtech/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Linux-64bit.deb
$ sudo dpkg -i dockle.deb && rm dockle.deb

git clone https://aur.archlinux.org/dockle-bin.git
cd dockle-bin
makepkg -sri

VERSION=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
) && curl -L -o dockle.zip https://github.com/goodwithtech/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Windows-64bit.zip
$ unzip dockle.zip && rm dockle.zip
$ ./dockle.exe [IMAGE_NAME]

if (((Invoke-WebRequest "https://api.github.com/repos/goodwithtech/dockle/releases/latest").Content) -match '"tag_name":"v(?<ver>[^"]+)"') {
$VERSION=$Matches.ver &&
Invoke-WebRequest "https://github.com/goodwithtech/dockle/releases/download/v${VERSION}/dockle_${VERSION}_Windows-64bit.zip" -OutFile dockle.zip &&
Expand-Archive dockle.zip && Remove-Item dockle.zip }

# Add dockle plugin
asdf plugin add dockle

# Show all installable versions
asdf list-all dockle

# Install specific version
asdf install dockle latest

# Set a version globally (on your ~/.tool-versions file)
asdf global dockle latest

# Now dockle commands are available
dockle --version

# Show all installable versions
mise ls-remote dockle

# Install specific version
mise install dockle@latest

# Set a version globally
mise use -g dockle@latest

# Now dockle commands are available
dockle --version

$ GO111MODULE=off go get github.com/goodwithtech/dockle/cmd/dockle
$ cd $GOPATH/src/github.com/goodwithtech/dockle && GO111MODULE=on go build -o $GOPATH/bin/dockle cmd/dockle/main.go

$ VERSION=$(
 curl --silent "https://api.github.com/repos/goodwithtech/dockle/releases/latest" | \
 grep '"tag_name":' | \
 sed -E 's/.*"v([^"]+)".*/\1/' \
) && docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  goodwithtech/dockle:v${VERSION} [YOUR_IMAGE_NAME]