Skip to content

doc: clarify that process._debugProcess() is not restricted by the Permission Model#62537

Open
cybe4sent1nel wants to merge 3 commits intonodejs:mainfrom
cybe4sent1nel:doc/permission-model-debugprocess-clarification
Open

doc: clarify that process._debugProcess() is not restricted by the Permission Model#62537
cybe4sent1nel wants to merge 3 commits intonodejs:mainfrom
cybe4sent1nel:doc/permission-model-debugprocess-clarification

Conversation

@cybe4sent1nel
Copy link
Copy Markdown

What

Adds a documentation note to the Permission Model page clarifying that
process._debugProcess() is not restricted by the kInspector
permission scope or any other Permission Model scope.

Why

The Permission Model documentation lists "Inspector protocol" as a
restricted surface. A developer reading this reasonably expects that
--permission prevents all Inspector activation — including
cross-process activation via process._debugProcess().

The current behavior creates a silent inconsistency:

  • kInspector blocks the sandboxed process from opening its own
    Inspector.
  • kInspector does not block the sandboxed process from calling
    process._debugProcess(pid) to force another Node.js process to
    open its Inspector.

This gap is not documented anywhere. This note ensures developers are
not surprised by this behavior when they rely on the Permission Model
as a sandbox.

Behavior unchanged

This is a documentation-only change. No API behavior is modified.

Background

Discussed with @RafaelGSS. The behavior is consistent with the Node.js
threat model (Node.js trusts the OS environment it runs in, and
cross-process signaling is an OS-level capability). The fix here is
documentation so operators understand what responsibility falls on them
vs. the Permission Model.

Checklist

  • make lint passes
  • Documentation only — no tests required
  • Follows the Node.js documentation style

@nodejs-github-bot
Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/security-wg

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Apr 1, 2026
Co-authored-by: Rafael Gonzaga <rafael.nunu@hotmail.com>
@RafaelGSS RafaelGSS added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 1, 2026
Clarified that a target process does not need to run under `--permission` to open its V8 Inspector.
cybe4sent1nel

This comment was marked as duplicate.

@cybe4sent1nel
Copy link
Copy Markdown
Author

Thanks for catching that — I've updated the sentence to remove the
contradiction. The paragraph now simply states that any Node.js process
running on the same host under the same OS user can be signaled,
without the conflicting parenthetical.

cybe4sent1nel

This comment was marked as duplicate.

@RafaelGSS RafaelGSS added the commit-queue Add this label to land a pull request using GitHub Actions. label Apr 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author ready PRs that have at least one approval, no pending requests for changes, and a CI started. commit-queue Add this label to land a pull request using GitHub Actions. doc Issues and PRs related to the documentations.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants