no-add-remote

Why ADD with a URL in a Dockerfile is a bad idea, and the curl/wget pattern to download files into an image instead.

On this page

ADD https://… downloads a file straight into an image layer. It looks convenient, but the download is unverified, never cache-busted correctly, and — unlike ADD with a local archive — a remote archive is not auto-extracted, so the compressed file itself lands in the layer. This rule flags every ADD whose source is a remote URL, unless the instruction sets --checksum.

What the rule catches

Dockerfile — unverified remote ADD

FROM debian:12-slim
ADD https://example.com/tool.tar.gz /tmp/tool.tar.gz
RUN tar -xzf /tmp/tool.tar.gz -C /usr/local/bin && rm /tmp/tool.tar.gz

Scanning this file reports:

⚠ WARN [docker-doctor/no-add-remote]
  ADD instruction uses a remote URL 'https://example.com/tool.tar.gz'. Remote files added via ADD cannot be cleaned up in later layers, increasing image size.

Why it matters

Three separate problems stack up. Integrity: without --checksum, nothing verifies the download, so you're trusting the remote server and the network path at every build. Size: the downloaded file is committed to its own layer; even if a later instruction deletes it, the bytes stay in the image history. Caching: Docker cannot tell whether the remote content changed, leading to stale-or-rebuilt-forever cache behavior. A RUN curl line fixes all three in one move.

How to fix it

Add --checksum=sha256:<digest> so BuildKit verifies the download, or use RUN curl or RUN wget and delete the downloaded archive in the same layer to minimize size.

Dockerfile — download, verify, extract, and clean in one layer

FROM debian:12-slim
RUN curl -fsSL https://example.com/tool.tar.gz -o /tmp/tool.tar.gz \
  && echo "d3adb33f…  /tmp/tool.tar.gz" | sha256sum -c - \
  && tar -xzf /tmp/tool.tar.gz -C /usr/local/bin \
  && rm /tmp/tool.tar.gz

Because the download, checksum verification, extraction, and cleanup happen inside a single RUN, the archive never survives into any layer — the image only contains the extracted tool. The rm in the bad example above does not achieve this: it removes the file in a later layer while the ADD layer still carries the full archive.

ADD --checksum=sha256:<digest> <url> <dest> is the other fix. BuildKit verifies the download, and the rule doesn't report it. The file still gets its own layer, so use this form for files you keep, such as a single binary. Keep RUN curl for archives you extract and delete.

Rule details

Rule key — docker-doctor/no-add-remote
Category — Security
Default severity — warning
Applies to — Dockerfiles

Explain this rule from the CLI:

npx @docker-doctor/cli@latest rules explain docker-doctor/no-add-remote

Change its severity — or turn it off — in your config file:

// docker-doctor.config.ts
export default {
  rules: {
    "docker-doctor/no-add-remote": "off",
  },
};

Severity affects the health score: error findings cost more points than warning, and info costs the least.