Node.js 5 min read

Node.js permission model: lock down scripts and services

Use the Node.js permission model to limit file, network and process access: audit mode, minimal grants, config files, npx and the known limits.

Crest Design
Padlock over a Node.js process with permission flags

The Node.js permission model lets you start a process with --permission and then grant only the access it needs: specific folders to read or write, network access, child processes, worker threads and so on. Anything not granted throws an ERR_ACCESS_DENIED error. It has been stable since Node.js 22.13.0 and 23.5.0, and on current releases it now also covers network access and has an audit mode, which makes it far easier to adopt.

It is a useful extra layer for build scripts, CLI tools, scheduled jobs and small services. It is not a sandbox for untrusted code, and the Node.js docs say so plainly. This guide covers what it restricts, how to roll it out without breaking things, and where its limits are. It is general technical information, not security advice for your specific setup.

What the permission model restricts

With --permission enabled, the docs list these as restricted by default: file system access, network access, child processes, worker threads, native addons, WASI, FFI, the inspector, and OpenSSL STORE loaders. You grant access back with flags:

Flag Grants Notes at the time of writing
--allow-fs-read=<path> Reading files under a path Your entry point is readable automatically
--allow-fs-write=<path> Writing files under a path * allows everything
--allow-net Network access Added in Node.js 25.0.0; marked as active development
--allow-child-process Spawning processes Needed by many build tools
--allow-worker Worker threads
--allow-addons, --allow-wasi, --allow-ffi Native code and WASI Leave off unless required

The current documentation is for the Node.js 26.x LTS line (v26.13.0 at the time of writing). On Node.js 22 and 24 you get the stable file system and process controls, but network access isn't restricted and audit mode isn't available, because both arrived in the 25.x line. Our Node.js 26 LTS upgrade guide covers moving across.

Where it is worth using

  • Build and deployment scripts that should only touch the project folder.
  • Running third-party CLIs with npx, where you want a package to read its own files and nothing else.
  • Scheduled jobs such as exports, image processing or report generation, which have a narrow, predictable footprint.
  • Small API services that read config at startup, then only need the network and a temp folder.

It adds less value for a large framework app that legitimately reads widely across the file system and spawns workers, though even there it can block writes outside an upload or cache folder.

Step 1: discover what your app needs with audit mode

Since Node.js 25.8.0, --permission-audit runs the same checks without blocking anything. Denied operations are published to diagnostics channels, such as node:permission-model:fs and node:permission-model:net, with the permission and the resource (file path or host). Execution continues.

To see them, preload a small script that subscribes to those channels with diagnostics_channel and logs each message. Preloaded scripts are readable automatically. Run your test suite or a staging copy in audit mode for a few days so scheduled tasks and rare code paths show up, then turn the log into a list of grants.

Step 2: grant the minimum and enforce

Switch from --permission-audit to --permission and add only what the audit showed, for example read access to the app folder, write access to /tmp/exports/, and network access. A few path rules from the docs are worth knowing:

  • Granting an existing directory covers everything inside it. If the directory doesn't exist yet at startup, add a trailing wildcard yourself.
  • Wildcards are prefix matches: /home/app* also matches /home/app-old, so be precise.
  • Since Node.js 22.17.0 and 24.2.0, your entry point is readable without a grant.

Rather than long command lines, put grants in a config file. Node.js 26.12.0 made --config-file stable, and a top-level permission object in that file (for example "allow-fs-read": ["./"] and "allow-net": true) turns the permission model on automatically. That keeps the policy in version control where it can be reviewed.

Step 3: drop access you only need at startup

Many services read secrets or config once at boot. With process.permission.drop('fs.read', '/etc/myapp') you can remove that access after reading, and process.permission.drop('child') removes the ability to spawn processes. Dropping is irreversible and affects future checks only, not files or sockets already open. You can check access at runtime with process.permission.has('fs.write', path), which is handy for clear error messages.

Step 4: use it with npx and CI

To run a package under the permission model, pass the flag through npm: npx --node-options="--permission" package-name. The docs note this usually fails until you grant read access to where the package lives, for example --allow-fs-read=$(npm config get cache) for the npx cache. In CI, wrap your build or deploy scripts the same way so a compromised dependency has a smaller blast radius.

Know the limits

The Node.js docs describe the model as a "seat belt" and say it does not provide security guarantees against malicious code. Specific limits they list include:

  • Symbolic links are followed even when they point outside granted paths, so granted folders must not contain relative symlinks.
  • Using an existing file descriptor through node:fs bypasses the checks.
  • Flags such as --env-file read files before the model starts, so they aren't covered.
  • process._debugProcess(pid) isn't gated, so a restricted process could open the inspector of another Node.js process run by the same OS user. Separate OS users or containers mitigate this.
  • Worker threads created with an explicit execArgv don't keep the parent's grants unless you pass the flags again.

Treat it as one layer alongside running as a non-root user, container isolation, dependency auditing and secret management.

Audit first, grant the minimum, then drop what you only needed at startup.

Frequently asked questions

Does the permission model replace Docker or other containers?

No. Containers and OS users isolate the whole process; the permission model limits what Node.js APIs can do inside it. They work well together.

Will it slow my app down?

The permissions documentation doesn't give performance figures. The checks run when restricted APIs are called, so measure under your own load before rolling out to production.

Can I use it on Node.js 22?

Yes, from 22.13.0 the model is stable for file system and process controls. The network flag and audit mode need a newer release line.

Need help hardening a Node.js app?

We build and maintain Node.js services, including upgrades and least-privilege setups, through our Node.js development service. For related reading, see our Node.js 26 LTS upgrade guide and website security checklist for small businesses. To review your setup with us, get in touch.

Sources: Permissions (Node.js docs), Command-line API (Node.js docs)

(over to you)

Planning a build like this?

Tell us what you're building and we'll come back with ideas and next steps.