11.1.3.3 Env Secret Avoidance

Env secret avoidance addresses why baking a sensitive value into an image through an ENV instruction is a particularly persistent and visible form of secret leakage, since the resulting value becomes part of the image's metadata, inspectable without even needing to run the container at all.

Why ENV-Embedded Secrets Are Especially Easy to Discover

An environment variable set through ENV becomes part of the image's configuration, visible directly through inspection without requiring the image to even be run.

ENV API_KEY=secret123

docker inspect myapp:1.0 --format '{{json .Config.Env}}'

This command reveals the embedded value directly, without needing to start a container at all — among the most easily discoverable forms of leaked secret.

Why This Differs From a Secret Provided at Runtime

A secret correctly supplied at runtime, rather than baked into the image, exists only in a specific running container's actual environment, not as part of the distributable image itself.

docker run -d -e API_KEY=secret123 myapp:1.0

This runtime-supplied value never becomes part of the image's own configuration, unlike the ENV instruction's persistent embedding.

Using a Build Argument Doesn't Solve This Either

Passing a sensitive value through a build argument and then setting it via ENV still results in the same persistent exposure, since the resulting ENV value is baked in regardless of how it was originally supplied.

ARG API_KEY
ENV API_KEY=$API_KEY

This pattern still embeds the secret into the image's configuration just as directly as hardcoding it would.

The Correct Approach: Supplying Secrets Only at Runtime

A genuinely sensitive value should be supplied when the container is actually run, or through a dedicated secrets mechanism, never baked into the image's own ENV configuration.

services:
  api:
    secrets:
      - api_key

Why Env Secret Avoidance Matters

Recognizing that ENV-embedded values are directly and easily inspectable without even running the container reinforces why genuinely sensitive configuration should always be supplied at runtime, never baked into an image's persistent configuration through this particular instruction.