Skip to content

Commit 481f697

Browse files
author
cybe4sent1nel
committed
doc: clarify process._debugProcess() is not gated by kInspector
1 parent 0dfdec9 commit 481f697

1 file changed

Lines changed: 29 additions & 0 deletions

File tree

doc/api/permissions.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -244,6 +244,35 @@ 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
250+
opening its own V8 Inspector. However, `process._debugProcess(pid)`
251+
which sends an OS-level signal (SIGUSR1 on POSIX, a remote thread on
252+
Windows) to an external process — is **not** gated by the `kInspector`
253+
scope or any other Permission Model scope.
254+
255+
A sandboxed process running under `--permission` with no additional
256+
grants can call `process._debugProcess(pid)` to force another Node.js
257+
process to open its V8 Inspector, regardless of whether that target
258+
process has any permission restrictions.
259+
260+
This is consistent with the Node.js threat model: Node.js trusts the
261+
OS environment in which it runs. Cross-process signaling is an
262+
operating-system-level capability; restricting it is the responsibility
263+
of the **operator** (for example, using OS-level process isolation,
264+
separate OS users per process, or seccomp/AppArmor profiles on Linux).
265+
266+
Developers relying on `--permission` to sandbox untrusted code should
267+
be aware that:
268+
269+
* `process._debugProcess()` is callable from any sandboxed process
270+
with no grants.
271+
* If a target Node.js process is running on the same host under the
272+
same OS user, it can be forced to open its Inspector via this API.
273+
* To prevent this, run sandboxed and target processes under different
274+
OS users, or use OS-level isolation mechanisms outside of Node.js.
275+
247276
#### Limitations and Known Issues
248277

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

0 commit comments

Comments
 (0)