# DOCKER-SEC-005: Secret in Build Argument

> **Severity:** CRITICAL | **CWE:** CWE-538

- **Language:** Docker
- **Category:** Security
- **URL:** https://codepathfinder.dev/registry/docker/security/DOCKER-SEC-005
- **Detection:** `pathfinder scan --ruleset docker/DOCKER-SEC-005 --project .`

## Description

This rule detects ARG instructions with names that suggest they contain sensitive
information such as passwords, API keys, tokens, or credentials. Build arguments are
permanently stored in the Docker image metadata and can be retrieved by anyone with
access to the image using 'docker history', making them unsuitable for secrets.

## Vulnerable Code

```python
FROM python:3.11-slim

# CRITICAL VULNERABILITY: Secret in build arg
ARG API_KEY
ARG DATABASE_PASSWORD
ARG GITHUB_TOKEN
ARG AWS_SECRET_ACCESS_KEY

# These secrets are now permanently in the image!
RUN pip install --index-url=https://user:${GITHUB_TOKEN}@github.com/ my-private-package
RUN echo "DB_PASS=${DATABASE_PASSWORD}" > /app/config.ini
```

## Detection Rule (Python SDK)

```python
from codepathfinder.container_decorators import dockerfile_rule
from codepathfinder.container_matchers import instruction


@dockerfile_rule(
    id="DOCKER-SEC-005",
    name="Secret in Build Argument",
    severity="CRITICAL",
    cwe="CWE-538",
    category="security",
    tags="docker,dockerfile,secrets,credentials,security,arg,build-arg,password,token,api-key,sensitive-data,information-disclosure",
    message="Build argument name suggests it contains a secret. ARG values are visible in image history via 'docker history'."
)
def secret_in_build_arg():
    """
    Detects ARG instructions with names suggesting secrets.

    Build arguments are stored in the image layer history and can be
    retrieved by anyone with access to the image. Never pass secrets
    as build arguments.
    """
    return instruction(
        type="ARG",
        arg_name_regex=r"(?i)^.*(password|passwd|secret|token|key|apikey|api_key|auth|credential|cred|private|access_token|client_secret).*$"
    )
```

## How to Fix

- Use Docker BuildKit secret mounts instead of ARG for secrets
- Store secrets in environment variables at runtime, not at build time
- Add sensitive files to .dockerignore to prevent accidental inclusion

## Security Implications

- **Persistent in Image Layers:** ARG values are baked into the image metadata and remain accessible even if the layer is deleted or the secret is "removed" later
- **Visible in Image History:** Anyone with access to the image can run 'docker history' or 'docker inspect' to retrieve all build arguments
- **Supply Chain Exposure:** Images pushed to registries expose these secrets to anyone who pulls the image
- **No Encryption:** Build args are stored in plaintext within the image metadata
- **CI/CD Leakage:** Build logs often echo ARG values, exposing them in CI/CD systems Real-world attack scenario:
- Developer passes database password as build arg: --build-arg DB_PASSWORD=secret123
- Image is pushed to Docker Hub or private registry
- Attacker pulls image and runs: docker history image:tag --no-trunc
- Attacker extracts DB_PASSWORD from build history
- Attacker uses credentials to access production database

## FAQ

**Q: How do secrets leak from Docker build arguments?**

ARG values are stored in the image layer history. Anyone with access to the image can run docker history to see all build arguments including secrets.

**Q: What is the secure alternative to ARG for secrets?**

Use BuildKit secret mounts: RUN --mount=type=secret,id=mysecret cat /run/secrets/mysecret. The secret is available during build but never stored in a layer.

**Q: How do I check if my image contains leaked secrets?**

Run docker history --no-trunc <image> to inspect all layers. Tools like trufflehog and gitleaks can also scan container images for exposed credentials.

## References

- [CWE-538: Insertion of Sensitive Information into Externally-Accessible File](https://cwe.mitre.org/data/definitions/538.html)
- [Docker BuildKit Secret Mounts](https://docs.docker.com/build/building/secrets/)
- [OWASP Docker Security Cheat Sheet](https://owasp.org/www-project-top-ten/)
- [NIST SP 800-190: Application Container Security Guide](https://csrc.nist.gov/publications)

---

Source: https://codepathfinder.dev/registry/docker/security/DOCKER-SEC-005
Code Pathfinder — Open source, type-aware SAST with cross-file dataflow analysis