Skip to content

Commit 95dee4f

Browse files
doc: clarify process._debugProcess() in Permission Model
PR-URL: #62537 Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
1 parent 3f52482 commit 95dee4f

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
@@ -248,6 +248,30 @@ There are constraints you need to know before using this system:
248248
* Using existing file descriptors via the `node:fs` module bypasses the
249249
Permission Model.
250250

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

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

0 commit comments

Comments
 (0)