Dockle — Container Image Linter for Security Best Practices

Introduction

Dockle analyzes built container images (not Dockerfiles) to find security issues and best-practice violations. Unlike Dockerfile linters that only check build instructions, Dockle inspects the final image layers, filesystem, and metadata to catch problems that survive the build process, such as leftover secrets, unnecessary setuid binaries, and missing healthchecks.

What Dockle Does

• Checks container images against CIS Docker Benchmark security rules
• Detects credentials, tokens, and secrets accidentally baked into image layers
• Identifies unnecessary setuid/setgid binaries that expand the attack surface
• Verifies healthcheck, user, and content trust metadata is properly configured
• Works with local images, remote registries, and tar archives

Architecture Overview

Dockle pulls or loads a container image, decompresses its layers, and runs a series of checkpoint-based analyzers against the image configuration and filesystem. Each checkpoint maps to a CIS benchmark rule or Docker best practice. Results are categorized by severity (FATAL, WARN, INFO, PASS) and output as text, JSON, or SARIF for integration with security dashboards.

Self-Hosting & Configuration

• Install via Homebrew, apt, or download a single binary from GitHub releases
• Run against any OCI-compatible image without needing the source Dockerfile
• Use .dockleignore to suppress specific checkpoints for accepted risks
• Set --exit-code 1 to fail CI pipelines on any finding above INFO level
• Integrate with GitHub Actions, GitLab CI, or Jenkins as a scan step

Key Features

• Scans built images, catching issues that Dockerfile linters miss
• CIS Docker Benchmark alignment for compliance-ready reports
• Secret detection in image layers (AWS keys, SSH keys, certificates)
• Single binary with no runtime dependencies; runs in any CI environment
• SARIF output for integration with GitHub Advanced Security and other platforms

Comparison with Similar Tools

• Hadolint — Lints Dockerfiles (source); Dockle scans built images (output)
• Trivy — Focuses on CVE vulnerability scanning; Dockle focuses on configuration best practices
• Grype — Dependency vulnerability scanner; Dockle checks image structure and metadata
• Docker Scout — Commercial image analysis; Dockle is free and open source
• Snyk Container — SaaS-based; Dockle runs locally without accounts or API keys

FAQ

Q: Does Dockle find CVE vulnerabilities? A: No. Dockle focuses on configuration and best-practice issues. Use Trivy or Grype alongside Dockle for CVE scanning.

Q: Can it scan images without Docker installed? A: Yes. Dockle can pull from registries directly or scan .tar image archives without a Docker daemon.

Q: How do I suppress false positives? A: Create a .dockleignore file listing checkpoint IDs (e.g., CIS-DI-0001) to skip specific rules.

Q: Does it work with Podman images? A: Yes. Dockle works with any OCI-compatible container image regardless of the build tool.

Sources

• https://github.com/goodwithtech/dockle
• https://containers.goodwith.tech