Scan Docker Images with Dockle for Security and Best Practices

Last reviewed: September 2026

Dockle is an open-source linter for Docker and OCI container images. It examines image contents and configuration for security and operational issues, including sensitive files, risky permissions, missing health checks and CIS-aligned image practices.

Dockle complements vulnerability scanners; it does not replace them. Use a vulnerability scanner to find known package and dependency vulnerabilities, and use Dockle to review how the image was assembled and configured.

What Dockle checks#

• CIS-aligned container-image checkpoints.
• Sensitive or suspicious files copied into image layers.
• Execution as the root user and risky setuid or setgid files.
• Missing HEALTHCHECK configuration.
• Unpinned or risky image-building practices.
• Package-manager caches and unnecessary image contents.
• Potential secrets exposed through files or environment configuration.

Understand result levels#

A severity label is not a complete risk decision. Review the finding, image purpose, runtime controls and compensating safeguards before suppressing it.

Install Dockle#

Use the upstream release page and checksums for Linux packages or archives. Confirm the current release and processor architecture before installation; do not copy a stale version number into automation.

The upstream project also provides a Homebrew tap for macOS and supported Linux environments.

For CI runners, pin an approved release and verify its checksum. Review the project release activity and open issues before treating the tool as a long-term control.

Scan a local image#

Build the image with an immutable CI tag, then run Dockle against that tag.

Read every FATAL and WARN result. Fix the Dockerfile or build context where possible, rebuild the image and scan again.

Fail a build on findings#

Set an explicit exit policy so CI does not succeed merely because the scanner produced output.

Start with a reviewed baseline, then tighten the policy deliberately. A sudden strict policy on an existing image estate can create broad suppressions instead of durable fixes.

Typical Dockerfile improvements#

• Use a minimal, trusted base image and pin it according to your update policy.
• Install only required packages and remove package-manager caches in the same layer.
• Create and use a non-root user when the workload permits it.
• Copy only required build artifacts into the runtime stage.
• Keep credentials and environment-specific secrets out of the image and build context.
• Add a meaningful health check when the runtime platform uses it.
• Use multi-stage builds to separate compilers and build dependencies from the runtime image.

Use suppressions carefully#

Some findings can be intentional or inapplicable. Document the reason, scope the exception to the exact check and image, assign an owner and expiration date, and review it after base-image or application changes.

• Never suppress a finding only to make the pipeline green.
• Do not place real secrets in ignore files or CI logs.
• Keep the exception near the policy configuration and under code review.
• Remove the exception when the underlying condition is fixed.

CI/CD workflow#

1. Build the image with a unique, immutable tag.
2. Scan dependencies and operating-system packages with a vulnerability scanner.
3. Run Dockle for configuration and image-construction checks.
4. Store machine-readable results as pipeline artifacts when supported.
5. Fail the pipeline according to the approved severity policy.
6. Sign and publish only the image digest that passed all required controls.
7. Re-scan stored images when vulnerability intelligence or policy changes.

Common problems#

• Image not found: confirm the exact tag and Docker daemon or registry access.
• Private registry denied: use the registry's supported short-lived authentication flow and protect credentials.
• False positive: verify the check against the current upstream issue tracker before suppressing it.
• Different local and CI results: compare Dockle versions, image digests, policy flags and runtime access.
• Slow or unreliable scans: cache approved tooling and avoid downloading unverified binaries during every build.
• No vulnerabilities reported: remember that Dockle is not primarily a CVE scanner.

Security limitations#

No single image scanner proves that a container is safe. Combine image linting with vulnerability management, secret scanning, software bills of materials, image signing, admission policy, least-privilege runtime settings, network controls, monitoring and patching.

Official references#

Dockle source and documentation

Dockle releases and checksums