Why Your CLI Should Read Secrets from a File Descriptor, Not argv
Run mytool --password hunter2 and the password is now in a world-readable place. Any local user can see it with ps, and the kernel will keep showing it until the process exits. The flag is convenient to write, and that is about the only thing in its favour.
Here is how to see the problem, why the usual workarounds are weaker than they look, and what a better interface is.
argv is public by default
Every process's command line lives in /proc/PID/cmdline, and on a stock Linux system that file is readable by everyone. Try it:
sh -c 'sleep 60' _ --password hunter2 &
tr '\0' ' ' </proc/$!/cmdline; echo
You will see the whole line, secret included. Another user running ps aux sees the same thing. The arguments are separated by NUL bytes, hence the tr.
There are more leaks beyond ps:
- Shell history, if you typed it at a prompt.
- Process accounting and audit logs that record executed command lines.
- Monitoring agents and crash reporters that helpfully capture "what was running".
- CI logs that echo the command before running it.
argv is an interface designed for things that are fine to be seen: file names, flags, modes.
The mitigations that only half work
hidepid=2 on the /proc mount hides other users' processes from unprivileged users. It is a good hardening step, but it is a property of the host, not of your tool, and you do not get to assume it.
Some tools overwrite their own argv after parsing. curl does this with -u, replacing the password with filler characters. It narrows the window but does not close it: the secret is visible between exec and the overwrite, and anything that logged the exec at the start already has it.
Environment variables are better than argv, since /proc/PID/environ is only readable by the same user and root. But they are inherited by every child process, and they show up in crash dumps and debug output. I covered that in an earlier post on keys in environment variables.
What a file descriptor gives you
A file descriptor is a handle that exists only inside one process (and whatever it deliberately shares it with). The secret travels through a pipe or a file the caller controls, and never appears in the command line. The only thing in argv is a small integer.
The interface looks like this:
./mytool --secret-fd 3 3<secret.txt
pass show example/db | ./mytool --secret-fd 0
./mytool --secret-fd 3 3< <(pass show example/db)
In the first form the shell opens the file as descriptor 3 before starting the tool. In the second, stdin is the secret. In the third, process substitution hands you a pipe and the secret never touches disk.
Several established tools already offer this shape: gpg --passphrase-fd, openssl ... -passin fd:N, docker login --password-stdin and cryptsetup --key-file=-. You are in good company.
Reading it in Go
Go does not hand you inherited descriptors by number, but os.NewFile wraps one:
package main
import (
"bytes"
"errors"
"flag"
"fmt"
"io"
"log"
"os"
)
func secretFromFD(fd uintptr) ([]byte, error) {
f := os.NewFile(fd, "secret-fd")
if f == nil {
return nil, errors.New("invalid file descriptor")
}
defer f.Close()
// Simplified: a secret over 4 KiB is silently truncated.
b, err := io.ReadAll(io.LimitReader(f, 4096))
if err != nil {
return nil, fmt.Errorf("reading secret fd: %w", err)
}
return bytes.TrimRight(b, "\r\n"), nil
}
func main() {
fd := flag.Int("secret-fd", -1, "file descriptor to read the secret from")
flag.Parse()
if *fd < 0 {
log.Fatal("--secret-fd is required")
}
secret, err := secretFromFD(uintptr(*fd))
if err != nil {
log.Fatal(err)
}
fmt.Fprintf(os.Stderr, "got %d bytes\n", len(secret))
}
Two details matter. Trim the trailing newline, because echo and most editors add one and it will otherwise become part of your password. And close the descriptor once read.
That close is not tidiness. A descriptor inherited from the shell has no close-on-exec flag, so any child you later spawn can inherit a still-open pipe or file containing the secret. Read it, then close it, before you start anything else.
Quick detour: why /dev/fd/N works too
Hang on, if bash gives <(cmd) to a program as a path like /dev/fd/63, how does open() on that path work? It is a symlink to /proc/self/fd/63, and opening a procfs fd link re-opens the underlying object. For a pipe, you get the same pipe, so reads consume the same data.
That means a tool with only a --password-file flag can already be fed a secret safely: mytool --password-file <(pass show example/db). The path is in argv but the secret is not. The catch is that a pipe can only be read once, so a tool that opens the file twice (say, once to validate and once to use) will get an empty second read.
Checking it worked
Start your tool with a descriptor and look at what the outside world sees:
./mytool --secret-fd 3 3<secret.txt &
tr '\0' ' ' </proc/$!/cmdline; echo
ls -l /proc/$!/fd
The command line should show only --secret-fd 3. If your tool exits quickly, add a sleep after reading while testing. After the close, descriptor 3 should no longer appear in the fd listing.
Pitfalls on the caller's side
- Do not build the input with an external
echoorcatin a way that puts the secret in their argv. Shell builtins likeprintfare fine, as they are not separate processes. - A here-string such as
3<<<"$SECRET"is convenient, but bash may back it with a temporary file on older versions. Check your version if that matters to you. - If the secret is in a shell variable, it is already in that shell's memory and probably its environment. The pattern protects the hand-off, not the whole life of the secret.
Offer the file descriptor option, document it first, and if you must keep a --password flag for compatibility, say in its help text that it is visible to other users. That one line of honesty costs you nothing.