Skip to content

Commit ea5c6bc

Browse files
author
cybe4sent1nel
committed
doc: clarify process._debugProcess() in Permission Model
1 parent e6ef477 commit ea5c6bc

File tree

1 file changed

+24
-0
lines changed

1 file changed

+24
-0
lines changed

doc/api/permissions.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -244,6 +244,30 @@ There are constraints you need to know before using this system:
244244
* Using existing file descriptors via the `node:fs` module bypasses the
245245
Permission Model.
246246

247+
#### process.\_debugProcess() and cross-process Inspector activation
248+
249+
The kInspector permission scope restricts the current process from opening its own V8 Inspector. However,
250+
process.\_debugProcess(pid) — which sends an OS-level signal (SIGUSR1 on POSIX, a remote thread on Windows)
251+
to an external process — is not gated by the kInspector scope or any other Permission Model scope.
252+
253+
A sandboxed process running under --permission with no additional grants can call process.\_debugProcess(pid)
254+
to force another Node.js process to open its V8 Inspector. The target process does not need to be running
255+
under --permission for this to work — any Node.js process running on the same host under the same OS user
256+
can be signaled.
257+
258+
This is consistent with the Node.js threat model: Node.js trusts the OS environment in which it runs.
259+
Cross-process signaling is an operating-system-level capability; restricting it is the responsibility of
260+
the operator (for example, using OS-level process isolation, separate OS users per process, or
261+
seccomp/AppArmor profiles on Linux).
262+
263+
Developers relying on --permission to sandbox untrusted code should be aware that:
264+
265+
* process.\_debugProcess() is callable from any sandboxed process with no grants.
266+
* If a target Node.js process is running on the same host under the same OS user, it can be forced to
267+
open its Inspector via this API.
268+
* To prevent this, run sandboxed and target processes under different OS users, or use OS-level isolation
269+
mechanisms outside of Node.js.
270+
247271
#### Limitations and Known Issues
248272

249273
* Symbolic links will be followed even to locations outside of the set of paths

0 commit comments

Comments
 (0)