RUN Instruction

What a RUN instruction does in a Docker build

A RUN instruction executes during image build, not when the container starts. That makes it part of the image’s construction history, so any packages installed, scripts executed, or files modified by the command become baked into a layer that will be reused by later builds and shipped to runtime.

This matters because a RUN step is not just a convenience for automation. It is a trust boundary inside the build process: the command can introduce code, secrets, packages, and configuration changes that alter the final image’s behavior and exposure.

Why RUN affects image content and attack surface

Each RUN instruction creates a new layer. In practice, that means build-time choices can leave behind tools, caches, package managers, compiler artifacts, shell history, or temporary files unless they are cleaned up in the same layer. The final image may therefore contain more software and data than the running application actually needs.

Because the command is evaluated by the build environment, RUN also inherits whatever network access, package sources, and build context are available at build time. If a command pulls content from the internet, installs dependencies, or executes scripts from the repository, those dependencies become part of the supply chain for the image.

Build-time command content and trust boundaries

The risk is not limited to what the command installs. The exact command string can determine whether the build is deterministic, whether it depends on mutable external state, and whether it introduces unreviewed behavior into the image. A seemingly minor change to a RUN line can add packages, modify permissions, fetch remote scripts, or expand the set of binaries available in production.

For that reason, RUN instructions should be treated as controlled build actions, not as harmless plumbing. They are often where software delivery security, dependency hygiene, and image hardening either succeed or fail.

Safer ways to reason about RUN in Dockerfiles

Good Dockerfile design keeps RUN steps narrow, explicit, and auditable. Prefer commands that do one thing, avoid fetching opaque remote scripts, and remove temporary build artifacts in the same layer when possible. When a build step only exists to prepare the image, check whether it can be moved into a dedicated build stage so the runtime image stays smaller and cleaner.

It is also worth reviewing every RUN instruction for hidden assumptions: package sources, shell behavior, environment variables, and whether the command depends on mutable state outside the repository. A RUN line that looks routine can still be the point where the image picks up extra attack surface.

Risk and Threat Considerations

RUN instructions are a common place for build-chain compromise, dependency injection, and accidental secret exposure because they execute code while the image is being assembled. If a build step downloads content, runs scripts, or installs packages from untrusted or overly broad sources, a malicious or tampered dependency can be baked directly into the image.

Failure mechanism: A RUN command can execute unreviewed shell logic, persist unwanted software in a layer, or copy sensitive material into the image through the build context or intermediate files.

Impact: The resulting image may carry hidden backdoors, unnecessary tooling, leaked credentials, or a larger vulnerable surface that is then deployed repeatedly across environments.

Practitioner Guidance

Why practitioners should care: Treat RUN instructions as part of your software supply chain, because they are one of the main places where build-time decisions become runtime exposure. Review them with the same discipline you would apply to any other trusted execution path in delivery.

What to watch for: Be cautious when a RUN line fetches remote content, chains many shell commands together, or leaves package managers, caches, or temporary files in the final layer. Those patterns often indicate avoidable image bloat or hidden trust dependencies.

Practitioner takeaway: A clean Docker image usually comes from small, explicit RUN steps that do only what the final artifact truly needs.

Related resources from NHI Mgmt Group

• How should security teams run access reviews for non-human identities?
• When do user access reviews become too risky to run manually?
• How should security teams govern LLMs that can call tools or run code?
• How should security teams govern autonomous agents that run inside containers?