Skip to content

Commit 18b9645

Browse files
rdw-msftrdw-msft
committed
add more code integrity docs
1 parent 05e012f commit 18b9645

File tree

2 files changed

+121
-0
lines changed

2 files changed

+121
-0
lines changed

‎doc/api/code_integrity.md

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Code Integrity
2+
3+
Code integrity refers to the assurance that software code has not been
4+
altered or tampered with in any unauthorized way. It ensures that
5+
the code running on a system is exactly what was intended by the developers.
6+
7+
Code integrity in Node.js integrates with platform features for code integrity
8+
policy enforcement. See platform speficic sections below for more information.
9+
10+
The Node.js threat model considers the code that the runtime executes to be
11+
trusted. As such, this feature is an additional safety belt, not a strict
12+
security boundary.
13+
14+
If you find a potential security vulnerability, please refer to our
15+
[Security Policy][].
16+
17+
## Code Integrity on Windows
18+
19+
There are three audiences that are involved when using Node.js in an
20+
environment enforcing code integrity. The application developers,
21+
those administrating the system enforcing code integrity, and
22+
the end user.
23+
24+
### Windows Code Integrity and Application Developers
25+
26+
Application developers are responsible for generating and
27+
distributing the signature information for their application.
28+
Application developers are also expected to design their application
29+
in robust ways to avoid unintended code execution.
30+
31+
Application developers can generate a Windows catalog file to
32+
store the hash of all files Node.js is expected to execute.
33+
34+
A catalog can be generated using the `New-FileCatalog` Powershell
35+
cmdlet. For example
36+
37+
```powershell
38+
New-FileCatalog -Version 2 -CatalogFilePath MyApplicationCatalog.cat -Path \my\application\path\
39+
```
40+
41+
The `Path` argument should point to the root folder containing your application's code. If
42+
your application's code is fully contained in one file, `Path` can point to that single file.
43+
44+
Be sure that the catalog is generated for the final version of the files that you intend to ship
45+
(i.e. after minifying).
46+
47+
### Windows Code Integrity and System Administrators
48+
49+
This section is intended for system administrators who want to enable Node.js
50+
code integrity features in their environments.
51+
52+
This section assumes familiarity with managing WDAC polcies.
53+
Official documentation for WDAC can be found [here](https://learn.microsoft.com/en-us/windows/security/application-security/application-control/windows-defender-application-control/).
54+
55+
Code integrity enforcement on Windows has two toggleable settings:
56+
`EnforceCodeIntegrity` and `DisableInteractiveMode`. These settings are configured
57+
by WDAC policy.
58+
59+
`EnforceCodeIntegrity` causes Node.js to call WldpCanExecuteFile whenever a module is loaded using `require`.
60+
WldpCanExecuteFile verifies that the file's integrity has not been tampered with from signing time.
61+
The system administrator should sign and install the application's file catalog where the application
62+
is running, per WDAC guidance.
63+
64+
`DisableInteractiveMode` prevents Node.js from being run in interactive mode, and also disables the `-e` and `--eval`
65+
command line options.
66+
67+
#### Enabling Code Integrity Enforcement
68+
69+
On newer Windows versions (22H2+), the preferred method of configuring application settings is done using
70+
`AppSettings` in your WDAC Policy.
71+
72+
```text
73+
<AppSettings>
74+
<App Manifest="wdac-manifest.xml">
75+
<Setting Name="EnforceCodeIntegrity" >
76+
<Value>True</Value>
77+
</Setting>
78+
<Setting Name="DisableInteractiveMode" >
79+
<Value>True</Value>
80+
</Setting>
81+
</App>
82+
</AppSettings>
83+
```
84+
85+
On older Windows versions, use the `Settings` section of your WDAC Policy.
86+
87+
```text
88+
<Settings>
89+
<Setting Provider="Node.js" Key="Settings" ValueName="EnforceCodeIntegrity">
90+
<Value>
91+
<Boolean>true</Boolean>
92+
</Value>
93+
</Setting>
94+
<Setting Provider="Node.js" Key="Settings" ValueName="DisableInteractiveMode">
95+
<Value>
96+
<Boolean>true</Boolean>
97+
</Value>
98+
</Setting>
99+
</Settings>
100+
```
101+
102+
### Windows Code Integrity and End Users
103+
104+
Depending on
105+
106+
## Code Integrity on Linux
107+
108+
Code integrity on Linux is not yet implemented. Plans for implementation will
109+
be made once the necessary APIs on Linux have been upstreamed.
110+
111+
## Code Integrity on MacOS
112+
113+
Code integrity on MacOS is not yet implemented. Currently, there is no
114+
timeline for implementation.
115+
116+
[Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md

‎doc/api/wdac-manifest.xml

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<AppManifest Id="NodeJS" xmlns="urn:schemas-microsoft-com:windows-defender-application-control">
3+
<SettingDefinition Name="EnforceCodeIntegrity" Type="Boolean" IgnoreAuditPolicies="false"/>
4+
<SettingDefinition Name="DisableInterpretiveMode" Type="Boolean" IgnoreAuditPolicies="false"/>
5+
</AppManifest>

0 commit comments

Comments
 (0)