Skip to content

Commit

Permalink
doc: clarify policy expectations
Browse files Browse the repository at this point in the history
PR-URL: #48947
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
  • Loading branch information
RafaelGSS authored and UlisesGascon committed Sep 10, 2023
1 parent 9a8fb4f commit f823472
Showing 1 changed file with 27 additions and 11 deletions.
38 changes: 27 additions & 11 deletions doc/api/permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,11 +33,18 @@ If you find a potential security vulnerability, please refer to our

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

Policies are a security feature intended to allow guarantees
about what code Node.js is able to load. 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.
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
Expand Down Expand Up @@ -202,12 +209,6 @@ the manifest and then immediately used without searching.
Any specifier string for which resolution is attempted and that is not listed in
the dependencies results in an error according to the policy.

Redirection does not prevent access to APIs through means such as direct access
to `require.cache` or through `module.constructor` which allow access to
loading modules. Policy redirection only affects specifiers to `require()` and
`import`. Other means, such as to prevent undesired access to APIs through
variables, are necessary to lock down that path of loading modules.

A boolean value of `true` for the dependencies map can be specified to allow a
module to load any specifier without redirection. This can be useful for local
development and may have some valid usage in production, but should be used
Expand All @@ -224,6 +225,9 @@ can be used to ensure some kinds of dynamic access are explicitly prevented.
Unknown values for the resolved module location cause failures but are
not guaranteed to be forward compatible.

All the guarantees for policy redirection are specified in the
[Guarantees](#guarantees) section.

##### Example: Patched dependency

Redirected dependencies can provide attenuated or modified functionality as fits
Expand Down Expand Up @@ -446,6 +450,18 @@ not adopt the origin of the `blob:` URL.
Additionally, import maps only work on `import` so it may be desirable to add a
`"import"` condition to all dependency mappings.

#### Guarantees

* The policies guarantee the file integrity when a module is loaded using
`require()`, `import()` or `new Module()`.
* Redirection does not prevent access to APIs through means such as direct
access to `require.cache` which allow access to loaded modules.
Policy redirection only affects specifiers to `require()` and
`import`.
* The approval of the module integrity in policies threat model implies
they are allowed to muck with and even circumvent security features once
loaded so environmental/runtime hardening is expected.

## Process-based permissions

### Permission Model
Expand Down

0 comments on commit f823472

Please sign in to comment.