Permissions#

Source Code: src/permission.cc

Permissions can be used to control what system resources the Node.js process has access to or what actions the process can take with those resources. Permissions can also control what modules can be accessed by other modules.

  • Module-based permissions control which files or URLs are available to other modules during application execution. This can be used to control what modules can be accessed by third-party dependencies, for example.

  • Process-based permissions control the Node.js process's access to resources. The resource can be entirely allowed or denied, or actions related to it can be controlled. For example, file system reads can be allowed while denying writes. This feature does not protect against malicious code. According to the Node.js Security Policy, Node.js trusts any code it is asked to run.

The permission model implements a "seat belt" approach, which prevents trusted code from unintentionally changing files or using resources that access has not explicitly been granted to. It does not provide security guarantees in the presence of malicious code. Malicious code can bypass the permission model and execute arbitrary code without the restrictions imposed by the permission model.

If you find a potential security vulnerability, please refer to our Security Policy.

Module-based permissions#

Policies#

Stability: 0 - Deprecated: Will be removed shortly

Node.js contains experimental support for creating policies on loading code.

Policies are a security feature intended to ensure the integrity of the loaded code.

While it does not function as a provenance mechanism to trace the origin of code, it serves as a robust defense against the execution of malicious code. Unlike runtime-based models that may restrict capabilities once the code is loaded, Node.js policies focus on preventing malicious code from ever being fully loaded into the application in the first place.

The use of policies assumes safe practices for the policy files such as ensuring that policy files cannot be overwritten by the Node.js application by using file permissions.

A best practice would be to ensure that the policy manifest is read-only for the running Node.js application and that the file cannot be changed by the running Node.js application in any way. A typical setup would be to create the policy file as a different user id than the one running Node.js and granting read permissions to the user id running Node.js.

Enabling#

The --experimental-policy flag can be used to enable features for policies when loading modules.

Once this has been set, all modules must conform to a policy manifest file passed to the flag:

node --experimental-policy=policy.json app.js

The policy manifest will be used to enforce constraints on code loaded by Node.js.

To mitigate tampering with policy files on disk, an integrity for the policy file itself may be provided via --policy-integrity. This allows running node and asserting the policy file contents even if the file is changed on disk.

node --experimental-policy=policy.json --policy-integrity="sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0" app.js
Features#
Error behavior#

When a policy check fails, Node.js by default will throw an error. It is possible to change the error behavior to one of a few possibilities by defining an "onerror" field in a policy manifest. The following values are available to change the behavior:

  • "exit": will exit the process immediately. No cleanup code will be allowed to run.
  • "log": will log the error at the site of the failure.
  • "throw": will throw a JS error at the site of the failure. This is the default.
{
  "onerror": "log",
  "resources": {
    "./app/checked.js": {
      "integrity": "sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0"
    }
  }
}
Integrity checks#

Policy files must use integrity checks with Subresource Integrity strings compatible with the browser integrity attribute associated with absolute URLs.

When using require() or import all resources involved in loading are checked for integrity if a policy manifest has been specified. If a resource does not match the integrity listed in the manifest, an error will be thrown.

An example policy file that would allow loading a file checked.js:

{
  "resources": {
    "./app/checked.js": {
      "integrity": "sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0"
    }
  }
}

Each resource listed in the policy manifest can be of one the following formats to determine its location:

  1. A relative-URL string to a resource from the manifest such as ./resource.js, ../resource.js, or /resource.js.
  2. A complete URL string to a resource such as file:///resource.js.

When loading resources the entire URL must match including search parameters and hash fragment. ./a.js?b will not be used when attempting to load ./a.js and vice versa.

To generate integrity strings, a script such as node -e 'process.stdout.write("sha256-");process.stdin.pipe(crypto.createHash("sha256").setEncoding("base64")).pipe(process.stdout)' < FILE can be used.

Integrity can be specified as the boolean value true to accept any body for the resource which can be useful for local development. It is not recommended in production since it would allow unexpected alteration of resources to be considered valid.

Dependency redirection#

An application may need to ship patched versions of modules or to prevent modules from allowing all modules access to all other modules. Redirection can be used by intercepting attempts to load the modules wishing to be replaced.

{
  "resources": {
    "./app/checked.js": {
      "dependencies": {
        "fs": true,
        "os": "./app/node_modules/alt-os",
        "http": { "import": true }
      }
    }
  }
}

The dependencies are keyed by the requested specifier string and have values of either true, null, a string pointing to a module to be resolved, or a conditions object.

The specifier string does not perform any searching and must match exactly what is provided to the require() or import except for a canonicalization step. Therefore, multiple specifiers may be needed in the policy if it uses multiple different strings to point to the same module (such as excluding the extension).