container-hadolint

What this skill does

# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```yaml
name: Hadolint
on: [push, pull_request]

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

      - name: Hadolint Dockerfile
        uses: hadolint/[email protected]
        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

```yaml
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:

```yaml
# .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:

```bash
# 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**: Never switch to root USER in Dockerfile
- **DL3020**: Use COPY instead of ADD (prevents arbitrary URL fetching)
- **DL3025**: Use JSON notation for CMD/ENTRYPOINT (prevents shell injection)

See `references/security_rules.md` for complete security rule catalog with CIS mappings.

### 5. Multi-Stage Build Validation

Scan complex multi-stage Dockerfiles:

```bash
# Validate all stages
hadolint Dockerfile

# Stage-specific validation (use custom script)
./scripts/hadolint_multistage.py Dockerfile
```

**Common Multi-Stage Issues:**
- Using same user across build and runtime stages
- Copying unnecessary build tools to production image
- Missing security hardening in final stage
- Secrets present in build stage propagating to runtime

**When to use**: Complex builds, security-hardened images, production containerization.

### 6. Pre-Commit Hook Integration

Prevent insecure Dockerfiles from being committed:

```bash
# Install pre-commit hook using bundled script
./scripts/install_precommit.sh

# Or manually create hook
cat << 'EOF' > .git/hooks/pre-commit
#!/bin/bash
for dockerfile in $(git diff --cached --name-only | grep -E 'Dockerfile'); do
  hadolint --failure-threshold warning "$dockerfile" || exit 1
done
EOF

chmod +x .git/hooks/pre-commit
```

**When to use**: Developer workstations, team onboarding, mandatory security controls.

## Security Considerations

### Sensitive Data Handling

- **Secret Detection**: Hadolint flags hardcoded secrets in ENV, ARG, LABEL instructions
- **Build Secrets**: Use Docker BuildKit secrets (`RUN --mount=type=secret`) instead of ARG for credentials
- **Multi-Stage Security**: Ensure secrets in build stages don't leak to final image
- **Image Scanning**: Hadolint validates Dockerfile - combine with image scanning (Trivy, Grype) for runtime security

### Access Control

- **CI/CD Permissions**: Hadolint scans require read access to Dockerfile and build context
- **Report Storage**: Treat scan reports as internal documentation - may reveal security practices
- **Trusted Registries**: Configure `trustedRegistries` to enforce approved base image sources

### Audit Logging

Log the following for compliance and security auditing:
- Scan execution timestamps and Dockerfile paths
- Rule violations by severity (error, warning, info)
- Suppressed rules and justifications
- Base image registry validation results
- Remediation actions and timeline

### Compliance Requirements

- **CIS Docker Benchmark 1.6**: Hadolint rules map to CIS controls (see `references/cis_mapping.md`)
  - 4.1: Create a user for the container (DL3002)
  - 4.6: Add HEALTHCHECK instruction (DL3025)
  - 4.7: Do not use update alone in Dockerfile (DL3009)
  - 4.9: Use COPY instead of ADD (DL3020)
- **OWASP Docker Security**: Validates against OWASP container security best practices
- **NIST SP 800-190**: Application container security guidance

## Bundled Resources

### Scripts (`scripts/`)

- `hadolint_scan.py` - Comprehensive scanning with multiple Dockerfiles and output formats
-