diff --git a/doc/api/permissions.md b/doc/api/permissions.md index d36590ec3ae9cd..3fe1789453f575 100644 --- a/doc/api/permissions.md +++ b/doc/api/permissions.md @@ -244,6 +244,30 @@ There are constraints you need to know before using this system: * Using existing file descriptors via the `node:fs` module bypasses the Permission Model. +#### process._debugProcess() and cross-process Inspector activation + +The kInspector permission scope restricts the current process from opening its own V8 Inspector. However, +process._debugProcess(pid) — which sends an OS-level signal (SIGUSR1 on POSIX, a remote thread on Windows) +to an external process — is not gated by the kInspector scope or any other Permission Model scope. + +A sandboxed process running under --permission with no additional grants can call process._debugProcess(pid) +to force another Node.js process to open its V8 Inspector. The target process does not need to be running +under --permission for this to work — any Node.js process running on the same host under the same OS user +can be signaled. + +This is consistent with the Node.js threat model: Node.js trusts the OS environment in which it runs. +Cross-process signaling is an operating-system-level capability; restricting it is the responsibility of +the operator (for example, using OS-level process isolation, separate OS users per process, or +seccomp/AppArmor profiles on Linux). + +Developers relying on --permission to sandbox untrusted code should be aware that: + +* process._debugProcess() is callable from any sandboxed process with no grants. +* If a target Node.js process is running on the same host under the same OS user, it can be forced to + open its Inspector via this API. +* To prevent this, run sandboxed and target processes under different OS users, or use OS-level isolation + mechanisms outside of Node.js. + #### Limitations and Known Issues * Symbolic links will be followed even to locations outside of the set of paths