1NPM-AUDIT(1) NPM-AUDIT(1)
2
3
4
6 npm-audit - Run a security audit
7
8 Synopsis
9 npm audit [--json] [--production] [--audit-level=(low|moderate|high|critical)]
10 npm audit fix [--force|--package-lock-only|--dry-run|--production|--only=(dev|prod)]
11
12 common options: [--production] [--only=(dev|prod)]
13
14 Description
15 The audit command submits a description of the dependencies configured
16 in your project to your default registry and asks for a report of known
17 vulnerabilities. If any vulnerabilities are found, then the impact and
18 appropriate remediation will be calculated. If the fix argument is
19 provided, then remediations will be applied to the package tree.
20
21 The command will exit with a 0 exit code if no vulnerabilities were
22 found.
23
24 Note that some vulnerabilities cannot be fixed automatically and will
25 require manual intervention or review. Also note that since npm audit
26 fix runs a full-fledged npm install under the hood, all configs that
27 apply to the installer will also apply to npm install -- so things like
28 npm audit fix --package-lock-only will work as expected.
29
30 By default, the audit command will exit with a non-zero code if any
31 vulnerability is found. It may be useful in CI environments to include
32 the --audit-level parameter to specify the minimum vulnerability level
33 that will cause the command to fail. This option does not filter the
34 report output, it simply changes the command's failure threshold.
35
36 Audit Endpoints
37 There are two audit endpoints that npm may use to fetch vulnerability
38 information: the Bulk Advisory endpoint and the Quick Audit endpoint.
39
40 Bulk Advisory Endpoint
41 As of version 7, npm uses the much faster Bulk Advisory endpoint to op‐
42 timize the speed of calculating audit results.
43
44 npm will generate a JSON payload with the name and list of versions of
45 each package in the tree, and POST it to the default configured reg‐
46 istry at the path /-/npm/v1/security/advisories/bulk.
47
48 Any packages in the tree that do not have a version field in their
49 package.json file will be ignored. If any --omit options are specified
50 (either via the --omit config, or one of the shorthands such as --pro‐
51 duction, --only=dev, and so on), then packages will be omitted from the
52 submitted payload as appropriate.
53
54 If the registry responds with an error, or with an invalid response,
55 then npm will attempt to load advisory data from the Quick Audit end‐
56 point.
57
58 The expected result will contain a set of advisory objects for each de‐
59 pendency that matches the advisory range. Each advisory object con‐
60 tains a name, url, id, severity, vulnerable_versions, and title.
61
62 npm then uses these advisory objects to calculate vulnerabilities and
63 meta-vulnerabilities of the dependencies within the tree.
64
65 Quick Audit Endpoint
66 If the Bulk Advisory endpoint returns an error, or invalid data, npm
67 will attempt to load advisory data from the Quick Audit endpoint, which
68 is considerably slower in most cases.
69
70 The full package tree as found in package-lock.json is submitted, along
71 with the following pieces of additional metadata:
72
73 • npm_version
74
75 • node_version
76
77 • platform
78
79 • arch
80
81 • node_env
82
83
84 All packages in the tree are submitted to the Quick Audit endpoint.
85 Omitted dependency types are skipped when generating the report.
86
87 Scrubbing
88 Out of an abundance of caution, npm versions 5 and 6 would "scrub" any
89 packages from the submitted report if their name contained a / charac‐
90 ter, so as to avoid leaking the names of potentially private packages
91 or git URLs.
92
93 However, in practice, this resulted in audits often failing to properly
94 detect meta-vulnerabilities, because the tree would appear to be in‐
95 valid due to missing dependencies, and prevented the detection of vul‐
96 nerabilities in package trees that used git dependencies or private
97 modules.
98
99 This scrubbing has been removed from npm as of version 7.
100
101 Calculating Meta-Vulnerabilities and Remediations
102 npm uses the @npmcli/metavuln-calculator http://npm.im/@npm‐
103 cli/metavuln-calculator module to turn a set of security advisories
104 into a set of "vulnerability" objects. A "meta-vulnerability" is a de‐
105 pendency that is vulnerable by virtue of dependence on vulnerable ver‐
106 sions of a vulnerable package.
107
108 For example, if the package foo is vulnerable in the range >=1.0.2
109 <2.0.0, and the package bar depends on foo@^1.1.0, then that version of
110 bar can only be installed by installing a vulnerable version of foo.
111 In this case, bar is a "metavulnerability".
112
113 Once metavulnerabilities for a given package are calculated, they are
114 cached in the ~/.npm folder and only re-evaluated if the advisory range
115 changes, or a new version of the package is published (in which case,
116 the new version is checked for metavulnerable status as well).
117
118 If the chain of metavulnerabilities extends all the way to the root
119 project, and it cannot be updated without changing its dependency
120 ranges, then npm audit fix will require the --force option to apply the
121 remediation. If remediations do not require changes to the dependency
122 ranges, then all vulnerable packages will be updated to a version that
123 does not have an advisory or metavulnerability posted against it.
124
125 Exit Code
126 The npm audit command will exit with a 0 exit code if no vulnerabili‐
127 ties were found. The npm audit fix command will exit with 0 exit code
128 if no vulnerabilities are found or if the remediation is able to suc‐
129 cessfully fix all vulnerabilities.
130
131 If vulnerabilities were found the exit code will depend on the au‐
132 dit-level configuration setting.
133
134 Examples
135 Scan your project for vulnerabilities and automatically install any
136 compatible updates to vulnerable dependencies:
137
138 $ npm audit fix
139
140 Run audit fix without modifying node_modules, but still updating the
141 pkglock:
142
143 $ npm audit fix --package-lock-only
144
145 Skip updating devDependencies:
146
147 $ npm audit fix --only=prod
148
149 Have audit fix install SemVer-major updates to toplevel dependencies,
150 not just SemVer-compatible ones:
151
152 $ npm audit fix --force
153
154 Do a dry run to get an idea of what audit fix will do, and also output
155 install information in JSON format:
156
157 $ npm audit fix --dry-run --json
158
159 Scan your project for vulnerabilities and just show the details, with‐
160 out fixing anything:
161
162 $ npm audit
163
164 Get the detailed audit report in JSON format:
165
166 $ npm audit --json
167
168 Fail an audit only if the results include a vulnerability with a level
169 of moderate or higher:
170
171 $ npm audit --audit-level=moderate
172
173 Configuration
174 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> <!-- automatically
175 generated, do not edit manually --> <!-- see lib/utils/config/defini‐
176 tions.js -->
177
178 audit-level
179 • Default: null
180
181 • Type: null, "info", "low", "moderate", "high", "critical", or "none"
182
183
184 The minimum level of vulnerability for npm audit to exit with a
185 non-zero exit code. <!-- automatically generated, do not edit manually
186 --> <!-- see lib/utils/config/definitions.js -->
187
188
189 dry-run
190 • Default: false
191
192 • Type: Boolean
193
194
195 Indicates that you don't want npm to make any changes and that it
196 should only report what it would have done. This can be passed into any
197 of the commands that modify your local installation, eg, install, up‐
198 date, dedupe, uninstall, as well as pack and publish.
199
200 Note: This is NOT honored by other network related commands, eg
201 dist-tags, owner, etc. <!-- automatically generated, do not edit manu‐
202 ally --> <!-- see lib/utils/config/definitions.js -->
203
204
205 force
206 • Default: false
207
208 • Type: Boolean
209
210
211 Removes various protections against unfortunate side effects, common
212 mistakes, unnecessary performance degradation, and malicious input.
213
214 • Allow clobbering non-npm files in global installs.
215
216 • Allow the npm version command to work on an unclean git repository.
217
218 • Allow deleting the cache folder with npm cache clean.
219
220 • Allow installing packages that have an engines declaration requiring
221 a different version of npm.
222
223 • Allow installing packages that have an engines declaration requiring
224 a different version of node, even if --engine-strict is enabled.
225
226 • Allow npm audit fix to install modules outside your stated dependency
227 range (including SemVer-major changes).
228
229 • Allow unpublishing all versions of a published package.
230
231 • Allow conflicting peerDependencies to be installed in the root
232 project.
233
234 • Implicitly set --yes during npm init.
235
236 • Allow clobbering existing values in npm pkg
237
238
239 If you don't have a clear idea of what you want to do, it is strongly
240 recommended that you do not use this option! <!-- automatically gener‐
241 ated, do not edit manually --> <!-- see lib/utils/config/definitions.js
242 -->
243
244
245 json
246 • Default: false
247
248 • Type: Boolean
249
250
251 Whether or not to output JSON data, rather than the normal output.
252
253 • In npm pkg set it enables parsing set values with JSON.parse() before
254 saving them to your package.json.
255
256
257 Not supported by all npm commands. <!-- automatically generated, do
258 not edit manually --> <!-- see lib/utils/config/definitions.js -->
259
260
261 package-lock-only
262 • Default: false
263
264 • Type: Boolean
265
266
267 If set to true, the current operation will only use the pack‐
268 age-lock.json, ignoring node_modules.
269
270 For update this means only the package-lock.json will be updated, in‐
271 stead of checking node_modules and downloading dependencies.
272
273 For list this means the output will be based on the tree described by
274 the package-lock.json, rather than the contents of node_modules. <!--
275 automatically generated, do not edit manually --> <!-- see
276 lib/utils/config/definitions.js -->
277
278
279 omit
280 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
281 duction', otherwise empty.
282
283 • Type: "dev", "optional", or "peer" (can be set multiple times)
284
285
286 Dependency types to omit from the installation tree on disk.
287
288 Note that these dependencies are still resolved and added to the pack‐
289 age-lock.json or npm-shrinkwrap.json file. They are just not physically
290 installed on disk.
291
292 If a package type appears in both the --include and --omit lists, then
293 it will be included.
294
295 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
296 ment variable will be set to 'production' for all lifecycle scripts.
297 <!-- automatically generated, do not edit manually --> <!-- see
298 lib/utils/config/definitions.js -->
299
300
301 workspace
302 • Default:
303
304 • Type: String (can be set multiple times)
305
306
307 Enable running a command in the context of the configured workspaces of
308 the current project while filtering by running only the workspaces de‐
309 fined by this configuration option.
310
311 Valid values for the workspace config are either:
312
313 • Workspace names
314
315 • Path to a workspace directory
316
317 • Path to a parent workspace directory (will result in selecting all
318 workspaces within that folder)
319
320
321 When set for the npm init command, this may be set to the folder of a
322 workspace which does not yet exist, to create the folder and set it up
323 as a brand new workspace within the project.
324
325 This value is not exported to the environment for child processes.
326 <!-- automatically generated, do not edit manually --> <!-- see
327 lib/utils/config/definitions.js -->
328
329
330 workspaces
331 • Default: null
332
333 • Type: null or Boolean
334
335
336 Set to true to run the command in the context of all configured
337 workspaces.
338
339 Explicitly setting this to false will cause commands like install to
340 ignore workspaces altogether. When not set explicitly:
341
342 • Commands that operate on the node_modules tree (install, update,
343 etc.) will link workspaces into the node_modules folder. - Commands
344 that do other things (test, exec, publish, etc.) will operate on the
345 root project, unless one or more workspaces are specified in the
346 workspace config.
347
348
349 This value is not exported to the environment for child processes.
350 <!-- automatically generated, do not edit manually --> <!-- see
351 lib/utils/config/definitions.js -->
352
353
354 include-workspace-root
355 • Default: false
356
357 • Type: Boolean
358
359
360 Include the workspace root when workspaces are enabled for a command.
361
362 When false, specifying individual workspaces via the workspace config,
363 or all workspaces via the workspaces flag, will cause npm to operate
364 only on the specified workspaces, and not on the root project. <!--
365 automatically generated, do not edit manually --> <!-- see
366 lib/utils/config/definitions.js -->
367
368 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
369
370
371 See Also
372 • npm help install
373
374 • npm help config
375
376
377
378
379 January 2022 NPM-AUDIT(1)