Dockerfile Security Basics Checker

Introduction:

Dockerfile security basics are the small build choices that decide whether a container image starts from a controlled base, avoids baking secrets into image history, and runs with only the privileges it needs. These choices matter before a release because a Dockerfile can look short and harmless while still pulling a moving base tag, copying too much build context, installing packages loosely, or leaving the final process as root.

A static Dockerfile review is useful because many early risks are visible before the image is built. A reviewer can check whether the final stage sets USER, whether ARG or ENV names look secret-like, whether remote downloads are verified, and whether CMD or ENTRYPOINT uses shell form. Those findings do not prove exploitation, but they do point to image hardening work that is cheaper to fix before the build pipeline and deployment policy depend on the image.

The practical boundary is important. Dockerfile linting cannot scan packages inside a finished image, prove that a base image is patched today, validate a runtime Kubernetes policy, or decide whether an exception is justified for a special build stage. It is a preflight review for source text. Treat a clean result as one part of a container security review, then pair it with image scanning, signed provenance, runtime testing, and the release policy your team actually enforces.

The strongest use is a fast pull-request check on one Dockerfile at a time. If the review finds a high-impact issue, fix the Dockerfile or document a narrow exception before copying the result into a release handoff.

Technical Details:

A Dockerfile is parsed as ordered instructions. Multi-line commands joined with a trailing backslash are normalized into one instruction, comments and blank lines are skipped, and every parsed instruction keeps its starting line number. Each FROM begins a stage. The final stage is treated as the runtime stage for checks such as final USER, WORKDIR, CMD, ENTRYPOINT, and HEALTHCHECK.

The review is rule-based. It does not execute commands, pull base images, read a registry, inspect an image filesystem, or verify that a package manager actually installs the requested versions. It looks for text patterns that commonly weaken Dockerfile hardening, then assigns a severity, control family, evidence line, and remediation note.

Rule Core

The first set of rules focuses on base-image control, privilege boundaries, secret handling, build context, package hygiene, supply-chain downloads, and runtime surface. The table summarizes the shipped checks in user-facing terms.

Risk score is a visible-finding sum. Low and info rows are included only when the Include low signals switch is on. The visible row set is sorted by severity weight and line number, then clipped by Finding row limit for the table view. The JSON result keeps both the visible list and the full normalized finding list.

Policy profile changes only a few expectations. Runtime service expects a non-root final image and a healthcheck. CI builder image skips the healthcheck expectation. Strict release gate also expects digest-pinned base images and treats some package-hygiene reminders more strongly.

Everyday Use & Decision Guide:

Name the image, service, repository, or build target in Image or service label before sharing results. The label does not change the checks, but it keeps copied rows and JSON tied to the build being reviewed.

Choose Policy profile before reading the score. Runtime service is a sensible first pass for application images because it expects a non-root final stage and a healthcheck. CI builder image is better for images that exist only to compile, test, or package code. Strict release gate raises digest-pin pressure for teams that need reproducible release inputs.

• Paste one Dockerfile into Dockerfile source, browse for a Dockerfile or text file, or drop the file onto the textarea. Files larger than 2 MB are rejected in the status line.
• Use Trusted registries to name registry hosts your team already accepts for base images. Docker Hub shorthand counts as docker.io.
• Use Finding row limit when the ledger is too long for a review screenshot. Raise it when a handoff needs every visible row.
• Turn on Force digest pin check when a runtime or CI image also needs release-style base-image reproducibility.
• Leave Include low signals on for a full basics audit. Turn it off only when the handoff needs critical, high, and medium findings first.

The summary is the fastest triage cue. It reports Dockerfile Security Baseline, the risk number, visible finding count, high-impact count, parsed stage count, instruction count, and final user badge. After that, use Policy Snapshot for the release decision, Finding Ledger for line-level evidence, Remediation Plan for family-level next actions, and Instruction Ledger when you need to understand how a line was classified.

A clean static result does not mean the built image is secure. It means the checked Dockerfile text did not match the implemented basics rules under the current profile. Follow a Baseline clear result with an actual build, image vulnerability scan, runtime test, and any required provenance or signing check.

Step-by-Step Guide:

Review one Dockerfile at a time so the risk score, line numbers, chart, and remediation rows describe the same build input.

1. Enter Image or service label, such as registry.example.com/orders-api:2.8.0, and confirm that the same label appears in Policy Snapshot.
2. Select Policy profile. Watch the summary wording change between runtime, CI builder, and strict release expectations.
3. Paste, browse, drop, or load a sample in Dockerfile source. The source status should show line and character counts before you use the result.
4. If Review Dockerfile input appears, fix the listed issue first. Empty input and a Dockerfile with no FROM produce critical errors because the checker cannot anchor a build stage.
5. Open Advanced only when the defaults need adjustment. Add registry hosts to Trusted registries, change Finding row limit, or apply Force digest pin check for a stricter review.
6. Read Policy Snapshot. Check Risk decision, Risk score, Visible findings, Instructions parsed, Final runtime user, and Runtime healthcheck.
7. Move to Finding Ledger and address rows in severity order. Use the Line, Evidence, and Remediation columns to update the Dockerfile or write a narrow waiver.
8. Use Remediation Plan to group work by control family, then check Dockerfile Risk Mix Chart to see whether the remaining rows cluster around base images, secrets, packages, or runtime surface.
9. Open JSON after the tables match the intended review. It includes the profile, risk decision, severity counts, final user, healthcheck status, visible findings, all findings, and instruction ledger.

A solid handoff has no critical or high rows in Finding Ledger, a non-root Final runtime user when the image runs a service, and a Risk decision that matches the release gate you selected.

Interpreting Results:

The first actionable row in Finding Ledger matters more than the size of the risk score. A Needs hardening result usually points to a high finding that should be fixed before release, such as a final stage without USER, a secret-like ARG, a latest base tag, or an installer script piped directly to a shell.

Baseline clear means no visible findings matched the static rules. It does not confirm that the base image is patched, that installed packages are safe, that the runtime process can start, or that the image will pass a vulnerability scanner. Use the result as evidence for one review pass, not as an approval stamp.

Line numbers are review aids, not absolute proof that the nearby text is the only cause. Multi-line Dockerfile instructions are collapsed for analysis, so a finding on the first line of a continued command may refer to content later in the same instruction.

Worked Examples:

Risky service sample

The risky sample starts from node:latest, sets ARG API_TOKEN=demo, uses ADD . /app, installs packages without the checked cleanup pattern, pipes a remote installer to bash, exposes port 22, and uses shell-form CMD npm start. Under Runtime service, the summary shows 104 risk, 12 visible finding(s), 4 high-impact, and 1 stage(s). Finding Ledger points first to the high rows: weak base tag, missing final user, secret-like build variable, and remote script execution.

Clean runtime sample

The clean sample uses two node:20-bookworm-slim stages, copies dependency and source files with narrower paths, sets USER node, declares a bounded HEALTHCHECK, and uses JSON exec form for CMD. Under Runtime service, Policy Snapshot reports Risk decision as Baseline clear, Risk score as 0, Final runtime user as node, and Runtime healthcheck as present.

Strict release without digest pins

The clean runtime sample changes when the review moves to Strict release gate or when Force digest pin check is on. The base tags stay specific enough to avoid the floating-tag warning, but each FROM lacks an @sha256 digest. The summary moves to Review, and Finding Ledger adds medium Base image rows asking for digest-pinned release references.

Text pasted before the first FROM

A snippet that contains only RUN echo hello cannot be reviewed as a complete Dockerfile. The alert shows Review Dockerfile input, Policy Snapshot cannot report a real stage count, and the risk decision becomes Blocked because no FROM instruction was found. Add the intended base image first, then rerun the review.

Responsible Use Note:

Dockerfiles can reveal registry hosts, private repository names, service labels, build arguments, package sources, internal ports, and hints about credentials. Paste the smallest useful text for review when working with sensitive projects, and treat copied rows, chart images, and JSON output as security evidence.

The check runs in the browser session and does not build the image. Pasted text and selected files are read locally by the page, but the resulting exports can still contain the same sensitive Dockerfile content and finding details.

FAQ:

Glossary:

Base image

The image named by FROM that starts a Dockerfile stage.

Digest pin

An @sha256 reference that binds a base image to one exact image digest for reproducible builds.

Final stage

The last stage in a multi-stage Dockerfile, treated here as the runtime stage for user, command, workdir, and healthcheck review.

Build context

The files available to Docker during build, often copied with COPY or ADD.

Secret mount

A BuildKit mechanism that exposes a secret during a build step without storing it in the final image metadata.

Shell form

A CMD or ENTRYPOINT written as a string instead of a JSON array, which can affect signals and arguments.

References:

• Building best practices, Docker Docs.
• Dockerfile reference, Docker Docs.
• Build secrets, Docker Docs.
• SecretsUsedInArgOrEnv, Docker Docs.
• Checking your build configuration, Docker Docs.