diff --git a/doc/api/permissions.md b/doc/api/permissions.md index d36590ec3ae9cd..1a187896db812f 100644 --- a/doc/api/permissions.md +++ b/doc/api/permissions.md @@ -244,6 +244,36 @@ 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