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#

bash

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

IDSeverityIssueCWEWhat it detectsDF001CRITICALRunning as rootCWE-250No USER instruction, or USER rootDF002HIGHUnpinned base imageCWE-1395:latest tag or no tag on FROMDF003CRITICALSecret in ENVCWE-312ENV PASSWORD=... — baked into image layerDF004HIGHADD with remote URLCWE-494ADD https://... — no integrity checkDF005MEDIUMShell form ENTRYPOINT/CMDCWE-755Signal handling failure — PID 1 won't get SIGTERMDF006HIGHsudo installedCWE-250apt-get install sudo — privilege escalationDF007MEDIUMMissing .dockerignoreCWE-552.env, .git, node_modules sent to build contextDF008MEDIUMPrivileged port exposedCWE-284EXPOSE < 1024 requires root or CAP_NET_BIND_SERVICEDF009LOWapt-get bloatCWE-1395Missing --no-install-recommendsDF010CRITICALSecret ARG defaultCWE-312ARG PASSWORD=value — in docker history

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: text

  .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#

yaml

# 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

bash

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

Example Output#

text

======================================================================
  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#

PatternDetected asDockerfile✅Dockerfile.dev, Dockerfile.prod✅api.dockerfile, worker.Dockerfile✅docker-compose.yml❌ (separate tool needed)

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#

SkillFocusphy-dockerfile-auditStatic security analysis — finds vulnerabilities in Dockerfile sourcedocker-essentialsOperational guide — docker run, docker ps, commandsdoro-docker-essentialsOperational guide — same as abovexcloud-docker-deployDeployment tool — compose templates, deployment workflows

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#

SkillRelationshipphy-k8s-security-auditKubernetes manifest security (DF checks the image source, K8s checks the deployment)phy-iac-sec-auditTerraform/CloudFormation securityphy-env-doctorDiscovers env vars in source codephy-secret-scanBroader secret detection (if installed)

---

Author#

Canlah AI — Run performance marketing without breaking your brand.

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