-
-
Notifications
You must be signed in to change notification settings - Fork 33.5k
Integrity checks via policy #23834
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
Closed
Integrity checks via policy #23834
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,104 @@ | ||
# Policies | ||
|
||
|
||
<!--introduced_in=TODO--> | ||
<!-- type=misc --> | ||
|
||
> Stability: 1 - Experimental | ||
|
||
<!-- name=policy --> | ||
|
||
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. | ||
|
||
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. | ||
bmeck marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
## Enabling | ||
|
||
<!-- type=misc --> | ||
|
||
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: | ||
|
||
```sh | ||
node --experimental-policy=policy.json app.js | ||
``` | ||
|
||
The policy manifest will be used to enforce constraints on code loaded by | ||
Node.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"` (default) - will throw a JS error at the site of the failure. | ||
|
||
```json | ||
{ | ||
"onerror": "log", | ||
bmeck marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
"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](https://www.w3.org/TR/SRI/#the-integrity-attribute) | ||
associated with absolute URLs. | ||
bmeck marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
When using `require()` 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`: | ||
|
||
```json | ||
{ | ||
"resources": { | ||
"./app/checked.js": { | ||
"integrity": "sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0" | ||
} | ||
} | ||
} | ||
``` | ||
|
||
Each resource listed in the policy manifest can be of one the following | ||
bmeck marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
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`. | ||
bmeck marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
2. A complete url string to a resource such as `file:///resource.js`. | ||
bmeck marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
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. | ||
|
||
In order to generate integrity strings, a script such as | ||
`printf "sha384-$(cat checked.js | openssl dgst -sha384 -binary | base64)"` | ||
can be used. | ||
bmeck marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
||
|
||
[relative url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string | ||
bmeck marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.