Skip to content

CL-0020: Credential-shaped environment keys with literal values

Severity: HIGH (how it is derived)

A credential is written into the Compose file, under a key named like one, so anyone who can read the file has it, and the running container exposes it through its environment. Move it into a secrets: file and point the image at that file.

Fix

Move the credential to Compose's secrets: primitive. For images that support the *_FILE convention (Postgres, MySQL, MariaDB, Bitnami images, many others), this is a one-line change:

# Before
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: hunter2

# After
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt   # add to .gitignore
    # or external: true if managed via `docker secret create`

Creating the secret file

./secrets/db_password.txt is an ordinary file on the host, resolved relative to the Compose file's directory; nothing generates it for you. Compose bind-mounts it read-only at /run/secrets/<name>, byte for byte and with the host file's owner and mode. Create it with the value alone, no trailing newline, readable only by you, and out of git. For a database that already holds data, read Moving an existing database's password first: it needs the value it already has, not a new one.

mkdir -p secrets
openssl rand -base64 32 | tr -d '\n' > secrets/db_password.txt
chmod 600 secrets/db_password.txt
echo 'secrets/' >> .gitignore

Two consequences of the byte-for-byte, owner-and-mode mount, both observed against a live container (Docker 29.7.2, Docker Compose 5.5.0):

  • A trailing newline reaches the workload. Some entrypoints strip it: postgres:16 reads the file with shell command substitution, which drops trailing newlines, so a password file saved by an editor still works there. A program that reads the file directly gets the newline as part of the value. tr -d '\n' above, or printf '%s', avoids the question.
  • The process that reads it must be able to open it. A 0600 file owned by your host user is mounted 0600 and owned by that uid inside the container. Root reads it while it holds DAC_OVERRIDE, which a cap_drop: [ALL] service must add back (see CL-0006); a non-root user with any other uid gets Permission denied. The long-syntax uid:, gid: and mode: on a service's secret do not change this for a file-sourced secret: Compose ignores them, warning that they are not supported, they will be ignored (captured, not CI-asserted). Either give the host file the uid the container reads it as, or source the secret from an environment variable instead, which Compose mounts 0444, owned by root:
secrets:
  db_password:
    environment: DB_PASSWORD   # read from the shell running `docker compose up`

Moving an existing database's password

The postgres image reads POSTGRES_PASSWORD or POSTGRES_PASSWORD_FILE only when it initialises an empty data directory. On a database that already has data, the file changes nothing: recreated with a new value in the file, the database still accepts the old password and refuses the new one (observed on postgres:16, Docker 29.7.2). So put the password the database already has into the secret file; this is a move, not a rotation. An editor keeps the value out of your shell history, and postgres strips the newline the editor adds. Change the password later in the database and the file together.

Check it worked

# Recreate the service with the new configuration
docker compose up -d db

# The password should be gone from the container's environment
docker compose exec db sh -c 'test -z "${POSTGRES_PASSWORD-}" && echo "not in the environment"'
# not in the environment

# The secret should be mounted and non-empty; this does not print it
docker compose exec db test -s /run/secrets/db_password && echo "secret mounted"
# secret mounted

compose-lint -q compose.yaml | grep CL-0020    # prints nothing once fixed

Then connect the way your application does, from another container, to confirm the password works over the network.

Images without a *_FILE variable

Read the file in the service's command and export it just before the program starts:

services:
  app:
    image: myapp:1.0
    secrets:
      - api_token
    command:
      - sh
      - -c
      - export API_TOKEN="$$(cat /run/secrets/api_token)"; exec myapp

The doubled $ is Compose's escape: Compose ships a single $, so the container's shell runs the substitution at startup, and this rule does not flag it. It needs a shell in the image, and exec must start whatever the image normally runs. The credential is still in the workload's environment, but no longer in the Compose file or in the container's configuration that docker inspect returns.

Coming from an env_file:

The same fix applies, because the destination is the same: an env_file: value lands in the container's process environment exactly as an environment: value does. Three things are worth knowing on the way.

It is worth doing even when the file is already gitignored. The gain is not that the value leaves git — it may have left already — but that it leaves the process environment. A secret declared under secrets: is mounted at /run/secrets/<name> as a file, so it appears on none of the surfaces listed under Why it matters. An env_file: value appears on all of them.

Do not point secrets: file: at the env file itself. A file-sourced secret is mounted byte-for-byte, so an env-file-style source gives the workload the whole line — POSTGRES_PASSWORD=hunter2 and its trailing newline — as the password, rather than hunter2 (verified against a live container). The source file holds the value alone, nothing else:

# secrets/db_password.txt  -- the whole file, no key, no quotes
hunter2

If the file is your .env, split its two jobs. A .env supplies ${VAR} interpolation to the document; naming it in env_file: additionally pushes every key in it into the container. Those are different jobs and only the second one is graded here. Keep .env for interpolation, put container configuration in its own env_file:, and put credentials in secrets:.

A placeholder value is not exempt, and should not be: changeme in a committed env file is what every fresh clone deploys until someone remembers to change it. The fix is the same.

Coming from a command-line flag

The destination is the same secrets: entry; what changes is how the program is pointed at it. In order of preference:

  1. A file option, if the program has one. --password-file /run/secrets/pw, --rpcpasswordfile, -p "$$(cat …)" are all the file convention; the value never enters the argument list.
  2. Read it in the shell line. command: ["sh", "-c", "exec redis-server --requirepass \"$$(cat /run/secrets/redis_pw)\""]. The doubled $ is Compose's escape: it ships a single $ so the container's shell runs the substitution. A bare $( happens to pass through on Compose 5.5.0, but $$ is the documented escape, so do not rely on it.
  3. For a healthcheck, the same with CMD-SHELL: test: ["CMD-SHELL", "mysqladmin ping -p\"$$(cat /run/secrets/db_pw)\" || exit 1"].

Only the password reaches the process this way, not the whole line — the same trap as a secrets: file: pointing at an env file, described above.

Tested on: Docker 29.7.2 with Compose 5.5.0, on a host without AppArmor (Yama ptrace_scope 1); the Fix steps above were re-run there in October 2026. Not tested: an AppArmor or SELinux host; Swarm-mode secrets.

What it detects

Environment variable entries (both list form KEY=value and map form KEY: value) where the two conditions below hold. The same test is applied to the arguments a service passes in command:, entrypoint: and healthcheck.test — see In command:, entrypoint: and healthcheck.test.

An entry fires when:

  1. The key name matches a credential convention (case-insensitive substring or suffix match), AND
  2. The value ships a non-empty literal string — not a ${VAR} reference Compose resolves to nothing, and not a boolean/numeric flag.

Matched key patterns:

Match type Pattern Notes
substring PASSWORD, PASSPHRASE, TOKEN, SECRET, API_KEY, APIKEY, PRIVATE_KEY, ACCESS_KEY, SECRET_KEY, ENCRYPTION_KEY, CREDENTIAL case-insensitive
suffix _PASS, _PWD, PASSWD, _SALT, _DSN suffix-anchored to avoid noisy substring hits (raw PASS would match Passport.js naming)

Exemptions (key matches a credential pattern but the rule does not fire):

  • Keys ending in _FILE — this is the secrets-mount convention (POSTGRES_PASSWORD_FILE: /run/secrets/db_password), the fix, not the bug.
  • Keys containing ALLOW_EMPTY_ or RANDOM_ — image-startup boolean toggles (MYSQL_ALLOW_EMPTY_PASSWORD: "yes", MYSQL_RANDOM_ROOT_PASSWORD: "yes").
  • Values that are exactly yes, no, true, false, on, off, 0, or 1 (case-insensitive) — boolean flags.
  • Keys that name a quantity about the credential — a lifetime, size, limit or policy knob (lifetimes TTL, TIMEOUT, EXPIRE, EXPIRY, EXPIRATION, VALIDITY, LIFETIME, MAX_AGE/MAXAGE, ROTATION, INTERVAL, RETENTION, DURATION; time units _SECONDS/_SECS, _MINUTES/_MINS, _HOURS, _DAYS, _MS; sizes and policy knobs MIN_LENGTH/MINLENGTH, MAX_LENGTH/MAXLENGTH, MIN_CHAR/MINCHAR, _LENGTH, _SIZE, _LIMIT, POLICY, REQUIREMENTS, _BONUS, _STRENGTH, _HISTORY, _ATTEMPTS, _RETRIES, plural TOKENS; rate limits and counts LIMITER, MAX_, MAXCHAR; work factors ROUNDS, ITERATIONS, _COST; and _PORT) — and whose value is a bare quantity (30, 1.5, 900s, 30m). JWT_ACCESS_TOKEN_EXPIRE_MINUTES: 30 is a duration, not a token.

    Both halves are required. On the key alone, AUTH_TOKENS: your_token_here would be skipped; on the value alone, DB_PASSWORD: 12345678 would be — and a weak numeric password is exactly the finding. So PASSWORD_RESET_TOKEN_TTL: 900 is exempt while SECRET_KEY: 12345 fires.

    The same holds for a rate limit or count: LIMITER_GET_PASSWORDS: 2 is a request budget and ACCOUNT_MAX_PASSWORDS: 1000 a count. - URLs that locate a credential without holding one. A key ending _DSN, _URI, _URL or _ENDPOINT names where something is, so it is exempt when its value is a URL with no userinfo, no credential-named query parameter (password, token, api_key, key, sig and the like) and no fragment: MAILER_DSN: smtp://mailpit:1025 and OIDC_TOKEN_URI: http://dex:5556/dex/token are addresses. DATABASE_DSN: postgres://app:hunter2@db/app holds a password and fires, and so does SENTRY_DSN: https://abc@sentry.io/123, which keeps its key in the username slot. A file:// URL is exempt under any key: PASSPORT_PRIVATE_KEY: file:///srv/oauth-private.key names the file the secret is read from, the _FILE exemption spelled as a URL.

    A secret written into a URL's path under such a key (a webhook URL with the token as a path segment) is not reported; finding it means judging the value, which this rule does not do. - Empty values (PASSWORD: "" — env unset, not a credential). - Values Compose ships as empty — made only of references with no default (${DB_PASSWORD}, or "${DB_PASSWORD}" in a list-form entry, where the quotes are literal characters). The credential is parameterized and sourced from process env, the documented secure-ish pattern.

    Two shapes that look similar but are not skipped, because the file ships a literal either way: a value that merely contains a reference (hunter2$X ships hunter2 — one appended character used to silence this rule), and a defaulted reference (${DB_PASSWORD:-hunter2} ships hunter2, which is a hardcoded credential in every fresh clone). Compose's escaped literal dollar ($$) does not count as a reference either: DB_PASSWORD: "pa$$w0rd" is a literal credential containing $, so it fires.

This rule is a naming-convention check, not a content scanner. It does not inspect the value for entropy, length, or provider-specific formats. A value of changeme fires, a 40-character production credential under BILLING_ENDPOINT does not. For value-side detection of credentials in URL-shaped env vars, see CL-0021.

Where it looks

Both environment: and every env_file: a service names. Compose merges a named env file into the container's process environment, so a credential written there reaches the same surfaces this rule describes while never appearing in the document — the reason env_file: is graded at all (ADR-027).

A key set in both is reported once, against environment:, because that is the spelling Compose ships. A finding from an env file names the key and the file it was written in; the value is never printed, and the text formatter does not open a file that is not a Compose document. A target resolving outside the project directory is refused rather than read. When a target contributes nothing, the run says which one and why on stderr, without changing the exit code.

It also looks in every other container the file deploys (graded units). An init container that creates a bucket before a log store starts is a common place for a literal key, and a parent with no environment: of its own used to hide it:

services:
  logs:
    image: grafana/loki:3.5.0
    pre_start:
      - image: amazon/aws-cli:2.27.50
        environment:
          AWS_SECRET_ACCESS_KEY: example-not-a-secret   # reported on logs.pre_start[0]
        command: ["s3api", "create-bucket", "--bucket", "logs"]

The finding names the hook, logs.pre_start[0], and its line. The fix is the same as for a service: declare the value under secrets: and read it from the file. A post_start or pre_stop hook's environment: is graded too; it reaches only the command the hook runs, not the container's environment. A pre_start hook's env_file: is not read, because Compose does not apply it, and a job's is read like a service's.

In command:, entrypoint: and healthcheck.test

The same test is applied to the tokens of an argument list, because the list reaches the same metadata: docker inspect returns Config.Cmd, Config.Entrypoint and Config.Healthcheck beside Config.Env, and /proc/<pid>/cmdline is readable by every uid in the container where environ is readable only by the process's own. Three token shapes name a value:

Shape Example What is tested
a flag, inline or next token --admin-password=admin, --password hunter2, -rpcpassword=x the flag name, with - read as _, against the key patterns above
an assignment in a shell line sh -c "PGPASSWORD=hunter2 psql" the variable name, against the key patterns above
mysql's glued password mysqladmin ping -phunter2 only when one of the mysql-family binaries is in the list
  • Flag names the key list does not reach but that name a credential: REQUIREPASS and MASTERAUTH (redis-server --requirepass, by far the commonest shape in real files).
  • The glued -p is read only beside mysql, mysqladmin, mysqlcheck, mysqldump, mysqlsh, mysqlshow, mariadb, mariadb-admin, mariadb-check or mariadb-dump (by basename, so /usr/bin/mysqladmin counts). To every other program -p is a port, a prefix or a project, and mysql's own port flag is -P.

A string value is split as a shell line; a list is taken as written, except that the payload after sh -c or after CMD-SHELL is itself a shell line and is split again. A healthcheck: with disable: true is not read — Compose ships test: ["NONE"] whatever is written.

Every exemption above carries over (--password-file, --token-ttl 900, --require-password true, ${PW}), and two more apply only here, because a value means something different in an argument list than in environment::

  • $$ is a reference, not a literal. Under environment:, $$ is Compose's escaped literal dollar, so pa$$w0rd fires. In an argument list, Compose hands $$VAR to the container as $VAR, which the shell expands at runtime from the environment: redis-server --requirepass $$REDIS_PASSWORD ships no credential and is not flagged. Neither is the fix this page recommends, $$(cat /run/secrets/<name>).
  • A path is the fix pattern. --password-file /run/secrets/pw, or any value starting with /, ./, ../ or ~/, points at where the secret lives rather than being it — the _FILE exemption spelled as an argument.

One finding per name per location; a flag repeated on one line is one thing to move. A literal in environment: and the same literal in command: are two findings, because each needs moving. The value is never printed; the finding names the flag or variable and the location.

Why it matters

Compose's environment: block places credentials directly into the container's process environment, which propagates to several surfaces:

  • docker inspect <container> (and the underlying daemon API) returns the full env block to anyone with daemon access.
  • /proc/<pid>/environ is readable by any process running as the same UID inside the container, and by privileged processes outside it.
  • docker compose config prints the rendered env to stdout — frequently captured in CI logs and set -x traces.
  • Process listings via ps eww expose env to any user on the host that can see the process.
  • Container-runtime metadata is often shipped to log aggregators and APM tools by default.

A credential passed as an argument reaches the same metadata by a parallel route: docker inspect returns Config.Cmd, Config.Entrypoint and Config.Healthcheck beside Config.Env, and /proc/<pid>/cmdline is readable by every uid in the container, where environ is readable only by the process's own.

Any service with daemon access can read every other container's env and argument lists. Compose's secrets: primitive solves this by materializing credentials as files at /run/secrets/<name>, scoped to the container's filesystem and absent from env, daemon metadata, and process listings.

Placeholder values like changeme, admin, or postgres are intentionally flagged. Real-world incidents repeatedly involve placeholders shipped to production unchanged — the leak path and the fix are identical regardless of whether the value is a real credential.

ATT&CK coverage

Remediating this finding contributes to mitigating the following MITRE ATT&CK techniques (pinned to ATT&CK v18). compose-lint is a static analyser, so this is mitigation coverage — it detects nothing at runtime.

Technique Tactic
T1552.001 Unsecured Credentials: Credentials In Files Credential Access

See also

  • CL-0021 — credentials embedded in connection-string env values (different detection mode, same exposure surface, same fix).
  • CL-0010 — host PID/IPC namespace sharing (cross-container /proc/<pid>/environ exposure).
  • Hardening guide, step 1 — where this rule fits when hardening a whole file

Severity derivation

Derivation (see severity model):

  • Baseline: B — the attacker can read the compose file, or influence what the image reference resolves to; no code execution anywhere yet
  • Precondition: Direct — reading the file is the attack. The credential is present in plaintext; no technique and no second defect stand between the reader and it
  • Impact: Single container — the credential authenticates to the service it belongs to. A credential that also unlocks a neighbour is that neighbour's finding
  • Qualifier/modifier: none
  • Derived: Direct × Single container = HIGH
  • Shipped: HIGH
  • Evidence: Not runtime-observable, and it does not need to be: the compose file is the artifact, and the finding is the literal value it contains. Every finding names the key and the line where the value appears

References: - OWASP Docker Security Cheat Sheet — Rule #12: Utilize Docker Secrets for Sensitive Data Management - Compose secrets: top-level element

A reference means the rule relates to that source. It does not mean a file with no finding complies with it. The CIS, OWASP and ATT&CK mapping for every rule, and the tags SARIF output carries for it, are on Standards mapping.