goodwithtech/dockle: a container image linter for CIS-based image checks

What dockle checks, and what it deliberately does not

Dockle takes a container image name and reports on how that image was built: files left behind, environment variables that look like secrets, missing or misconfigured users, and other items the project maps to CIS Benchmarks. The README frames the goal as helping you build best-practice Docker images and secure ones, with checkpoints that include CIS Benchmarks. The comparison table in the README is the clearest statement of scope: dockle's target is the image, its purpose is security audit plus Dockerfile lint, and it is marked as suitable for CI. Clair, by contrast, is listed with the purpose "Scan Vulnerabilities". That distinction matters more than the feature list. Dockle is not a CVE scanner and does not try to be one. If your question is "does this base image contain a known vulnerable library", dockle is the wrong tool. If your question is "did this image get built the way our policy says it should be", it is aimed exactly at that. The audience is teams that already build images and want a pass/fail gate in the pipeline, not teams looking for a full vulnerability management platform.

How dockle reads an image: binary, registry client, checkpoint set

The repository layout shows the shape of the tool. There is a cmd/ directory for the command entry point, a pkg/ directory for the implementation, and a config/ directory. The go.mod file lists github.com/containers/image/v5 as a dependency, which is the library dockle uses to pull and inspect image content, alongside the AWS SDK v2 and Google Cloud credential helper for registry authentication. Output formats are handled by separate dependencies: github.com/owenrumney/go-sarif/v2 for SARIF, and the CLI is built on github.com/urfave/cli/v3. The checkpoints themselves live in CHECKPOINT.md at the repository root, which is the file to read when you want to know what a given code actually means. The Dockerfile shows the runtime shape: a static Go binary (CGO_ENABLED=0) copied into an alpine:3.21 stage, with ca-certificates and shadow installed, and ENTRYPOINT set to dockle. Notably, the USER directive that would drop privileges is present but commented out in the Dockerfile, with a comment explaining it exists for use via a mounted /var/run/docker.sock. If you run the container against a mounted Docker socket, you are running as root by default, and that is a deliberate choice in the file rather than an oversight.

Installing dockle and running a first scan

The README's quick start is a Homebrew tap, which covers macOS, Linux and WSL. The tap name is goodwithtech/r.

brew install goodwithtech/r/dockle

The README also notes that anyone on version 0.1.16 or older should run brew untap goodwithtech/dockle first, because the tap name changed. Once installed, the basic invocation takes only an image name.

dockle [YOUR_IMAGE_NAME]

Replace the placeholder with a real image reference, for example an image you have already pulled. Dockle reads the image and prints its findings; the README's checkpoint summary and CHECKPOINT.md describe the categories. The README's Common Examples section documents getting or saving the results as JSON and as SARIF, and it documents two related flags for CI: one to specify the exit code and one to specify the exit level. Those two flags are what turn dockle from a report into a gate, so read that section before wiring it into CI. If you prefer not to install a binary, the README documents Debian/Ubuntu, RHEL/CentOS, Arch, Windows, PowerShell 7, asdf, mise, a manual binary download from the releases page, and building from source.

Registry authentication and the private-image case

The README devotes a section to authorization for private registries, with subsections for Docker Hub, Amazon ECR, Google Container Registry, and self-hosted registries using BasicAuth. This is where the dependency list earns its place: the AWS SDK v2 ECR client and the Google Cloud credential helper are in go.mod precisely so dockle can authenticate against those registries without a separate login dance. For a self-hosted registry the README describes BasicAuth. The practical consequence is that dockle is not limited to public images, but the credentials it needs are registry credentials, and the README does not describe a secret-storage mechanism of its own. You supply them the way the CI system expects, which means the security of those credentials is your CI's problem, not dockle's. That is a normal division of labour, but it is worth naming, because a linter that reads private images necessarily holds credentials that can read those images.

Where dockle gets in the way: ignore files and false positives

Any image linter that ships a fixed checkpoint set will produce findings you disagree with. Dockle's answer is an ignore file: the repository root contains a .dockleignore, which tells you the project uses this mechanism for its own image. The README documents ignoring specified checkpoints, and separately documents accepting or rejecting suspicious environment variables, files and file extensions. That last pair is the honest part of the design. A checkpoint that flags an environment variable as suspicious is a heuristic, and heuristics generate noise on images that legitimately carry configuration in env vars. The accept and reject options let you tune that per image, but tuning is manual and per-repository. There is no documented baseline-learning mode, and the README does not describe a way to derive an ignore set from a previous run. In practice this means the first weeks with dockle on an existing image fleet involve reading findings and writing ignore entries, and that work is not automated by anything in the repository as described. The other limitation is structural: because dockle inspects the built image, a finding arrives after the build has already succeeded. It cannot stop you from writing a bad Dockerfile, only from shipping the image that results.

dockle, hadolint and trivy: three different inspection points

The README's own comparison table puts dockle next to hadolint, Docker Bench for Security and Clair. Hadolint's target is the Dockerfile, and its purpose is Dockerfile lint; dockle's target is the image. That difference is not cosmetic. A Dockerfile linter can tell you that a RUN instruction installs packages without cleaning the package cache, and it can do so before a single layer is built. An image linter can tell you that a file is actually present in the final layer, including files that arrived through a base image you did not write. Neither subsumes the other, and running both is reasonable: hadolint on the source, dockle on the artifact. Docker Bench for Security is listed with the host, Docker daemon, image and container runtime as its target, and it is a shell script with dependencies, marked as not suitable for CI in the table, which places it in a different operating context entirely. The comparison list does not include trivy, but the search data shows people asking about it, and the distinction follows from the same table: trivy belongs to the vulnerability-scanning category that Clair occupies, while dockle's stated purpose is security audit and Dockerfile lint. Choosing between them is not a matter of quality, it is a matter of which question you are asking.

CI integration, licence and the cost of keeping up

The README has a Continuous Integration section with subsections for GitHub Action, Travis CI, CircleCI and GitLab CI, so the intended deployment is a pipeline step rather than a developer's laptop. The Dockerfile makes a containerised run straightforward, and the commented-out USER block is a reminder that mounting the Docker socket into that container grants it root-equivalent access to the host daemon. The licence situation needs care. The repository's LICENSE file and the GitHub metadata point to Apache-2.0, but the README carries an AGPL v3 badge and links to the GNU AGPL text. Those two sources disagree, and the discrepancy is not explained in the README. Anyone embedding dockle in a distributed product should resolve that before relying on either. On maintenance: the repository is not archived, and the last push was on 2026-08-10. Releases are much less frequent than commits, with v0.4.15 in January 2025, v0.4.14 in February 2024 and v0.4.13 in July 2023, so the tagged releases lag the development branch by a wide margin. If you pin to a release, expect to be running code that is well behind master, and check CHECKPOINT.md on master when a finding surprises you.

Editorial conclusion

Adopt dockle if you want a fast, dependency-free check on the image you actually ship, wired into CI through the exit-code and exit-level flags. Skip it if what you need is CVE detection, since the project positions itself as an image linter and points elsewhere for vulnerability scanning. Before rolling it out, run it against a few of your own images and read the checkpoint list in CHECKPOINT.md, because the default exit behaviour and the ignore-file format decide how much noise reaches your pipeline.

Frequently asked questions

Official sources

1. goodwithtech/dockle on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases