In Node.js 24, what does running a service with --permission restrict, how do the --allow-* flags grant access back, and what does it not protect against?
answer
- deny by default, grant by flag
- file paths, children, workers, addons
- the network is not on the list
- a seat belt, not a sandbox
- audit before you enforce
basics
~20 s--permission makes Node deny file access, child processes, worker threads, addons, WASI and the inspector unless an --allow-* flag grants them. In Node 24 the network stays open, and the model guards trusted code, not malicious code.
solid answer
~40 sStarting Node with `--permission` turns on enforce mode: any `node:fs` access, `child_process` spawn, `worker_threads.Worker`, native addon, WASI instance or inspector connection that was not granted fails, mostly with `ERR_ACCESS_DENIED` (addons with `ERR_DLOPEN_DISABLED`). Grants are flags: `--allow-fs-read` and `--allow-fs-write` take `*` or a path, repeated once per path because commas no longer separate paths; `--allow-child-process`, `--allow-worker`, `--allow-addons`, `--allow-wasi` and `--allow-inspector` are switches. The entry point is readable implicitly (since v24.2.0), code can ask `process.permission.has('fs.write', dir)`, and since v24.20.0 `--permission-audit` reports violations on `node:diagnostics_channel` without denying them. The limits matter as much: Node 24 does not gate network access, files read by `--env-file` are outside the model, existing file descriptors and symlinks get past path checks, and the docs state it offers no guarantees against malicious code.
code
bash · 5 linesnode --permission \
--allow-fs-read=./config/ \
--allow-fs-write=./uploads/ \
--allow-child-process \
server.cjsgo deeper
Recall that --permission denies file access, child processes and worker threads by default, and that --allow-* flags grant them back.
Explain how path grants work, including repeats, wildcards and the implicit entry point, and how process.permission.has checks a grant at run time.
Show operational judgment: discover grants with --permission-audit, drop startup-only permissions, and state exactly what the model leaves open in Node 24, the network first.
Decide where the model fits in a team's defence: a cheap guard rail against buggy dependencies, never a substitute for operating-system isolation of untrusted code.
## What the Permission Model is The **Permission Model** is Node's built-in way to restrict what a process may touch. It sits behind the `--permission` flag, which has been stable since v22.13.0 and v23.5.0. Node's documentation describes it as a **"seat belt"**: it stops trusted code from unintentionally changing files or using resources it was not granted, and it explicitly offers no security guarantees in the presence of malicious code. ## What --permission denies, and the flag that grants it back | Resource | Granted by | Failure when not granted | |---|---|---| | File reads through `node:fs` | `--allow-fs-read=<path or *>` | `ERR_ACCESS_DENIED` | | File writes through `node:fs` | `--allow-fs-write=<path or *>` | `ERR_ACCESS_DENIED` | | Child processes | `--allow-child-process` | `ERR_ACCESS_DENIED` | | Worker threads | `--allow-worker` | `ERR_ACCESS_DENIED` | | Native addons | `--allow-addons` | `ERR_DLOPEN_DISABLED` | | WASI instances | `--allow-wasi` | `ERR_ACCESS_DENIED` | | The inspector protocol | `--allow-inspector` (v24.12.0) | `ERR_ACCESS_DENIED` | | OpenSSL STORE loaders | `--allow-openssl-store` (v24.21.0) | `ERR_ACCESS_DENIED` | Network access is **not** in that table. In Node 24 a process under `--permission` can still open sockets and make HTTP requests; the `--allow-net` flag that gates the network was added in v25.0.0. ## Granting file system access - Each of `--allow-fs-read` and `--allow-fs-write` takes `*`, an absolute path or a path relative to the working directory. Repeat the flag for each path; since v20.7.0 a comma no longer separates paths. - A path that names an **existing directory** is treated as that directory plus everything under it. For a directory that does not exist yet, write the wildcard yourself, as in `/data/out/*`. - Characters after a `*` are ignored, so `/home/*.js` behaves like `/home/*`. - The entry point, and modules preloaded with `-r`, are readable without a grant since v24.2.0. ## Checking and dropping permissions at run time When the model is on, `process.permission` appears. `process.permission.has('fs.write', './uploads')` returns whether a scope and resource are granted; the scopes include `fs`, `fs.read`, `fs.write`, `child` and `worker`. Since v24.20.0, `process.permission.drop(scope[, reference])` gives a permission up **irreversibly**, for example after reading configuration at startup. Dropping affects future checks only: files, children and workers that are already open stay open. ## Where the flags can live - **On the command line**, the usual place, visible in the start command. - **In `NODE_OPTIONS`**: `--permission` and every `--allow-*` flag are on the allow list, which is also how the model reaches Node children started with `child_process.spawn()` since v24.4.0. - **In a configuration file**, under a top-level `permission` object, when the experimental `--experimental-config-file` flag is used; that feature is still early development in Node 24, so treat it as optional. ## Discovering what a service needs Turning `--permission` on for an existing service usually breaks it on the first unexpected read. `--permission-audit` (v24.20.0) performs every check without denying anything and publishes each violation on `node:diagnostics_channel` channels such as `node:permission-model:fs` and `node:permission-model:child`. A practical rollout: 1. Run the service with `--permission-audit` in a test environment and subscribe to the channels. 2. Collect the resources it touches, and turn them into `--allow-*` flags. 3. Switch to `--permission` with those flags; if both flags are passed, enforce mode wins. ## What it does not protect against - **Malicious code.** The documentation states that malicious code can bypass the model and run without its restrictions; Node's security policy trusts any code it is asked to run. - **The network**, in Node 24. - **Startup reads.** Flags such as `--env-file` and `--openssl-config` read their files before the model is initialised, so those reads are not subject to it. - **Other file access paths.** The model restricts the file system through `node:fs`; the documentation does not guarantee that access through other modules, such as `node:sqlite`, is covered. - **Existing file descriptors.** Using an already open descriptor through `node:fs` bypasses the model. - **Symbolic links.** Links are followed even to locations outside the granted paths, so granted directories must not contain relative symlinks. - **Other processes.** `process._debugProcess(pid)` can still signal another Node process run by the same user to open its inspector; separating OS users is the operator's job. The model is valuable as a guard rail against a dependency or a bug writing where it should not. Isolating untrusted code still needs operating-system boundaries: separate users, containers or system-call filters.
- Why can't --permission be relied on to sandbox untrusted plugins inside a Node service?Because Node's documentation states the model offers no security guarantees against malicious code, which can bypass it. In Node 24 it also leaves the network open, lets existing file descriptors and symlinks past path checks, and cannot stop `process._debugProcess` from signalling another same-user Node process. Untrusted code needs operating-system isolation such as separate users or containers.
- With --allow-child-process granted, does a spawned Node child run under the same restrictions?A child started with `child_process.fork()` inherits the parent's execution arguments, so it receives the Permission Model flags. Since v24.4.0, `child_process.spawn()` of a Node child propagates them too, through the `NODE_OPTIONS` environment variable. A non-Node program the service spawns is outside Node's model altogether.
- How would you roll the Permission Model out on an existing service without breaking it?Run it with `--permission-audit` first, subscribe to the `node:permission-model:*` diagnostics channels, and record every resource it touches. Convert those into `--allow-*` flags, switch to `--permission`, and where startup alone needs a resource, give it up afterwards with `process.permission.drop`.
It works like keycards in an office building: staff only open the rooms they were issued, which stops honest mistakes, but it was never meant to stop a burglar who comes in through a window.
- --permission blocks outbound network requests in Node 24.
- The Permission Model safely sandboxes untrusted third-party code.
- --allow-fs-read=/a,/b grants read access to both paths.
- Under --permission, Node cannot read its own entry script without a grant.
- Variables from --env-file are blocked unless the file is in --allow-fs-read.
- process.permission.drop closes file handles the process already opened.
Assumes Node 24: the Permission Model is stable since v22.13.0 and v23.5.0, entry points are readable implicitly since v24.2.0, --permission-audit and process.permission.drop arrived in v24.20.0, and network access is only gated by --allow-net from v25.0.0, so it reaches LTS with Node 26.