ADR 0024: Read the password from a file¶
- Status: Accepted
- Date: 2026-11-12
Context¶
Since ADR 0018 the bot
reads every setting from its environment, and the password only from
there, through the password variable. That took the password out of the
host's process list, which every user of the host can read. Two places
still show it:
docker inspectprints the container's environment,passwordincluded, to anyone who can use Docker on the host. That access gives root on the host anyway, but the password also lands in whatever records the inspect output: a support paste, a monitoring agent, a backup of the container's configuration./proc/<pid>/environshows it to the process's own user and to root.
ADR 0018 named a secret file as the strongest option and left it for a
later step, because it needs a new setting and a new step for the
operator. Docker has a convention for this: Compose and swarm mount each
secret as a file under /run/secrets/, and many images read a variable
named after the secret with _FILE added.
The tradelocker client (0.56.2) keeps the password it is given for the
life of the process and logs in again with it when its token expires.
Whatever the source, the password is in the bot's memory while it runs.
Decision¶
A new setting, password_file, names a file that holds the password. It
is the other way to set the password, not a second one: exactly one of
password_file and password must be set.
flowchart TD
ENV["the container's environment"] --> BOTH{"password_file and password<br/>both set, neither empty?"}
BOTH -- yes --> STOP2["exit 2: set either password_file<br/>or the password environment variable, not both"]
BOTH -- no --> FILE{"password_file set?"}
FILE -- yes --> READ["read up to 1025 bytes of the file,<br/>once, before any output"]
READ --> CHECK{"readable, at most 1024 bytes,<br/>UTF-8, no byte order mark, no NUL,<br/>one non-empty line?"}
CHECK -- no --> STOP3["exit 2: password_file: the file ...<br/>(the content is never printed)"]
CHECK -- yes --> LOGIN["log in with the line,<br/>one trailing line ending dropped"]
FILE -- no --> VAR{"password set?"}
VAR -- yes --> LOGIN2["log in with the variable, as set"]
VAR -- no --> STOP1["exit 2: no password: set password_file to a file<br/>that holds it, or the password environment variable"]
- Exactly one source. When both are set, the bot stops with exit
status
2anderror: set either password_file or the password environment variable, not both. Neither wins: apasswordline left in an env file would otherwise decide, unseen, which password logs in. An empty value counts as not set, forpasswordas before and forpassword_filenow, so a Compose file that passes${PASSWORD_FILE}from a host that leaves it unset does not clash withpassword. - Neither set. The message now names both ways:
error: no password: set password_file to a file that holds it, or the password environment variable. The--passwordrefusal names both too:argument --password: set password_file or the password environment variable instead. - The file is read once, at startup, before any output, like every other setting. A file that cannot be read stops the bot as a bad setting does, before the greeting and the login.
- What the file must hold: one line.
- It is read as bytes and decoded as UTF-8 by the bot, so every system reads the same line endings.
- One trailing
\r\n,\nor\ris dropped, sinceechoand most editors end a file with one. Nothing else is trimmed, as nothing is trimmed from the variable (ADR 0018): spaces and shell characters reach the login as written. - A file that then still holds a line boundary is refused: any that
Python's
splitlinesknows, as for the webhook body, such as\n,\r,\x0b,\x0cor\u2028. An operator who pointspassword_fileat the env file would otherwise send every line of it to the broker as one password. - A file that holds a NUL character is refused. UTF-16 without a byte order mark decodes as UTF-8 with a NUL after each letter, and would fail the login as a wrong password.
- A file longer than 1024 bytes, the line ending included, is refused, after a read of 1025 bytes and no more, so a path that names a device or a large file is not read into memory.
- A file that is not UTF-8 is refused. Windows PowerShell 5.1 writes
>as UTF-16. - A file that starts with a byte order mark is refused rather than having it dropped: the last line ending is the only change the bot makes, so the password is always what an editor shows.
- An empty file, or one that holds only a line ending, is refused.
- No message carries the content. Each says what is wrong with the
file,
password_file: the file .... For a file that cannot be read the system's reason follows in brackets, such as(No such file or directory). The decoding error is never shown, because it quotes the bytes. password_fileis read from the environment only, likepassword.--password_fileis an unknown argument and is refused without being printed. One place to look for where the password comes from, and no rule to define for an option against the other source's variable.passwordstays. The frozen contract gainspassword_file; it loses nothing. Removingpasswordwould stop every deployment that sets it on its next pull, with--restart unless-stoppedrestarting it in a loop.
| Case | Before | After |
|---|---|---|
password set |
logs in with it | the same |
password_file set to a file holding p\n |
ignored; exit 2 without password |
logs in with p |
| both set | password_file ignored |
exit 2, not both |
| neither, or both empty | exit 2, the password environment variable is not set or is empty |
exit 2, no password: set password_file ... |
| a file that is missing, a directory, empty, longer than 1024 bytes, of two lines, with a NUL, not UTF-8, or with a byte order mark | exit 2, password_file: the file ..., content not printed |
|
--password_file on the command line |
unknown argument, not printed | the same |
What changes¶
composition_root.password_frompicks the source. A new adapter module,adapters/password_file.py, reads the file (read_password_file) and applies the rules to its bytes (password_from_bytes, no I/O). Each returns aResultwith the password or the message, andparse_argsturns anErrinto the argparse error and exit status2. An adapter module rather than a port: only the composition root asks for the password, so a port would have one implementation and no caller inside the layers. Update: the module is nowadapters/secret_file.py, withread_secret_fileandsecret_from_bytes, and each message names the setting, since the Telegram token file is read under the same rules (ADR 0027).-
Tests. A new
tests/characterization/test_startup_password_file.pypins:- the line reaching the login as written, with each line ending;
- an empty
password_fileorpasswordcounting as not set; - each refused file stopping the bot before any output, with a marker in the file that must not appear in the output;
- a missing file and a directory;
- both sources set;
--password_filerefused as unknown.
A unit test,
tests/unit/adapters/test_password_file.py, pins the bounded read against a file with no end.The missing-password pin, the
--passwordpin and the help text pin flip to the new messages. - Mutations. Each fails at least one test: - keeping the byte order mark; - stripping every trailing line ending; - stripping\nonly, or not a lone\r; - letting the file win over the variable; - keeping a file of several lines, or counting only\nand\ras line boundaries; - keeping a NUL character; - dropping the size check, or reading the file to its end; - showing the decoding error; - reading the file in text mode. - CI starts the built image with a file mounted read-only at/run/secrets/password, holdingp a $HOME *: the greeting is printed, and the image's own Python reads exactlyp a $HOME *from it. The file is written outside the build context, after the build, so no image can hold it. It also starts the image with apassword_filethat names no file, which must stop it with status2and(No such file or directory). The step without a password checks the new message. - The README's Quick start mounts the password as a file with--mount type=bind,...,readonly, not-v: for a source that does not exist,-v"automatically creates the directory on the host", while--mount"produces an error" (Bind mounts). A directory in place of the file would stop the bot with(Is a directory)and be in the operator's way. The Configuration table, Security section and Troubleshooting table coverpassword_file. ADR 0018, the roadmap's frozen contract anddocs/architecture.mdare updated.
What this does not cover¶
- The client writes the password to the log. Found in this step's CI
run: the
tradelockerclient (0.56.2) logs atdebugunless told otherwise, and writes each request it sends in full, the login's{'email': ..., 'password': ..., 'server': ...}included, to the container's output. Sodocker logsholds the password after every start, whichever source it came from. Not fixed here: it is a defect of its own, listed in the roadmap, with its own step and ADR. Update: fixed in step 6m, which runs the client atinfo(ADR 0025). - The password in memory. The client keeps it for the life of the process, so a memory dump of the bot still holds it.
- A changed password needs a restart. The file is read once, and the client logs in again with the password it was given.
- The file's permissions are not checked. Who can read the file on the host decides who can read the password, and the bot cannot see that from inside the container. The README tells the operator to make the host's file readable only by them.
- A pipe with no writer keeps the bot from starting, with nothing in the log: opening it waits for a writer. Not guarded: it is a path the operator chose. A device or a large file is refused after 1025 bytes.
- Images built before this change ignore
password_fileand stop with the old message whenpasswordis not set.
Consequences¶
- With
password_file,docker inspectshows only the path, and the password is in a file the operator controls, such as a Compose secret. - The
passwordvariable works as before, so no running deployment has to change. - Setting both is now an error, so an operator who moves to the file must
remove
passwordfrom the env file.
Alternatives considered¶
- Replace
passwordwithpassword_file. The roadmap first named the step that way. Not taken: it changes the frozen contract and stops every deployment on its next pull. It can follow as a step of its own once deployments have moved. - Prefer the file when both are set, as some images do. Rejected: a
forgotten
passwordline would be silently ignored or, after the file is removed, silently used; stopping names the conflict. - Strip all surrounding whitespace from the file's content. Rejected: a password may start or end with a space, and ADR 0018 keeps the variable as set.
- Accept
--password_fileas an option. The path is not secret, but the option would need a rule for when it meets thepasswordvariable. Not taken for now; running outside the image can set the variable. - Refuse a file readable by others. Not taken: the mode inside the
container is whatever the mount gives it, and a secret is mounted
"world-readable (mode
0444)" by default (Compose file reference, secrets), so the check would refuse the usual secret. It would also say nothing about who can read the host's copy.