What breaks when secrets are passed through Docker ARG or ENV instead of ephemeral secret mounts?

Secrets can spill into build logs, shared runners, cached layers, and published images. Once that happens, later file deletion does not remove earlier layer data. This breaks least privilege, complicates incident response, and leaves organisations with credentials that may still be retrievable even after the original source file has been corrected.

Why This Matters for Security Teams

Passing secrets through Docker build-time and runtime paths that persist in logs or layers turns a temporary build dependency into a durable exposure problem. OWASP Non-Human Identity Top 10 is especially relevant here because build systems, CI runners, and deployment workflows often handle credentials as machine identities, not as disposable values. The practical risk is not just disclosure, but also trust contamination: once a secret is embedded in a layer, cache, or image history, it can outlive the pipeline run that used it.

Security teams often underestimate how quickly a single Dockerfile pattern can become an organisation-wide secret handling weakness. Docker Build Secrets guidance exists precisely because ARG and ENV were never meant to provide secret isolation. ARG values can surface in image metadata and build output, while ENV values are deliberately carried into the final image context. That means anyone with access to the artifact, registry, or cache may recover material that should have been ephemeral. In practice, many security teams encounter secret leakage only after a compromised image, a shared runner inspection, or an unexpected registry pull has already exposed it, rather than through intentional control testing.

How It Works in Practice

Docker Dockerfile instructions behave differently depending on whether the value is used for build selection or runtime configuration. ARG is available during image build, but it can still be captured in build output, cache metadata, and layer provenance. ENV persists into the resulting image and may be visible to containers, scanners, and anyone inspecting the image configuration. By contrast, ephemeral secret mounts keep the secret outside the image filesystem and make it available only to the specific build step that needs it.

Operationally, the difference is whether the secret becomes part of the artifact lifecycle. With ARG or ENV, the secret can be copied into a layer, echoed by a command, written into a temporary file, or preserved by caching. With secret mounts, the build step can authenticate to a package registry, fetch a private dependency, or sign an artifact without baking the credential into the output. That is why current guidance suggests using ephemeral secret delivery for anything that is credential-like, especially API keys, tokens, certificates, and signing material.

• Use secret mounts for private package installs, dependency retrieval, and signing steps.
• Keep ARG for non-sensitive build parameters such as version labels or feature flags.
• Avoid ENV for secrets that must not appear in image configuration or container inspection.
• Scan image history, layer metadata, and CI logs as part of secret exposure verification.

Build systems also need guardrails outside the Dockerfile itself. CI/CD policy should block patterns that interpolate secrets into shell commands, bake them into base images, or reuse cached layers across trust boundaries. Teams should pair this with secret rotation, registry access review, and artifact provenance checks. CISA secure-by-design guidance is useful here because it pushes teams to remove exposure at design time instead of relying on after-the-fact detection. These controls tend to break down when shared runners reuse caches across projects because the same secret-bearing layer can be inherited by unrelated builds.

Common Variations and Edge Cases

Tighter secret handling often increases pipeline complexity, requiring organisations to balance build simplicity against leakage resistance. There is no universal standard for every build environment yet, especially where legacy Docker workflows, air-gapped registries, or custom builders make secret mounts harder to adopt.

Some teams argue that short-lived secrets reduce the impact of ARG or ENV exposure. That is partly true, but it does not eliminate the core issue: a short-lived credential can still be harvested from an image, cache, or log long after the intended use. The risk is amplified when builds are distributed, when artefacts are mirrored across environments, or when developers use the same Dockerfile in both local and production pipelines. For highly regulated environments, provenance and retention matter as much as the credential lifetime itself.

One important exception is non-secret configuration that looks sensitive but is not actually a credential. Build flags, public endpoints, and release identifiers can usually remain in ARG or ENV without creating the same exposure class. The practical rule is to treat anything that can authenticate, authorise, sign, or decrypt as a secret, and keep it out of persistent layers. Where the boundary is unclear, current guidance suggests classifying the value as secret and proving that it does not persist in the final image or cache. That distinction becomes critical when the same pipeline handles NHI credentials for automated deployment or signing workflows.

Related resources from NHI Mgmt Group

• What is the difference between Docker Secrets and BuildKit secret mounts?
• What breaks when secrets are passed through an LLM context?
• What breaks when secrets are passed through notebooks and Spark configuration?
• What breaks when access to servers and databases is managed through broad network reach instead of roles?