container-audit

name	container-audit
description	Audit Dockerfiles and docker-compose files for base image, user privileges, secret leaks, layer efficiency, signal handling, healthchecks, and compose safety. One sub-agent per Dockerfile. Static, live (Trivy/Grype), and apply modes.
argument-hint	["dockerfile-path-or-glob"]
allowed-tools	Read Grep Glob Write Edit Bash(bash:*) Agent
effort	high
paths	**/Dockerfile*

Container Audit

Output path directive (canonical — overrides in-body references). All file outputs from this skill MUST be written under .anthril/audits/container-audit/. Run mkdir -p .anthril/audits/container-audit before the first Write call. Primary artefact: .anthril/audits/container-audit/<artefact>. Do NOT write to the project root or to bare filenames at cwd. Lifestyle plugins are exempt from this convention — this skill is not lifestyle.

When to use

Run this skill when the user mentions:

• Dockerfile review, container security, image hardening
• CIS Docker Benchmark
• docker-compose audit
• Image size optimisation
• Secret leaks in container builds

Covers eight categories: base image choice (distroless/alpine, digest pinning), user privileges (non-root, dropped capabilities, read-only filesystem), secret leaks (no ARG/ENV secrets, BuildKit --mount=type=secret), layer efficiency (multi-stage, COPY --from, cache ordering), signal handling (tini, STOPSIGNAL, exec-form CMD), healthchecks, .dockerignore coverage, and docker-compose safety (no privileged: true, no host network, resource limits).

Before You Start

1. Determine operating mode. --live enables docker inspect, docker history, and Trivy/Grype scans. --apply enables per-finding Dockerfile patching. --runtime is not applicable for this skill (there is no safe runtime test for a Dockerfile without a target environment).
2. Find all Dockerfiles and compose files. Run scripts/list-dockerfiles.sh.
3. Sub-agent budget. One Agent(subagent_type=Explore) per Dockerfile. Warn above 10 files.
4. Load .container-ignore for suppression rules.

User Context

$ARGUMENTS

Container inventory: !bash "${CLAUDE_PLUGIN_ROOT}/skills/container-audit/scripts/list-dockerfiles.sh"

Live mode availability: !which docker 2>/dev/null || echo "docker:unavailable" · !which trivy 2>/dev/null || echo "trivy:unavailable"

---

Audit Phases

Phase 1: Discovery & Mode Selection

1. Parse inventory output. Separate Dockerfiles, docker-compose files, .dockerignore files.
2. Confirm scope and mode with the user.
3. In --live mode, verify Docker daemon reachable; fall back to static if not.

Phase 2: Per-Dockerfile Snapshot

For each Dockerfile, extract:

• FROM chain (stage names, base images, tags, digests)
• USER directives
• HEALTHCHECK
• ENTRYPOINT / CMD (exec form vs shell form)
• EXPOSE / ENV / ARG
• COPY patterns (source paths, --from references, --chown)
• RUN commands (shell-parsed)
• BuildKit-specific syntax (--mount=type=secret, --mount=type=cache)

In --live mode, additionally:

• Run docker history <image> for size-per-layer breakdown.
• Run trivy image <image> --severity HIGH,CRITICAL --quiet (or grype, snyk container) for CVE surface.
• Run docker inspect <image> for final USER, Entrypoint, and exposed ports.

Phase 3: Parallel Sub-Agent Audit

Spawn one Agent(subagent_type=Explore) per Dockerfile (single assistant message). Each walks categories A–H from reference.md §1:

• A. Base image — distroless/alpine/scratch where possible, pinned by digest, from a trusted registry
• B. User & privileges — explicit non-root USER before ENTRYPOINT, dropped capabilities, read-only FS hint
• C. Secrets & leaks — no secrets in ARG/ENV, no copied .env files, no hardcoded tokens, BuildKit secrets for build-time
• D. Layer efficiency — multi-stage build, COPY --from= for artefact, RUN combined with cleanup, layer cache-friendly order
• E. Signals & shutdown — tini/dumb-init for PID 1, STOPSIGNAL, exec-form CMD (JSON array, not shell)
• F. Healthcheck — HEALTHCHECK present, interval sensible, command meaningful (not just curl localhost)
• G. .dockerignore — excludes .git, node_modules, tests/, .env*, OS junk
• H. docker-compose — no privileged: true, no network_mode: host, named volumes, resource limits, no user: root

Phase 4: Merge & Risk Register

Merge sub-agent output. Dedupe via .container-ignore. Assign CT-001… IDs in severity-then-category order.

Phase 5: Remediation Drafting

For every CRITICAL/HIGH/MEDIUM finding, append a commented RUN/USER/HEALTHCHECK block to dockerfile-suggested.patch with the target file:line, evidence, and suggested fix.

Phase 6: Apply Mode (opt-in)

When --apply, iterate findings interactively with [a]pply / [s]kip / [A]ll / [q]uit. Edit Dockerfiles via Edit. Destructive changes (removing a FROM, ENTRYPOINT) need DESTROY confirmation.

Phase 7: Reporting

Write container-audit.md + container-audit.json + dockerfile-suggested.patch (and image-scan.json in --live mode with Trivy output).

---

Scoring

Category weights: A=15, B=20, C=20, D=10, E=5, F=10, G=10, H=10 (sum 100). See reference.md §3.

Total	Verdict
90–100	PASS
70–89	PASS WITH WARNINGS
50–69	CONDITIONAL
<50	FAIL

---

Important Principles

• Secrets at build time use BuildKit, not ARG. ARG TOKEN= is baked into the image history.
• USER must be set before the final CMD. Root at runtime is the default — flag every Dockerfile that doesn't explicitly switch.
• Multi-stage is the norm. Any Dockerfile that doesn't use multi-stage and ships a build toolchain is MEDIUM or HIGH depending on image size.
• Tag pins move. FROM node:20-alpine will drift. FROM node:20.11.1-alpine3.19@sha256:<digest> is pinned.
• latest in production is a finding. Always CRITICAL for production-tagged images.
• docker-compose privileged: true is always CRITICAL unless a suppression explains why (e.g., a CI runner).
• Australian English. DD/MM/YYYY. Markdown-first.

---

Edge Cases

1. No Dockerfile present. Report "no containers found" and exit cleanly.
2. Dockerfile is generated by a framework (next/standalone, nixpacks). Flag as "generated; framework-managed"; skip apply suggestions but audit the final output.
3. Multi-arch builds (buildx). Audit each stage independently; flag if arch-specific base images differ in patch level.
4. Windows-based images. Base-image checks differ — skip alpine/distroless suggestions, check servercore vs nanoserver.
5. distroless images without a shell. Healthcheck must use the image's exec format, not CMD-SHELL.
6. docker-compose with override files. Parse base + all overrides; findings target the file where the issue originates.
7. Compose uses secrets: top-level. Good — don't flag. Flag when secrets are inlined in env instead.