Dockerfile Security Basics Checker

Introduction:

Container image security starts earlier than the image scan. A Dockerfile decides which operating system and language runtime enter the build, which files are copied, which commands run during image creation, and which user starts the final process. A short file can still carry release risk when it pulls a moving base tag, copies the whole repository, stores a token in a build variable, or leaves the application running as root.

Static Dockerfile review is valuable because many weak defaults are visible before anyone builds or pushes an image. The review is not trying to prove that every package is safe. It asks whether the build recipe follows basic hardening habits: controlled base images, narrow build context, verified downloads, least-privilege runtime users, predictable commands, and a runtime contract that is clear enough for deployment systems to monitor.

Several Dockerfile terms matter for security decisions. A FROM line starts a build stage and names the base image. A multi-stage Dockerfile may compile in one stage and copy only selected artifacts into the final stage. ARG and ENV can make builds configurable, but secret-like names or values can leak into image history or metadata. ADD and COPY both bring content into the build, while ADD has extra remote-fetch and archive behavior that deserves closer review.

Common mistakes usually come from treating containers as a packaging detail instead of a supply-chain boundary. A developer may choose latest for convenience, paste an installer command from a vendor page, or copy the entire project because it builds locally. Those choices can make later rebuilds hard to reproduce and can pull private files, credentials, or unnecessary tools into an image that will run in production.

A clean Dockerfile review is still only a starting point. It cannot confirm that a registry image is patched today, inspect the finished filesystem, verify signatures, test the service, or replace a runtime policy such as Kubernetes security context controls. Use Dockerfile security basics to catch visible recipe problems early, then pair the result with image scanning, provenance checks, CI builds, and deployment controls.

How to Use This Tool:

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

1. Enter an Image or service label, such as registry.example.com/orders-api:2.8.0. The label should appear in Policy Snapshot so exports can be tied back to the right pull request or build target.
2. Choose Policy profile. Use Runtime service for application images, CI builder image for build-only images, and Strict release gate when release inputs should also pressure base-image digest pins.
3. Paste the Dockerfile into Dockerfile source, browse for a Dockerfile-like text file, drop a file on the textarea, or load one of the samples. The source status line should show line and character counts. A selected file larger than 2 MB is rejected before review.
4. If Review Dockerfile input appears, fix the input first. Empty text and text with no FROM instruction create critical findings because stages, final user, base image posture, and healthcheck status cannot be anchored.
5. Open Advanced only when the default review needs adjustment. Add approved hosts in Trusted registries, raise or lower Finding row limit, turn on Force digest pin check, or hide low and info reminders with Include low signals.
6. Start with Policy Snapshot. Check Risk decision, Risk score, Visible findings, Instructions parsed, Final runtime user, and Runtime healthcheck.
7. Use Finding Ledger for line-level evidence, Remediation Plan for control-family next actions, Instruction Ledger for parsing context, and Dockerfile Risk Mix Chart when you need to see which risk families dominate the result. A useful handoff has no critical or high rows in the ledger, a non-root Final runtime user for runtime service images, and a Risk decision that matches the release gate you selected.

Interpreting Results:

The first high-impact row matters more than the size of the score. A missing final USER, a weak base tag, a secret-like build variable, world-writable permissions, or an installer script piped to a shell should usually be fixed before release or covered by a narrow, time-limited exception.

Baseline clear means the current Dockerfile text and settings did not match the static basics rules. It does not mean the built image has no vulnerabilities, that the base image digest is trusted, or that the container will run correctly under your orchestrator.

Line numbers are review aids. A multi-line instruction is analyzed as one instruction, so a finding on the first line of a continued RUN command may refer to content later in that same command.

Use the chart to spot clusters, not to replace the ledger. For example, several low package-hygiene rows may be less urgent than one high secret finding, but a cluster can still show where a Dockerfile needs cleanup before it becomes a repeated pattern across services.

Technical Details:

Dockerfile review begins with instruction structure. Blank lines and comments are ignored, continued lines ending in a backslash are joined, and each parsed instruction keeps the line where it started. Every FROM begins a stage. The last stage is treated as the final runtime stage for checks such as final USER, WORKDIR, CMD, ENTRYPOINT, and HEALTHCHECK.

The rule set is static and text-based. It does not execute build commands, pull images, query registries, inspect package databases, or read a finished image filesystem. That boundary keeps the review fast and predictable, but it also means a clean result must be followed by build-time and runtime security checks.

Rule Core

The baseline groups findings by control family. Each row below summarizes the visible security idea rather than every internal pattern.

Formula Core

The risk score is the sum of weighted visible findings. Low and info rows count only when Include low signals is on. The visible finding set is sorted by severity weight and line number, then the table is clipped by Finding row limit. The JSON output includes both the visible findings and the full normalized finding list.

Profile Effects

Policy profile changes a small set of expectations. It does not change the parsed Dockerfile text, but it changes how healthchecks, digest pins, and some package hygiene rows are judged.

Deduplication happens by finding type, line, and evidence text so repeated pattern matches on the same instruction do not inflate the result. Findings that remain are still rule signals, not proof of exploitability. The safest interpretation is to treat them as review prompts tied to visible Dockerfile text.

Responsible Use Note:

Dockerfiles can reveal registry hosts, private repository names, build arguments, package sources, internal ports, and service labels. They can also contain accidental credentials. Paste the smallest useful Dockerfile text when reviewing sensitive projects.

The review runs in the browser session and does not build the image. Pasted text and selected files are read locally by the page, but copied tables, chart images, downloaded files, and JSON output can still contain sensitive details from the Dockerfile and findings.

Do not treat the result as a penetration test, vulnerability scan, or compliance approval. It is a static basics check that should feed a broader container security workflow.

Advanced Tips:

• Use Strict release gate for Dockerfiles that feed production images, signed images, or deployment approvals. It adds digest-pin pressure even when the base tag is otherwise specific.
• Keep Include low signals on during cleanup work so package-cache reminders, shell-form command notes, and missing healthchecks are visible before they spread across service templates.
• Use Trusted registries as a review assumption, not as a blanket approval. Add only registries your team already allows for base images, then document exceptions in the pull request or release ticket.
• Raise Finding row limit before exporting a noisy legacy Dockerfile. A low row limit can make the table easier to read, but the full visible ledger is better for remediation planning.
• Compare Dockerfile Risk Mix Chart with Remediation Plan. The chart shows where findings cluster, while the remediation rows show which control families need release-blocking fixes first.

Worked Examples:

Risky application image

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, Policy Snapshot reports Risk decision as Needs hardening, Risk score as 104, Visible findings as 12 shown of 12, and Final runtime user as not set. The first high rows point to the 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. That result is a good static baseline, but the image should still be built, scanned, and tested.

Strict release gate without digest pins

The same clean sample changes when Policy profile is set to Strict release gate or Force digest pin check is on. The node:20-bookworm-slim tags are specific enough to avoid the weak-tag warning, but each FROM line lacks an @sha256 digest. Policy Snapshot moves to Review, and Finding Ledger adds medium Base image rows asking for release-grade digest pins.

Snippet with no base image

A snippet such as RUN echo hello cannot be reviewed as a complete Dockerfile. The alert shows Review Dockerfile input, and Policy Snapshot reports Risk decision as Blocked because no FROM instruction exists. Add the intended base image first, then read the stage count, instruction ledger, final user, and healthcheck results again.

FAQ:

Glossary:

Base image

The image named by FROM that starts a Dockerfile stage.

Build context

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

Digest pin

An @sha256 reference that binds a base image line to one exact image digest.

Final stage

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

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 signal and argument handling.

Trusted registry

A registry host that the review settings treat as approved for base-image provenance reminders.

References:

• Building best practices, Docker Docs.
• Dockerfile reference, Docker Docs.
• SecretsUsedInArgOrEnv, Docker Docs.
• Build secrets, Docker Docs.
• Docker Security Cheat Sheet, OWASP Cheat Sheet Series.
• How to build a multi-stage Docker image, Simplified Guide.