The worst incident on my record was not a crash. A build step needed a token for a private npm registry, so someone passed it as a build argument. The image went to a registry with broad read access, and months later a routine audit found the token sitting in the image metadata, valid the whole time. This lesson is about what’s inside your images, the parts you didn’t write and the parts you didn’t mean to include.
\nEvery package in your image, from Debian’s libssl to npm’s express, has a public history of vulnerabilities (CVEs). A scanner reads the image’s package inventory and matches it against those databases. Docker Scout is built into the Docker CLI:
docker scout quickview notes-api:1.4.0\ndocker scout cves --only-severity critical,high notes-api:1.4.0\ndocker scout recommendations notes-api:1.4.0quickview gives a one-screen summary: vulnerability counts for your image, for its base image, and for a newer version of that base if one exists. cves lists each finding with the package, the installed version and the version that fixes it. recommendations suggests base image tags with fewer known vulnerabilities. Trivy and Grype are popular open-source scanners that do the same job; pick one and use it everywhere.
A long list of findings is not a to-do list. Work through it like this:
\npackage.json, run npm ci, rebuild.Then make it a gate so regressions can’t sneak in:
\ndocker scout cves --only-severity critical,high --exit-code notes-api:1.4.0With --exit-code, the command fails when it finds vulnerabilities at those severities, so your CI job fails before the push. While you’re in CI, ask the builder for supply-chain metadata too: docker buildx build --sbom=true --provenance=mode=max … attaches a software bill of materials and build provenance to the image, which makes the next audit a lookup instead of an investigation.
Images remember more than you’d think. Three common leaks:
\nENV API_KEY=… is stored in the image config and set in every container. docker image inspect shows it.ARG NPM_TOKEN used in a RUN step is recorded in the image’s build history. docker history --no-trunc can reveal it.COPY .npmrc then RUN rm .npmrc) still exists in the earlier layer. Anyone with the image can extract that layer.Docker’s build checks warn about the first two (SecretsUsedInArgOrEnv) when the variable name looks like a secret. Take the warning seriously.
The right tool is a secret mount: the secret is made available to a single RUN step as a file (or an environment variable) and never written to a layer. notes-api’s build needs a token for a private package, so:
FROM node:24-slim AS build\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN --mount=type=secret,id=npmrc,target=/root/.npmrc \\\n --mount=type=cache,target=/root/.npm \\\n npm cidocker build --secret id=npmrc,src=$HOME/.npmrc -t notes-api:1.4.0 .During that RUN, npm finds its config at /root/.npmrc. Before and after, the file doesn’t exist, and nothing about it is stored in the image or the build cache. Without a target, secrets are mounted at /run/secrets/<id>. If a tool reads a token from an environment variable instead, mount it as one with RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN npm ci and pass --secret id=npm_token,env=NPM_TOKEN on the command line, which reads the value from your shell’s own NPM_TOKEN.
The database password notes-api uses in production has no business in the image at all. It arrives when the container starts: from an environment variable in Compose, from a Kubernetes Secret, or from your cloud’s secret manager. You’ll wire up both of the first two in the next sections. The image stays identical across environments; only the injected configuration changes.
\nSection 2 is done: your image is lean, unprivileged, traceable and clean. Next you’ll give it a database to talk to, with Docker Compose.
\n","toc":[{"id":"sec-1","text":"Scan before you ship","level":2},{"id":"sec-2","text":"Triage in a sensible order","level":2},{"id":"sec-3","text":"How secrets leak into images","level":2},{"id":"sec-4","text":"BuildKit secret mounts","level":2},{"id":"sec-5","text":"Runtime secrets are not the image’s job","level":2}],"takeaways":["docker scout cves lists known CVEs per package; --only-severity critical,high --exit-code turns it into a CI gate.","Fix base-image findings first by updating or switching the base; docker scout recommendations suggests candidates.","Anything passed with ARG or ENV, or written to a file in a RUN step, is recoverable from the image, even if a later step deletes it.","RUN --mount=type=secret exposes a secret to one build step without writing it into any layer.","Runtime secrets such as database passwords are injected when the container starts, never built into the image."],"further":[{"title":"Docker Scout quickstart","url":"https://docs.docker.com/scout/quickstart/"},{"title":"Build secrets","url":"https://docs.docker.com/build/building/secrets/"},{"title":"docker scout cves","url":"https://docs.docker.com/reference/cli/docker/scout/cves/"}],"quiz":[{"q":"A scan of notes-api:1.4.0 reports 30 CVEs, 27 of them in Debian packages from the base image. What’s the most effective first step?
apt-get upgrade in the runtime stage.","why":"It makes builds unpredictable and still leaves you maintaining the OS by hand. Fix the base image itself."},{"text":"Ignore it until a customer asks.","why":"Known, fixable CVEs in shipped images are exactly what attackers scan for."}],"answer":1},{"q":"This build step needs an npm token. What’s wrong with it?
\nARG NPM_TOKEN\nRUN echo \"//npm.pkg.github.com/:_authToken=${NPM_TOKEN}\" > .npmrc \\\n && npm ci && rm .npmrc.npmrc file is deleted in the same step, so the token never persists.","why":"The file is gone, but build arguments are recorded in the image’s build history, so the token is still recoverable."},{"text":"ARG values can’t be used inside RUN.","why":"They can; that’s what makes this pattern tempting."},{"text":"The token must be passed with ENV instead of ARG.","why":"ENV is worse: it’s stored in the image config and set in every running container."},{"text":"The token is recorded with the build arguments and can be read from the image’s history; use a secret mount instead.","why":"Correct. Docker’s own docs warn that ARG and ENV are not for secrets. A secret mount exists only during that one step."}],"answer":3},{"q":"What does this line give the npm ci step? RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
/root/.npmrc containing the secret, visible only during this step and absent from the layer.","why":"Correct. The mount appears for the command and disappears afterwards; nothing about its content is stored in the image."},{"text":"An environment variable named npmrc set for every later step.","why":"This form mounts a file at target. Secret mounts never carry over to later steps."},{"text":"A copy of .npmrc baked into the image under /root.","why":"That’s what COPY would do. A secret mount is never written into a layer."},{"text":"Nothing, unless the image also runs as root.","why":"The mount works for whichever user runs the step; the target path here just matches root’s home directory."}],"answer":0},{"q":"Where should notes-api’s production database password come from?
","options":[{"text":"A.env file copied into the image during the build.","why":"That bakes the password into every copy of the image, in every registry and cache it reaches."},{"text":"A build argument, so each environment’s image gets its own password.","why":"Build arguments are recorded in image history, and per-environment images break “test what you ship”."},{"text":"Injected at run time, for example from a Kubernetes Secret or Compose secret, never stored in the image.","why":"Correct. The same image runs everywhere; each environment supplies its own credentials when the container starts."},{"text":"Hard-coded in dist/config.js and protected by running as non-root.","why":"A non-root user can still read its own code, and so can anyone who pulls the image."}],"answer":2}],"exercise":{"kind":"spot-bug","language":"dockerfile","code":"# syntax=docker/dockerfile:1\nFROM node:24-slim\nARG NPM_TOKEN\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN echo \"//npm.pkg.github.com/:_authToken=${NPM_TOKEN}\" > .npmrc\nRUN npm ci --omit=dev\nRUN rm .npmrc\nCOPY dist ./dist\nUSER node\nCMD [\"node\", \"dist/server.js\"]","bugLines":[3,6],"title":"Where the token leaks","prompt":"This image for an internal tool installs packages from a private registry. The author believes deleting .npmrc on line 8 keeps the token safe. Select the two lines that put the token into the image where anyone who pulls it can recover it.
Line 3 passes the token as a build argument, which is recorded in the image’s build history. Line 6 writes it into .npmrc in its own layer; line 8’s rm only hides the file in a later layer, so extracting the line-6 layer reveals it. Use a secret mount, which exists only for the one step that needs it:
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \\\n npm ci --omit=devdocker build --secret id=npmrc,src=$HOME/.npmrc -t tool:1.0.0 .Then rotate the token, because every copy of the old image still contains it.
\n","checkLabels":{}},"words":788,"readMinutes":4}