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:16reads 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, orprintf '%s', avoids the question. - The process that reads it must be able to open it. A
0600file owned by your host user is mounted0600and owned by that uid inside the container. Root reads it while it holdsDAC_OVERRIDE, which acap_drop: [ALL]service must add back (see CL-0006); a non-root user with any other uid getsPermission denied. The long-syntaxuid:,gid:andmode:on a service's secret do not change this for a file-sourced secret: Compose ignores them, warning that theyare 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 mounts0444, 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:
- 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. - 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. - 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:
- The key name matches a credential convention (case-insensitive substring or suffix match), AND
- 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_orRANDOM_— 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, or1(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 knobsMIN_LENGTH/MINLENGTH,MAX_LENGTH/MAXLENGTH,MIN_CHAR/MINCHAR,_LENGTH,_SIZE,_LIMIT,POLICY,REQUIREMENTS,_BONUS,_STRENGTH,_HISTORY,_ATTEMPTS,_RETRIES, pluralTOKENS; rate limits and countsLIMITER,MAX_,MAXCHAR; work factorsROUNDS,ITERATIONS,_COST; and_PORT) — and whose value is a bare quantity (30,1.5,900s,30m).JWT_ACCESS_TOKEN_EXPIRE_MINUTES: 30is a duration, not a token.Both halves are required. On the key alone,
AUTH_TOKENS: your_token_herewould be skipped; on the value alone,DB_PASSWORD: 12345678would be — and a weak numeric password is exactly the finding. SoPASSWORD_RESET_TOKEN_TTL: 900is exempt whileSECRET_KEY: 12345fires.The same holds for a rate limit or count:
LIMITER_GET_PASSWORDS: 2is a request budget andACCOUNT_MAX_PASSWORDS: 1000a count. - URLs that locate a credential without holding one. A key ending_DSN,_URI,_URLor_ENDPOINTnames 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,sigand the like) and no fragment:MAILER_DSN: smtp://mailpit:1025andOIDC_TOKEN_URI: http://dex:5556/dex/tokenare addresses.DATABASE_DSN: postgres://app:hunter2@db/appholds a password and fires, and so doesSENTRY_DSN: https://abc@sentry.io/123, which keeps its key in the username slot. Afile://URL is exempt under any key:PASSPORT_PRIVATE_KEY: file:///srv/oauth-private.keynames the file the secret is read from, the_FILEexemption 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$Xshipshunter2— one appended character used to silence this rule), and a defaulted reference (${DB_PASSWORD:-hunter2}shipshunter2, 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:
REQUIREPASSandMASTERAUTH(redis-server --requirepass, by far the commonest shape in real files). - The glued
-pis read only besidemysql,mysqladmin,mysqlcheck,mysqldump,mysqlsh,mysqlshow,mariadb,mariadb-admin,mariadb-checkormariadb-dump(by basename, so/usr/bin/mysqladmincounts). To every other program-pis 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. Underenvironment:,$$is Compose's escaped literal dollar, sopa$$w0rdfires. In an argument list, Compose hands$$VARto the container as$VAR, which the shell expands at runtime from the environment:redis-server --requirepass $$REDIS_PASSWORDships 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_FILEexemption 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>/environis readable by any process running as the same UID inside the container, and by privileged processes outside it.docker compose configprints the rendered env to stdout — frequently captured in CI logs andset -xtraces.- Process listings via
ps ewwexpose 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>/environexposure). - 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.