/container-hadolint

name: container-hadolint
description: >
  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.
version: 0.1.0
maintainer: SirAppSec
category: devsecops
tags: [docker, hadolint, dockerfile, container-security, cis-benchmark, linting, ci-cd]
frameworks: [CIS, OWASP]
dependencies:
  tools: [hadolint, docker]
references:
  - https://github.com/hadolint/hadolint
  - https://www.cisecurity.org/benchmark/docker
  - https://docs.docker.com/develop/develop-images/dockerfile_best-practices/

Dockerfile Security Linting with Hadolint

Overview

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:

GitHub Actions

name: Hadolint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Hadolint Dockerfile
        uses: hadolint/hadolint-action@v3.1.0
        with:
          dockerfile: Dockerfile
          failure-threshold: warning
          format: sarif
          output-file: hadolint.sarif

      - name: Upload SARIF to GitHub Security
        if: always()
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: hadolint.sarif

GitLab CI

hadolint:
  image: hadolint/hadolint:latest-debian
  stage: lint
  script:
    - hadolint -f gitlab_codeclimate Dockerfile > hadolint-report.json
  artifacts:
    reports:
      codequality: hadolint-report.json
    when: always

**When to use**: Automated security gates, pull request checks, deployment validation.

3. Configuration Customization

Create `.hadolint.yaml` to customize rules:

# .hadolint.yaml
failure-threshold: warning
ignored:
  - DL3008  # Allow unpinned apt-get packages (assess risk first)
  - DL3059  # Allow multiple RUN instructions

trustedRegistries:
  - docker.io/library  # Official Docker Hub images
  - gcr.io/distroless  # Google distroless images
  - registry.access.redhat.com  # Red Hat registry

override:
  error:
    - DL3001  # Enforce: never use yum/dnf/zypper without version pins
  warning:
    - DL3015  # Warn: use --no-install-recommends with apt-get
  info:
    - DL3059  # Info: multiple RUN instructions reduce layer caching

label-schema:
  maintainer: text
  org.opencontainers.image.vendor: text
  org.opencontainers.image.version: semver

Use bundled templates in `assets/`:

• `assets/hadolint-strict.yaml` - Strict security enforcement (CRITICAL/HIGH only)
• `assets/hadolint-balanced.yaml` - Balanced validation (recommended)
• `assets/hadolint-permissive.yaml` - Permissive for legacy Dockerfiles

**When to use**: Reducing false positives, organizational standards, legacy Dockerfile migration.

4. Security-Focused Validation

Enforce critical security rules:

# Only fail on security issues (error severity)
hadolint --failure-threshold error Dockerfile

# Check specific security rules
hadolint --trusted-registry docker.io/library Dockerfile

# Scan all Dockerfiles in project
find . -name "Dockerfile*" -exec hadolint {} \;

# Generate security report with only errors
hadolint -f json Dockerfile | jq '.[] | select(.level == "error")'

**Critical Security Rules:**

• **DL3000**: Use absolute WORKDIR (prevents directory traversal)
• **DL3001**: Always use version pinning for package managers
• **DL3002**: Neve