You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
docs: masking by default (#171) breaks password commands and parent checks; show how to handle them with the mask on #191
#171 (in 0.6.0) made nodkey run mask secret values by default when stdout and stderr are not both a terminal. It is listed as a feature. After an update from 0.5.0, two common setups broke with no warning:
A password command that prints the secret. For example a mail client's password.cmd = "nodkey run --secret P=mail-read -- printenv P". The client reads the output through a pipe, so it now gets ***, and the login fails.
A wrapper that needs the command to replace nodkey (execve). With masking on, nodkey stays the parent of the command. A script that checks that its parent is the process that started nodkey run stops working.
--no-mask makes both work again, but it also lets any agent print the secret with one command. Masking should stay on. The docs should show how to handle each case with the mask on, and treat --no-mask as a last resort.
How each case works with the mask on
Password command: run the program that needs the secret insidenodkey run, and let it read the value from its own environment. For a mail client: nodkey run --secret MAIL_READ=mail-read -- mailclient …, with password.cmd = "printenv MAIL_READ". The value then moves only between the program and its own child, never through nodkey's masked output, and the program's own output to the agent stays masked. A small wrapper can pick the secrets per command (a read secret for reading, the send secret only for sending).
Parent check: accept nodkey as the parent. The command's parent is either the caller (execve) or a process named nodkey (masked) whose parent is the caller. nodkey is not dumpable, so /proc/PID/exe cannot be read; read the name and the parent pid from /proc/PID/stat. A masked run gives the command no extra file descriptors of its own making, but nodkey does not close inherited ones (Go closes only close-on-exec fds), so an fd passed to nodkey run reaches the command too.
Done when
docs/setup.md, the nodkey run section, explains both cases with the patterns above, with a password-command example that keeps the mask on. --no-mask is described as a last resort, with what it costs (any agent can then print the value).
docs/setup.md, the update section, has a note for an update from 0.5.0 or older: check each nodkey run whose output another program reads, and each script that checks its parent.
DESIGN.md says exactly what the command gets in a masked run (child of nodkey, stdin, inherited fds, which signals are passed, exit code) and in an execve run.
The changelog of the next release lists it as a note for updates.
changed the title [-]docs: masking by default (#171) breaks password commands and wrappers that need execve; say so and show --no-mask[/-][+]docs: masking by default (#171) breaks password commands and parent checks; show how to handle them with the mask on[/+]on Nov 16, 2026
Done in #195 (squash commit c5a87b9). Masking stays on; --no-mask is described as the last resort.
Evidence for "Done when":
docs/setup.md, the nodkey run section (section 11): new part "Keep the mask on: password commands and wrappers". It has a password-command example with the mask on (nodkey run --secret MAIL_READ=mail-read -- mail-client sync, with password.cmd = "printenv MAIL_READ") and the parent check from /proc/PID/stat. --no-mask is the last resort, with its cost: even a plain printenv then shows the value.
docs/setup.md, the update section (section 13): a note for an update from 0.5.0 or older: check each nodkey run whose output another program reads, and each script that checks its parent.
DESIGN.md section 5, step 7, "What the command gets": the execve run and the masked run (child of nodkey, stdin, pipes, inherited fds, process group, which signals are passed, a SIGKILL of nodkey, exit codes). Checked against internal/client/run.go and runmask.go. A small test program confirmed that an inherited fd reaches the child. The security reviewer confirmed the signal behavior with its own test.
The changelog of the next release: the title of docs: note for updates from 0.5.0: keep the mask on for password commands and parent checks #195 is the note ("docs: note for updates from 0.5.0: keep the mask on for password commands and parent checks"), so release-please lists it under Documentation. No release was made (that needs Geno's OK). This box can be ticked when the release is out, and then the issue can close.
Activity
[-]docs: masking by default (#171) breaks password commands and wrappers that need execve; say so and show --no-mask[/-][+]docs: masking by default (#171) breaks password commands and parent checks; show how to handle them with the mask on[/+]groupsky commentedon Nov 16, 2026
Done in #195 (squash commit c5a87b9). Masking stays on;
--no-maskis described as the last resort.Evidence for "Done when":
nodkey runsection (section 11): new part "Keep the mask on: password commands and wrappers". It has a password-command example with the mask on (nodkey run --secret MAIL_READ=mail-read -- mail-client sync, withpassword.cmd = "printenv MAIL_READ") and the parent check from/proc/PID/stat.--no-maskis the last resort, with its cost: even a plainprintenvthen shows the value.nodkey runwhose output another program reads, and each script that checks its parent.SIGKILLof nodkey, exit codes). Checked againstinternal/client/run.goandrunmask.go. A small test program confirmed that an inherited fd reaches the child. The security reviewer confirmed the signal behavior with its own test.