Dockerfile ARG is a build time variable used to pass values into the image construction process. When teams misuse it for secrets, those values can end up recorded in build output or image metadata. The safer pattern is to avoid placing credentials in ARG and inject them only when the container runs.
What Dockerfile ARG Does in a Build
dockerfile ARG defines a build-time variable that lets you parameterise image construction without hardcoding values into the Dockerfile. It is useful for version pins, feature flags, and repeatable builds, but it is not a runtime secret store.
Where ARG Fits in the Docker Build Lifecycle
ARG exists only during the build stage, so its values are available to build instructions that run while the image is being assembled. That makes it different from runtime environment variables, which are injected when a container starts and are better suited to operational configuration that should not be baked into the image.
The practical distinction matters because build-time inputs can influence layers, metadata, cache behaviour, and downstream image reproducibility. If a value is meant to remain private after the build, placing it in ARG creates unnecessary exposure.
Security Implications of Build Arguments
Build arguments become risky when teams treat them as a convenient place to pass credentials, tokens, or other secret material. Those values can leak into build logs, intermediate layers, cache traces, or image metadata depending on how the build is performed and what tooling captures.
Using ARG for non-secret configuration is normal, but using it for sensitive material breaks the boundary between build inputs and protected operational secrets. The safer pattern is to keep secrets out of the Dockerfile and inject them only through mechanisms designed for runtime or ephemeral use.
Good Uses and Common Misuses of ARG
ARG is best used for things that are acceptable to disclose as part of the build process, such as software version selectors, package mirrors, compilation options, or optional build features. It helps teams produce consistent images while still allowing controlled variation.
The common misuse is assuming that because a value is temporary, it is also private. Build-time does not mean hidden, and it does not mean unrecorded. If the value would be harmful if exposed after a build, it should not be passed through ARG.
Risk and Threat Considerations
Secrets passed through ARG can persist in places developers do not expect, especially when build logs are retained, cache layers are shared, or image inspection reveals historical metadata. That turns a convenience feature into a disclosure path.
Failure mechanism: The build system records or propagates the argument value in a way that survives beyond the immediate build step, creating an avoidable exposure path for credentials or tokens.
Impact: A leaked build secret can enable image tampering, repository access, registry compromise, or broader environment access if the secret is reused elsewhere.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 addresses the attack and risk surface, while NIST SP 800-53 Rev 5, CIS Controls v8 and SLSA set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | IA-5 — Authenticator Management | Build secrets require lifecycle control and rotation discipline. |
| CM-6 — Configuration Settings | Dockerfile build parameters are configuration inputs that must be controlled. | |
| Recommendation — Store build secrets outside ARG and rotate any exposed credentials promptly. Use controlled build parameters and avoid embedding sensitive values in Dockerfile arguments. | ||
| CIS Controls v8 | CIS-4 — Secure Configuration of Enterprise Assets and Software | Docker image build settings are software configuration that must not expose secrets. |
| Recommendation — Harden image build patterns so secrets are not placed in Dockerfile ARG values. | ||
| SLSA | Build provenance and integrity | Build inputs and provenance matter because ARG can affect image construction outputs. |
| Recommendation — Keep build inputs reproducible and prevent sensitive data from entering build provenance. | ||
| OWASP Non-Human Identity Top 10 | NHI-02 — Secret Leakage | Misused build arguments can leak secret material into build artifacts and metadata. |
| Recommendation — Keep secrets out of Dockerfile ARG and use secret handling that avoids artifact leakage. | ||
Practitioner Guidance
Common misunderstanding: Teams often use ARG for anything that feels temporary, but temporary is not the same as confidential. Treat build arguments as public build inputs unless the value is explicitly safe to expose.
Practitioner takeaway: Reserve ARG for non-sensitive build parameters and keep secrets out of the image construction path entirely.
Related resources from NHI Mgmt Group
- Why do Dockerfile secrets create lasting risk even after a secret is deleted from the final image?
- What do security teams get wrong about using ENV and ARG for credentials in container builds?
- What breaks when secrets are passed through Docker ARG or ENV instead of ephemeral secret mounts?
- What mistakes do teams make when they try to run MCP servers without a Dockerfile?
