Dockerfile ADD Instruction

What the ADD instruction actually does

The Dockerfile ADD instruction is more than a simple copy operation. It can place local files or directories into an image, but it can also change build behaviour by unpacking archives and, in some cases, retrieving remote content. That extra convenience is useful, but it also means the instruction can alter what enters the build context and what ends up inside the image.

Because of that expanded behaviour, ADD should be understood as a build-time content transformation step, not just a file move. The practical difference is that the image may include material that was not present as a plain source file copy, which changes how teams reason about determinism, provenance, and reviewability.

Why ADD is different from COPY

In day-to-day container authoring, COPY is the predictable choice when you want to transfer local files into an image without side effects. ADD adds convenience, but the trade-off is that the same line can mean several different things depending on the source and how the instruction is interpreted.

That makes ADD harder to review at a glance. A reader must know whether the source is a local path, an archive, or a remote location, and whether the build will expand content or simply place it in the image. In security-sensitive pipelines, that ambiguity is often the reason teams standardise on COPY unless the extra behaviour is genuinely required.

How ADD changes build inputs and image contents

The main security concern is not that ADD is inherently unsafe, but that it can broaden the set of inputs a build depends on. If a Docker build can fetch remote content, the effective supply chain extends beyond the local source tree. If it can unpack archives, the resulting image contents may differ from what a reviewer sees in the original artifact.

That matters for reproducibility and inspection. A small change in source location, archive contents, or remote availability can produce a materially different image. In regulated or tightly controlled environments, teams often want every input to be explicit, versioned, and reviewable before it is promoted into a build.

Where ADD fits in supply chain control

ADD belongs in the broader software supply chain discussion because it can influence provenance, traceability, and image integrity. When build steps implicitly transform or retrieve content, it becomes harder to prove exactly what was consumed during the build and harder to confirm that the final image reflects only approved inputs.

Build systems are strongest when each source is intentionally chosen and each transformation is easy to explain. For that reason, many secure build practices treat ADD as an exception rather than a default, especially when the same outcome can be achieved more transparently with COPY and explicit unpacking or retrieval steps.

Review and control points for maintainable Dockerfiles

The best review question is simple: does this ADD line provide behaviour that a plain copy cannot? If not, the instruction usually adds complexity without adding value. If yes, the reason should be obvious in the Dockerfile and the source being introduced should be something the team is prepared to trust, track, and validate.

A secure review also looks for hidden build dependencies, especially where remote retrieval or archive expansion could mask what actually enters the image. The goal is not to ban convenience, but to preserve clarity, determinism, and ownership over the build inputs that shape the resulting container.

Risk and Threat Considerations

Using ADD expands the attack surface of a Docker build because it can introduce implicit fetch and unpack behaviour. That creates room for build-time surprises, source tampering, and weaker provenance, especially when teams assume the instruction behaves like a straightforward copy.

Failure mechanism: A build consumes remote or archive-based input that is not reviewed with the same rigour as local source, allowing unexpected content to enter the image or an attacker-controlled dependency to influence the build result.

Impact: The resulting container image may contain untrusted code or altered assets, and downstream release, deployment, and incident response decisions can be based on a build artifact whose provenance is harder to prove.

Practitioner Guidance

Why practitioners should care: Treat ADD as an exception path, not the default file-transfer mechanism. When teams reserve it for the cases where its extra behaviour is genuinely needed, reviews become clearer and build inputs are easier to reason about.

Common misunderstanding: Many engineers read ADD as a harmless shorthand for copying files. In practice, the instruction can change image contents in ways that deserve explicit scrutiny, especially when archives or remote sources are involved.

Practitioner takeaway: Prefer the simplest instruction that expresses the build intent clearly, and use ADD only when its additional behaviour is both necessary and understood.

Related resources from NHI Mgmt Group

• When does gamified cloud security training add more value than passive instruction?
• When should organisations add continuous controls for AI agents?
• When does an independent control layer add more value than native controls?
• When should organisations add risk signals to cryptographic authorization flows?