Dockerfile security linting and best practice validation using Hadolint with 100+ built-in rules aligned to CIS Docker Benchmark. Use when: (1) Analyzing Dockerfiles for security misconfigurations and anti-patterns, (2) Enforcing container image security best practices in CI/CD pipelines, (3) Detecting hardcoded secrets and credentials in container builds, (4) Validating compliance with CIS Docker Benchmark requirements, (5) Integrating shift-left container security into developer workflows, (6) Providing remediation guidance for insecure Dockerfile instructions.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Dockerfile security linting and best practice validation using Hadolint with 100+ built-in rules aligned to CIS Docker Benchmark. Use when: (1) Analyzing Dockerfiles for security misconfigurations and anti-patterns, (2) Enforcing container image security best practices in CI/CD pipelines, (3) Detecting hardcoded secrets and credentials in container builds, (4) Validating compliance with CIS Docker Benchmark requirements, (5) Integrating shift-left container security into developer workflows, (6) Providing remediation guidance for insecure Dockerfile instructions.
Hadolint is a Dockerfile linter that validates container build files against security best practices and the CIS Docker Benchmark. It analyzes Dockerfile instructions to identify misconfigurations, anti-patterns, and security vulnerabilities before images are built and deployed.
Hadolint integrates ShellCheck to validate RUN instructions, ensuring shell commands follow security best practices. With 100+ built-in rules mapped to CIS Docker Benchmark controls, Hadolint provides comprehensive security validation for container images.
Quick Start
Install Hadolint
# macOS via Homebrew
brew install hadolint
# Linux via binary
wget -O /usr/local/bin/hadolint https://github.com/hadolint/hadolint/releases/latest/download/hadolint-Linux-x86_64
chmod +x /usr/local/bin/hadolint
# Via Docker
docker pull hadolint/hadolint
Scan Dockerfile
# Scan Dockerfile in current directory
hadolint Dockerfile
# Scan with specific Dockerfile path
hadolint path/to/Dockerfile
# Using Docker
docker run --rm -i hadolint/hadolint < Dockerfile
Generate Report
# JSON output for automation
hadolint -f json Dockerfile > hadolint-report.json
# GitLab Code Quality format
hadolint -f gitlab_codeclimate Dockerfile > hadolint-codeclimate.json
# Checkstyle format for CI integration
hadolint -f checkstyle Dockerfile > hadolint-checkstyle.xml
Core Workflows
1. Local Development Scanning
Validate Dockerfiles during development:
# Basic scan with colored output
hadolint Dockerfile
# Scan with specific severity threshold
hadolint --failure-threshold error Dockerfile
# Show only warnings and errors
hadolint --no-color --format tty Dockerfile | grep -E "^(warning|error)"# Verbose output with rule IDs
hadolint -t style -t warning -t error Dockerfile
Output Format:
Dockerfile:3 DL3008 warning: Pin versions in apt get install
Dockerfile:7 DL3025 error: Use JSON notation for CMD and ENTRYPOINT
Dockerfile:12 DL3059 info: Multiple RUN instructions detected
When to use: Developer workstation, pre-commit validation, iterative Dockerfile development.
2. CI/CD Pipeline Integration
Automate Dockerfile validation in build pipelines:
When to use: Automated security gates, pull request checks, deployment validation.
3. Configuration Customization
Create .hadolint.yaml to customize rules:
# .hadolint.yamlfailure-threshold:warningignored:-DL3008# Allow unpinned apt-get packages (assess risk first)-DL3059# Allow multiple RUN instructionstrustedRegistries:-docker.io/library# Official Docker Hub images-gcr.io/distroless# Google distroless images-registry.access.redhat.com# Red Hat registryoverride:error:-DL3001# Enforce: never use yum/dnf/zypper without version pinswarning:-DL3015# Warn: use --no-install-recommends with apt-getinfo:-DL3059# Info: multiple RUN instructions reduce layer cachinglabel-schema:maintainer:textorg.opencontainers.image.vendor:textorg.opencontainers.image.version:semver
Security Dashboards: Export JSON to Grafana, Kibana, Datadog for centralized monitoring
SDLC Integration
Development: Pre-commit hooks provide immediate feedback
Code Review: PR checks prevent insecure Dockerfiles from merging
Testing: Scan test environment Dockerfiles
Staging: Validation gate before production promotion
Production: Periodic audits of deployed container configurations
Troubleshooting
Issue: Too Many False Positives
Symptoms: Legitimate patterns flagged (legacy Dockerfiles, specific use cases)
Solution:
# Create .hadolint.yamlignored:-DL3059# Multiple RUN instructions (valid for complex builds)# Or use inline ignores# hadolint ignore=DL3008RUNapt-getupdate&&apt-getinstall-ycurl
Consult references/remediation_guide.md for rule-specific guidance.
Issue: Base Image Registry Not Trusted
Symptoms: Error about untrusted registry even for legitimate images
Solution:
# Add to .hadolint.yamltrustedRegistries:-mycompany.azurecr.io-gcr.io/my-project-docker.io/library
Issue: ShellCheck Warnings in RUN Instructions
Symptoms: SC2086, SC2046 warnings from ShellCheck integration
Solution:
# Bad: Unquoted variables
RUN echo $MY_VAR > file.txt
# Good: Quoted variables
RUN echo "$MY_VAR" > file.txt
# Or disable specific ShellCheck rule
# hadolint ignore=DL4006
RUN echo $MY_VAR > file.txt
See references/shellcheck_integration.md for complete ShellCheck guidance.
Issue: Multi-Stage Build Not Recognized
Symptoms: Errors about missing USER instruction despite proper multi-stage setup
Solution:
# Ensure each stage has appropriate USER
FROM node:18 AS builder
# Build operations...
FROM node:18-alpine AS runtime
USER node # Add USER in final stage
CMD ["node", "app.js"]
Issue: CI Pipeline Failing on Warnings
Symptoms: Build fails on low-severity issues
Solution:
# Adjust failure threshold in CI
hadolint --failure-threshold error Dockerfile
# Or configure per-environmentif [ "$CI_ENVIRONMENT" == "production" ]; then
hadolint --failure-threshold warning Dockerfile
else
hadolint --failure-threshold error Dockerfile
fi
Advanced Configuration
Custom Rule Severity Override
# .hadolint.yamloverride:error:-DL3001# Package versioning is critical-DL3020# COPY vs ADD is security-criticalwarning:-DL3059# Multiple RUN is warning, not infoinfo:-DL3008# Downgrade apt-get pinning to info for dev images
Inline Suppression
# Suppress single rule for one instruction
# hadolint ignore=DL3018
RUN apk add --no-cache curl
# Suppress multiple rules
# hadolint ignore=DL3003,DL3009
WORKDIR /tmp
RUN apt-get update && apt-get install -y wget
# Global suppression (use sparingly)
# hadolint global ignore=DL3059
Trusted Registry Enforcement
# .hadolint.yamltrustedRegistries:-docker.io/library# Official images only-gcr.io/distroless# Google distroless-cgr.dev/chainguard# Chainguard images# This will error on:# FROM nginx:latest ❌ (docker.io/nginx)# FROM docker.io/library/nginx:latest ✅ (trusted)
