Skip to content

docs: note for updates from 0.5.0: keep the mask on for password commands and parent checks - #195

Merged
groupsky merged 1 commit into
mainfrom
hq-job/nodkey-190-build/191-mask-docs
Nov 16, 2026
Merged

groupsky merged 1 commit into
mainfrom
hq-job/nodkey-190-build/191-mask-docs

Conversation

@groupsky

Copy link
Copy Markdown
Contributor

Fixes #191.

Since 0.6.0 (#171), nodkey run masks the output by default when stdout or stderr is not a terminal. Two setups broke with no warning: a password command that prints the secret through a pipe (it now gets ***), and a wrapper that checks that its parent is its caller (nodkey now stays as the parent). This PR documents how to handle both with the mask on, and describes --no-mask as a last resort.

What changes

  • docs/setup.md, section 11, new part "Keep the mask on: password commands and wrappers":
    • Password command: run the program itself inside nodkey run, with password.cmd = "printenv VAR". The value goes only from the program to its own child, never through the masked output. It also says that the program and its children keep the value in their environment for the whole run.
    • Parent check: accept a parent named nodkey (read from /proc/PID/stat, as /proc/PID/exe cannot be read) and look at its parent. A warning says a name is not proof: use it only as a convenience, not a security boundary.
    • Inherited fds reach the masked command.
    • --no-mask as the last resort, with its cost.
  • docs/setup.md, 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", for execve and for a masked run: parent, process ID, stdin, pipes, process group and session, inherited fds, which signals are passed, what a SIGKILL of nodkey does, exit codes. Checked against internal/client/run.go and runmask.go, and with a small Go program for the fd and signal behavior.

The title of this PR is a note for updates, so it shows in the changelog of the next release.

THREAT-MODEL.md: no change. This PR only describes behavior that exists; no check and no value path changes.

Security review

The security-reviewer agent reviewed it twice. The first pass found one medium issue (a wrong claim about SIGUSR1: the Go runtime drops it) and four low ones (the parent-name warning, the CAP_SYS_PTRACE limit of "not dumpable", EPIPE after a SIGKILL, and the longer life of the value in the password-command pattern). All are fixed. The second pass found one low wording issue (the mask was overstated); it is fixed with the reviewer's text. No finding is open.

go test . (the docs test) passes.

🤖 Generated with Claude Code

…ands and parent checks (#191)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@groupsky
groupsky merged commit c5a87b9 into main Nov 16, 2026
7 checks passed
@groupsky
groupsky deleted the hq-job/nodkey-190-build/191-mask-docs branch November 16, 2026 14:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: masking by default (#171) breaks password commands and parent checks; show how to handle them with the mask on

1 participant