@@ -212,6 +212,30 @@ There are constraints you need to know before using this system:
|
212 | 212 | * Using existing file descriptors via the `node:fs` module bypasses the |
213 | 213 | Permission Model. |
214 | 214 | |
| 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 | + |
215 | 239 | #### Limitations and Known Issues |
216 | 240 | |
217 | 241 | * Symbolic links will be followed even to locations outside of the set of paths |
|