CL-0021: Credentials embedded in connection-string values¶
Severity: HIGH (how it is derived)
A connection string in the Compose file carries a literal password in its
user:password@ part, so anyone who can read the file has it, whatever the
variable is called. Keep the password in a secrets: file and build the URL,
or hand the client the password, from that file at startup.
Fix¶
Three patterns, in order of preference. Options 1 and 2 were checked against
a live postgres:16 server (Docker 29.7.2), connecting from a second
container, with a wrong and a missing password both refused.
1. Move the credential to secrets: and reassemble the URL at startup (best)¶
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets:
- db_password
app:
image: myapp:1.0
secrets:
- db_password
command:
- sh
- -c
- >-
export DATABASE_URL="postgresql://postgres:$$(cat /run/secrets/db_password)@db/postgres";
exec myapp
secrets:
db_password:
file: ./secrets/db_password.txt # add to .gitignore
The doubled $ is Compose's escape: Compose ships a single $, so the
container's shell reads the file when the service starts. The command needs a
shell in the image, and exec must start whatever the image normally runs.
Create the file as CL-0020 describes,
but with a hex password. A password inside a URL cannot contain /, ?, #
or @ unencoded, and base64 output can contain /:
mkdir -p secrets
openssl rand -hex 32 | tr -d '\n' > secrets/db_password.txt
chmod 600 secrets/db_password.txt
echo 'secrets/' >> .gitignore
With a / in the password, the URL's host part ends early: psql read
postgres:ab/cd…@db as host postgres and port ab, and failed with
psql: error: invalid integer value "ab" for connection option "port"
(captured on Docker 29.7.2, not CI-asserted). asyncpg, which does not use
libpq, misreads it the same way (invalid literal for int() with base 10:
'ab'). Node's pg fails harder: it throws TypeError: Invalid URL, and the
error it prints carries the whole URL, password included, so the password
ends up in the service's logs (pg 8.23.1, asyncpg 0.32.0, captured, not
CI-asserted).
2. Keep the password out of the URL with a password file (libpq clients)¶
Clients built on libpq, such as psql and psycopg, read the password from the
file PGPASSFILE names when the URL carries none. So do two that are not:
asyncpg, and Node's pg, whose support is deprecated and goes away in pg
9.0 (it asks for a password callback instead). Both also refuse a group- or
world-readable file with a warning (pg prints libpq's wording; asyncpg's
names the path as PosixPath(...)):
services:
app:
image: myapp:1.0
environment:
DATABASE_URL: postgresql://postgres@db/postgres # no password
PGPASSFILE: /run/secrets/pgpass
secrets:
- pgpass
secrets:
pgpass:
file: ./secrets/pgpass
The file uses libpq's host:port:database:user:password format, one line per
server, with * matching anything. Build it from the password file created
in option 1:
printf 'db:5432:*:postgres:%s\n' "$(cat secrets/db_password.txt)" > secrets/pgpass
chmod 600 secrets/pgpass
Keep it 0600. libpq ignores a password file that group or others can read,
and then connects with no password at all:
WARNING: password file "/run/secrets/pgpass" has group or world access; permissions should be u=rw (0600) or less
psql: error: connection to server at "db" (…), port 5432 failed: fe_sendauth: no password supplied
(Captured on Docker 29.7.2, not CI-asserted.)
That rules out an environment:-sourced secret here, which Compose mounts
0444. A 0600 file keeps its host owner inside the container, so a client
running as another non-root uid cannot open it
(CL-0020 covers both).
3. Substitute the password from process env (interim improvement)¶
services:
app:
environment:
DATABASE_URL: postgresql://app:${DB_PASSWORD}@db/app
This pulls the credential out of the document. Compose resolves ${DB_PASSWORD} from the sibling .env or the operator's shell, and compose-lint deliberately does not resolve a .env value into environment: (ADR-026 §2) — so following this advice does not trip the rule that gave it.
One condition: the file supplying DB_PASSWORD must not also be named in an env_file: for this service. env_file: .env merges every key in that file into the container's process environment, so the credential lands back where it started and CL-0020 reports it — correctly (ADR-027). Keep .env for interpolation or name it in env_file: for container config; doing both undoes this fix.
Less secure than option 1 in any case — the credential still ends up in container env — but a meaningful improvement over a literal value, and a one-line change.
Options 1 and 2 apply unchanged when the connection string was written in an env_file: rather than in environment:; see CL-0020's migration notes for the two traps on that path.
Check it worked¶
compose-lint -q compose.yaml | grep CL-0021 # prints nothing once fixed
Then start the service and confirm it connects. When the password does not
arrive, a libpq client reports fe_sendauth: no password supplied; when the
wrong one does, password authentication failed (both captured on Docker
29.7.2, not CI-asserted).
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. Non-libpq clients were checked too: pg 8.23.1 and asyncpg 0.32.0 read a 0600 password file and ignore a 0644 one, as libpq does. Not tested: other non-libpq clients (JDBC, Go's pgx).
What it detects¶
Environment variable values that contain a literal scheme://user:password@host userinfo segment, regardless of the key name.
services:
app:
environment:
DATABASE_URL: postgresql://postgres:hunter2@db:5432/app # fires
MONGO_URL: mongodb://root:example@mongo:27017/ # fires
AIRFLOW__DATABASE__SQL_ALCHEMY_CONN: postgresql+psycopg2://airflow:airflow@postgres/airflow # fires
Detection matches any URI scheme ([a-zA-Z][a-zA-Z0-9+.\-]*) followed by ://, then splits the user:password@ that follows at the first : and @ that sit outside a ${...} substitution — a plain split lands inside one, so postgresql://${DB_USER:?error}:${DB_PASSWORD:?error}@db/x would be read as a password of ?error}:${DB_PASSWORD:?error} and reported as a literal even though the file ships no credential. A match requires the password half to ship a non-empty literal — that is, it is not made up solely of ${VAR}/$VAR references Compose resolves to nothing (Compose's escaped literal dollar, $$, is data, not a substitution — pa$$w0rd fires). The username half may be empty: RFC 3986 §3.2.1 permits it, and redis://:password@host — the standard Redis URL form — still leaks the password, so it fires.
Skipped:
- Password half is made only of
${VAR}/$VARreferences with no default — Compose ships nothing there, so the credential is parameterized. (A$-valued username with a literal password still fires: the password leaks regardless. A password whose only dollars are$$escapes also fires — that is a literal$in the credential, not a substitution. A defaulted password such as${DB_PASSWORD:-hunter2}fires too: the default is what the file deploys.) - Both halves are references with no default (
postgresql://${DB_USER:?error}:${DB_PASSWORD:?error}@db/x) — the same rule as above, once the split respects the substitution. - Userinfo password is empty (
scheme://user:@host) — no credential to leak. - No userinfo at all (
scheme://host/path) — nothing to flag. - Empty or non-string value.
This rule is key-name-agnostic and value-shaped, the inverse of CL-0020. They are independent and may both fire on the same service when both surfaces apply (e.g., a separate DB_PASSWORD: hunter2 and a DATABASE_URL: postgres://app:hunter2@db/app).
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.
Why it matters¶
The exposure surface is identical to CL-0020 — env vars propagate through docker inspect, /proc/<pid>/environ, docker compose config, process listings, and CI logs. Embedding the credential in a URL doesn't add or remove any leak path, it just hides the credential from key-pattern scanning.
This is the largest detection gap that key-pattern rules miss in real-world Compose files. In a corpus of 1554 real docker-compose.yml files, 151 contained a literal user:password@ segment in an environment: value — none of which would have been caught by credential-shaped key matching alone.
RFC 3986 §3.2.1 deprecates passing passwords in URI userinfo regardless of Docker context: "Use of the format 'user:password' in the userinfo field is deprecated." This rule covers the Compose-specific exposure on top of the general URI hygiene concern.
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-0020 — credential-shaped env keys with literal values (key-side detection of the same exposure surface).
- 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 password sits in the userinfo segment of a connection string in plaintext
- Impact: Single container — the credential authenticates to the service the connection string addresses
- 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. See CL-0020 — the two rules differ in matcher, not in risk
References:
- OWASP Docker Security Cheat Sheet — Rule #12: Utilize Docker Secrets for Sensitive Data Management
- Compose secrets: top-level element
- RFC 3986 §3.2.1 — userinfo deprecation for passwords
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.