containers-audit

Imported from kosif199022-jpg/kosif-atlas (skills/237-best-practices/765-containers-audit/SKILL.md). Install upstream with npx skills add kosif199022-jpg/kosif-atlas --skill 765-containers-audit. Copyright stays with the author.

Containers audit

Walk every container-related file under the target path against the containers-best-practices skill's rule set, present a prioritized findings list, and offer each fix interactively. Audit target: $ARGUMENTS — when none is given, the current directory.

This skill is read-mostly: read files and search the tree freely, edit a file only after explicit per-finding approval, and never delete or move files or run docker commands during the audit. If the target path is outside the current repository, refuse and ask the user to change into it first — that keeps the blast radius bounded.

Step 1 — Discover

Search the target path for container files:

• **/Dockerfile
• **/*.dockerfile
• **/.devcontainer/devcontainer.json
• **/.devcontainer/**/devcontainer.json
• **/devcontainer.json
• **/compose.yml, **/compose.yaml
• **/docker-compose.yml, **/docker-compose.yaml
• **/compose.override.yml, **/compose.override.yaml
• **/docker-compose.override.yml, **/docker-compose.override.yaml

Also check for:

• .dockerignore at the repo root and next to each Dockerfile — both existence (SEC-001) and coverage (SEC-015, against the baseline in the rule).
• .gitignore at the repo root — needed for SEC-019.
• Any .env, .env.* (excluding .env.example / .env.template) at the repo root — flag for SEC-012, SEC-019.
• .git/ directory presence — confirms .dockerignore needs SEC-013 coverage.

Print a short summary of what was found, grouped by type. If nothing was found, exit cleanly with a one-line message — do not proceed.

Step 2 — Load the rule set

Read the containers-best-practices skill so its rule index is in context — it ships in this same module at ../containers-best-practices/SKILL.md. Then read the relevant reference file for each type of file you discovered:

• Any Dockerfile → ../containers-best-practices/references/dockerfile.md
• Any devcontainer.json → ../containers-best-practices/references/devcontainer.md
• Any compose file → ../containers-best-practices/references/compose.md
• Always → ../containers-best-practices/references/security-build.md (covers .dockerignore, BuildKit, scanning)

Also load:

• ../containers-best-practices/references/uv-python.md whenever the repo shows Python+uv signals: pyproject.toml with [tool.uv], uv.lock present, COPY --from=ghcr.io/astral-sh/uv in the Dockerfile, or any uv sync invocation. The uv rules cross-cut the Dockerfile and security categories.
• ../containers-best-practices/references/buildx.md when the repo has a docker-bake.hcl, a CI config using docker/build-push-action or docker buildx, or a Dockerfile with RUN --mount=type=cache (cache backend choice becomes relevant).

Read only the rules relevant to what you found — don't load all files if only a Dockerfile is present.

Step 3 — Analyze each file

For every discovered file, walk it line-by-line against the relevant rules. Record each violation as a finding:

{
  severity: "high" | "medium" | "low",
  rule_id:  "DOCKER-005",
  file:     "path/to/Dockerfile",
  line:     42,            // best-effort; omit if not applicable
  problem:  "Runs as root in final stage",
  fix:      "Add a non-root USER directive after the final COPY step"
}

Severity mapping

If a rule's applicability is genuinely ambiguous (e.g. you can't tell whether the entrypoint is long-lived), record it as needs-judgment instead of fabricating a severity — list it separately at the end. A Docker socket mounted into a dev container (DEVC-025) is always needs-judgment: ask whether host-root access from inside the container is an accepted, documented risk. So are a production runtime on a full general-purpose base (SEC-023) and a host running untrusted workloads without rootless mode or userns-remap (SEC-024) — neither is decidable from the file alone.

Step 4 — Present findings

Print a single consolidated report:

Found N findings across M files:

  high:   X
  medium: Y
  low:    Z
  needs-judgment: W

By file:
  path/Dockerfile (3 findings)
    [high]   DOCKER-005 — line 18 — Runs as root in final stage
    [med]    DOCKER-002 — line 1  — Base image pinned by tag, not digest
    [low]    DOCKER-012 — line 1  — No WORKDIR set
  .devcontainer/devcontainer.json (1 finding)
    [med]    DEVC-002 — postCreateCommand runs apt install (move to image)

Step 5 — Interactive fix loop

Walk the findings in severity order (high → medium → low). For each one, ask the user — with the harness's structured question tool when it has one, otherwise a numbered prompt (Reply with 1=apply, 2=skip, 3=diff, 4=skip-file, 5=stop) answered on the next turn:

• Apply this fix — perform the edit and confirm what changed.
• Skip this finding — leave it; move on.
• Show me the diff first — print the proposed old and new text, then ask again.
• Skip rest of this file — move to the next file's findings.
• Stop auditing — abort the loop and jump to the summary.

Never apply a fix without explicit per-finding approval. This skill never autofixes.

For each fix:

1. Re-read the file (state may have changed since the initial scan).
2. Construct the minimal edit to address the rule. If the fix is non-trivial (e.g. restructuring into multi-stage), describe the change in words and ask the user to confirm before editing.
3. After editing, briefly state what was applied and which rule ID it resolved.

Step 6 — Summary

When done, print:

Audit complete.

Applied:  A fixes
Skipped:  S findings
Deferred: D findings (needs-judgment — manual review recommended)

Next steps:
  - <one-line nudge per remaining high-severity finding>
  - Consider running the containers audit again after manual changes.

If .dockerignore was missing and the user approved creating it, list the patterns that were added so they can review.