◐ Shell
clean mode source ↗

doc: clarify process._debugProcess() in Permission Model · nodejs/node@ce47ea3

Original file line numberDiff line numberDiff line change

@@ -212,6 +212,30 @@ There are constraints you need to know before using this system:

212212

* Using existing file descriptors via the `node:fs` module bypasses the

213213

Permission Model.

214214
215+

#### process.\_debugProcess() and cross-process Inspector activation

216+
217+

The `kInspector` permission scope restricts the current process from opening its own V8 Inspector. However,

218+

process.\_debugProcess(pid) — which sends an OS-level signal (SIGUSR1 on POSIX, a remote thread on Windows)

219+

to an external process — is not gated by the `kInspector` scope or any other Permission Model scope.

220+
221+

A sandboxed process running under --permission with no additional grants can call process.\_debugProcess(pid)

222+

to force another Node.js process to open its V8 Inspector. The target process does not need to be running

223+

under --permission for this to work — any Node.js process running on the same host under the same OS user

224+

can be signaled.

225+
226+

This is consistent with the Node.js threat model: Node.js trusts the OS environment in which it runs.

227+

Cross-process signaling is an operating-system-level capability; restricting it is the responsibility of

228+

the operator (for example, using OS-level process isolation, separate OS users per process, or

229+

seccomp/AppArmor profiles on Linux).

230+
231+

Developers relying on --permission to sandbox untrusted code should be aware that:

232+
233+

* process.\_debugProcess() is callable from any sandboxed process with no grants.

234+

* If a target Node.js process is running on the same host under the same OS user, it can be forced to

235+

open its Inspector via this API.

236+

* To prevent this, run sandboxed and target processes under different OS users, or use OS-level isolation

237+

mechanisms outside of Node.js.

238+
215239

#### Limitations and Known Issues

216240
217241

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