Docker Audit

Docker Audit Skill

Purpose

Systematic audit of Docker configurations against the 10 most common Docker mistakes. Covers image security, build efficiency, runtime safety, and Compose best practices. Works with grep-based detection (no external tools required) plus optional deep scanning with hadolint, trivy, and dockle.

Quick Start

/docker-audit [path]

Discovery

Find all Docker files in scope:

find . -name "Dockerfile*" -o -name "compose*.yaml" -o -name "compose*.yml" -o -name "docker-compose*.yml" -o -name "docker-compose*.yaml" -o -name ".dockerignore" | head -50

Audit Categories

1. Image Tags (Critical)

# Detect :latest or untagged images
grep -n "^FROM.*:latest" Dockerfile*
grep -n "^FROM [^ :]*$" Dockerfile*
grep -rn "image:.*:latest" compose*.yaml docker-compose*.yml 2>/dev/null
grep -rn "image: [^ :]*$" compose*.yaml docker-compose*.yml 2>/dev/null

Pass: All FROM/image directives use pinned version tags (e.g., node:22.12-alpine) Fail: Any :latest or missing tag

2. Image Size (High)

# Check for bloated base images
grep -n "^FROM.*ubuntu\|^FROM.*debian\|^FROM.*centos\|^FROM.*fedora" Dockerfile*

Pass: Uses alpine, slim, or distroless variants Fail: Full OS base images without justification

3. Build Cache Ordering (Medium)

# Check COPY order — dependency files should come before source
grep -n "^COPY\|^ADD" Dockerfile*
# Correct: COPY package*.json -> RUN npm install -> COPY . .
# Wrong: COPY . . -> RUN npm install

Pass: Dependency manifests (package.json, requirements.txt, go.mod, Gemfile) copied and installed before source code Fail: COPY . . appears before dependency installation

4. Non-Root User (Critical)

# Check for USER directive
grep -n "^USER" Dockerfile*
# Check for user creation
grep -n "adduser\|useradd\|addgroup\|groupadd" Dockerfile*

Pass: USER directive present with non-root user Fail: No USER directive (defaults to root)

5. Secrets in Build (Critical)

# Detect secrets in Dockerfiles
grep -in "ENV.*PASSWORD\|ENV.*SECRET\|ENV.*API_KEY\|ENV.*TOKEN\|ENV.*CREDENTIAL" Dockerfile*
grep -in "ARG.*PASSWORD\|ARG.*SECRET\|ARG.*API_KEY\|ARG.*TOKEN" Dockerfile*
# Check for COPY of secret files
grep -in "COPY.*\.env\|COPY.*credentials\|COPY.*\.pem\|COPY.*\.key\|COPY.*\.p12" Dockerfile*

Pass: No secrets in ENV/ARG/COPY directives Fail: Secret-like values found in build context

6. Dockerignore (High)

# Check existence and content
ls .dockerignore 2>/dev/null
# Check for critical exclusions
grep -c ".git\|node_modules\|__pycache__\|\.env" .dockerignore 2>/dev/null

Pass: .dockerignore exists and excludes .git, node_modules/pycache, .env, logs Fail: Missing or incomplete .dockerignore

7. Health Checks (High)

# Dockerfile HEALTHCHECK
grep -n "HEALTHCHECK" Dockerfile*
# Compose healthcheck
grep -A3 "healthcheck:" compose*.yaml docker-compose*.yml 2>/dev/null

Pass: HEALTHCHECK in Dockerfile or healthcheck in Compose for all services Fail: No health check defined

8. Multi-Stage Builds (Medium)

# Count FROM directives (multi-stage = 2+)
grep -c "^FROM" Dockerfile*
# Check for AS aliases
grep -n "^FROM.*AS\|^FROM.*as" Dockerfile*

Pass: Production Dockerfile uses multi-stage (2+ FROM with AS alias) Fail: Single FROM for production images

9. Layer Efficiency (Medium)

# Count separate RUN commands (flag if >5)
grep -c "^RUN" Dockerfile*
# Check for cleanup in same layer as install
grep -n "rm -rf.*apt\|rm -rf.*cache\|rm -rf.*tmp\|rm -rf.*lists" Dockerfile*
# Detect split update/install (bad pattern)
grep -c "apt-get update" Dockerfile*
grep -c "apt-get install" Dockerfile*

Pass: RUN commands combined where logical, cleanup in same layer as install Fail: Many separate RUN commands, no cleanup, split update/install

10. Base Image Currency (Medium)

# Extract base images for scanning
grep "^FROM" Dockerfile* | awk -F'FROM ' '{print $2}' | awk '{print $1}'

# Trivy scan (if available)
trivy image --severity HIGH,CRITICAL <image>

# Docker Scout (if available)
docker scout cves <image>

Pass: No critical/high CVEs in base images Fail: Outdated base images with known vulnerabilities

Compose-Specific Checks

# File naming — modern convention is compose.yaml
ls compose.yaml compose.override.yaml 2>/dev/null
ls docker-compose.yml docker-compose.yaml 2>/dev/null

# Resource limits
grep -A5 "deploy:" compose*.yaml docker-compose*.yml 2>/dev/null | grep "limits"
grep "mem_limit\|cpus:" compose*.yaml docker-compose*.yml 2>/dev/null

# Named volumes vs bind mounts
grep "\\./" compose*.yaml docker-compose*.yml 2>/dev/null  # bind mounts (flag for prod)

# Deprecated CLI usage
grep "docker-compose" Makefile* scripts/*.sh 2>/dev/null  # should be docker compose

# Override structure
ls compose.override.yaml compose.prod.yaml compose.staging.yaml 2>/dev/null

# Verify merge output
docker compose config 2>/dev/null

Compose Checklist

• Uses compose.yaml naming (not docker-compose.yml)
• Override files for dev (compose.override.yaml) and prod (compose.prod.yaml)
• docker compose config produces valid merged output
• Image versions pinned in all compose files
• Resource limits set for all services
• Named volumes for persistent data (no bind mounts in prod)
• Healthcheck defined for each service
• No use of deprecated docker-compose CLI in scripts

External Tools

Run when available. Fall back to grep-based checks otherwise.

# Hadolint — Dockerfile linter (primary tool)
hadolint Dockerfile
hadolint --format json Dockerfile

# Trivy — vulnerability + misconfiguration scanner
trivy config Dockerfile
trivy image <built-image>

# Docker Scout — CVE scanning
docker scout cves <image>
docker scout recommendations <image>

# Dockle — container image linter
dockle <image>

Audit Report Format

# Docker Audit Report

**Date**: YYYY-MM-DD
**Scope**: [path]
**Files Scanned**: [list]

## Summary

| Severity | Count |
| -------- | ----- |
| Critical | 0     |
| High     | 0     |
| Medium   | 0     |
| Low      | 0     |

## Overall Score

[X/10 categories pass] — PASS / NEEDS WORK / FAIL

## Findings

### [Category] — [PASS/FAIL] (Severity)

- **File**: Dockerfile:14
- **Issue**: [description]
- **Fix**: [specific remediation]

## Dockerfile Checklist

- [ ] Image tags pinned (no :latest)
- [ ] Minimal base image (alpine/slim/distroless)
- [ ] Build cache optimized (deps before source)
- [ ] Non-root USER directive
- [ ] No secrets in Dockerfile/args
- [ ] .dockerignore exists and aggressive
- [ ] HEALTHCHECK defined
- [ ] Multi-stage build for production
- [ ] Layers combined and cleaned
- [ ] Base images scanned and current

## Compose Checklist

- [ ] Uses compose.yaml naming convention
- [ ] Override files for dev/prod separation
- [ ] Image versions pinned
- [ ] Resource limits set
- [ ] Named volumes (no bind mounts in prod)
- [ ] Healthcheck per service
- [ ] No deprecated docker-compose CLI usage

## Recommendations

### Immediate (Critical/High)

1. [action items]

### Short-Term (Medium)

1. [action items]

### Ongoing

1. [action items]

Integration

• /security-scan — covers application code; /docker-audit covers container config
• /infrastructure-setup — creates Docker files; /docker-audit validates them
• rules/docker.md — always-on guardrails; this skill is the deep audit

Tool Installation

# Hadolint (macOS)
brew install hadolint

# Trivy (macOS)
brew install trivy

# Dockle
brew install goodwithtech/r/dockle

# Docker Scout (built into Docker Desktop 4.17+)
docker scout version