phy-dockerfile-audit — Dockerfile Security Auditor

Scans Dockerfiles for security misconfigurations without requiring Docker, hadolint, or any external tool. Zero external dependencies — pure Python stdlib.

Quick Start

# Scan a single Dockerfile
python3 ~/.claude/skills/phy-dockerfile-audit/scripts/dockerfile_audit.py Dockerfile

# Scan entire project (finds all Dockerfiles recursively)
python3 ~/.claude/skills/phy-dockerfile-audit/scripts/dockerfile_audit.py .

# CI mode — exits 1 on any CRITICAL or HIGH finding
python3 ~/.claude/skills/phy-dockerfile-audit/scripts/dockerfile_audit.py . --ci

# GitHub Actions annotation format
python3 ~/.claude/skills/phy-dockerfile-audit/scripts/dockerfile_audit.py . --format github

# JSON output (for SARIF / dashboards)
python3 ~/.claude/skills/phy-dockerfile-audit/scripts/dockerfile_audit.py . --format json

# Run one specific check
python3 ~/.claude/skills/phy-dockerfile-audit/scripts/dockerfile_audit.py . --check DF003

The 10 Checks

Pass / Fail Criteria

DF001 — Running as root

• FAIL (CRITICAL): No USER instruction in the Dockerfile, OR explicit USER root / USER 0.
• PASS: USER nonroot, USER appuser, USER 1001, or any non-root user. Docker 25+ supports USER --uid 1001.
• Note: Fires once per Dockerfile. If last USER before CMD is non-root, passes.

DF002 — Unpinned base image

• FAIL (HIGH): FROM ubuntu:latest, FROM node (no tag), FROM python:latest.
• PASS: FROM ubuntu:22.04, FROM node:20-slim, FROM python@sha256:abc123... (digest pin).
• Note: FROM scratch is exempt.

DF003 — Secret in ENV

• FAIL (CRITICAL): ENV PASSWORD=actual_value, ENV API_KEY=sk-abc123, ENV DB_PASSWORD=prod_pass.
• PASS: ENV API_KEY="", ENV API_KEY=placeholder, ENV API_KEY=${SECRET} (uses build arg or runtime var).
• Detection: Key name must match: password|passwd|secret|api_key|token|auth|credential|private_key|db_pass|jwt_secret|signing_key|encryption_key|smtp_pass.

DF004 — ADD with remote URL

• FAIL (HIGH): ADD https://get.example.com/install.sh /tmp/install.sh — fetched at build time with no hash verification.
• PASS: COPY local_file.sh /tmp/ or RUN curl -fsSL https://... | sha256sum --check.

DF005 — Shell form ENTRYPOINT/CMD

• FAIL (MEDIUM): ENTRYPOINT service nginx start, CMD python app.py (no brackets).
• PASS: ENTRYPOINT ["nginx", "-g", "daemon off;"], CMD ["python", "app.py"] (exec form with JSON array).

DF006 — sudo installed

• FAIL (HIGH): RUN apt-get install -y sudo, RUN apt install sudo vim.
• PASS: sudo not installed anywhere. Specific commands needing elevation should use gosu or capability grants.

DF007 — Missing .dockerignore

• FAIL (MEDIUM): No .dockerignore file in the same directory as the Dockerfile.
• PASS: .dockerignore exists alongside the Dockerfile.
• Recommended .dockerignore:

  .git
  .env*
  node_modules
  *.log
  coverage/
  .DS_Store
  **/__pycache__
  

DF008 — Privileged port

• FAIL (MEDIUM): EXPOSE 80, EXPOSE 443, EXPOSE 22 — ports below 1024.
• PASS: EXPOSE 8080, EXPOSE 3000 — use docker run -p 80:8080 to map at runtime.

DF009 — apt-get without --no-install-recommends

• FAIL (LOW): RUN apt-get install -y curl (no flag).
• PASS: RUN apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*.
• Impact: --no-install-recommends typically reduces image size by 20-40%.

DF010 — Secret ARG with hardcoded default

• FAIL (CRITICAL): ARG DB_PASSWORD=mysecret — the default appears in docker history --no-trunc.
• PASS: ARG DB_PASSWORD (no default) — pass at build time with --build-arg DB_PASSWORD=$SECRET.

CI Integration

# GitHub Actions
- name: Dockerfile Security Audit
  run: python3 scripts/dockerfile_audit.py . --format github --ci

# GitLab CI
dockerfile-audit:
  script:
    - python3 scripts/dockerfile_audit.py . --ci
  allow_failure: false

# Pre-commit hook
#!/bin/sh
python3 ~/.claude/skills/phy-dockerfile-audit/scripts/dockerfile_audit.py . --ci

Example Output

======================================================================
  phy-dockerfile-audit — Dockerfile Security Report
======================================================================
  Total: 6  |  Critical: 3  |  High: 2
======================================================================

🔴 [DF001] CRITICAL — Running as root (no USER instruction) (CWE-250)
   File : ./Dockerfile
   Code : (no USER directive in file)
   Fix  : Add 'USER nonroot' or: RUN useradd -r -u 1001 appuser && USER appuser

🔴 [DF003] CRITICAL — Secret-like value in ENV instruction (CWE-312)
   File : ./Dockerfile:5
   Code : ENV API_KEY=sk-prod-abc123xyz
   Fix  : Pass secrets at runtime via --env-file or Docker secrets.

🔴 [DF010] CRITICAL — Secret-like ARG with hardcoded default (CWE-312)
   File : ./Dockerfile:2
   Code : ARG DB_PASSWORD=supersecret123
   Fix  : Remove the default: ARG DB_PASSWORD (pass via --build-arg at build time)

🟠 [DF002] HIGH — Base image unpinned (latest / no tag) (CWE-1395)
   File : ./Dockerfile:1
   Code : FROM ubuntu:latest
   Fix  : Pin to a specific version: ubuntu:22.04 or use a SHA digest.

🟠 [DF004] HIGH — ADD with remote URL (arbitrary fetch) (CWE-494)
   File : ./Dockerfile:6
   Code : ADD https://example.com/script.sh /setup.sh
   Fix  : Use RUN curl -fsSL <url> | sha256sum -c <hash> instead.

🟡 [DF005] MEDIUM — Shell form ENTRYPOINT / CMD (no signal pass) (CWE-755)
   File : ./Dockerfile:7
   Code : ENTRYPOINT service nginx start
   Fix  : Use exec form: ENTRYPOINT ["service", "nginx", "start"]

Supported Dockerfile Variants

Technical Notes

• Zero external dependencies — pure Python 3.7+ stdlib
• Line continuation handling — \ continuations joined before analysis
• Comment stripping — # comments ignored
• Multi-stage builds — scans all FROM stages for unpinned tags
• Skips: .git/, node_modules/, dist/, build/, vendor/
• DF007 checks for .dockerignore relative to each Dockerfile found

Differentiation vs Existing Docker Skills

This is the only static Dockerfile security scanner on ClawHub. No hadolint required, no Docker daemon needed — works in any CI environment with Python 3.7+.

Companion Skills

Author

Canlah AI — Run performance marketing without breaking your brand.

• GitHub: github.com/PHY041
• All Skills: clawhub.ai/PHY041