1NPM-AUDIT(1) NPM-AUDIT(1)
2
6 npm-audit - Run a security audit
7 Synopsis
9 npm audit [fix|signatures]
10 Description
12 The audit command submits a description of the dependencies configured
13 in your project to your default registry and asks for a report of known
14 vulnerabilities. If any vulnerabilities are found, then the impact and
15 appropriate remediation will be calculated. If the fix argument is
16 provided, then remediations will be applied to the package tree.
17 The command will exit with a 0 exit code if no vulnerabilities were
19 found.
20 Note that some vulnerabilities cannot be fixed automatically and will
22 require manual intervention or review. Also note that since npm audit
23 fix runs a full-fledged npm install under the hood, all configs that
24 apply to the installer will also apply to npm install -- so things like
25 npm audit fix --package-lock-only will work as expected.
26 By default, the audit command will exit with a non-zero code if any
28 vulnerability is found. It may be useful in CI environments to include
29 the --audit-level parameter to specify the minimum vulnerability level
30 that will cause the command to fail. This option does not filter the
31 report output, it simply changes the command's failure threshold.
32 Audit Signatures
34 To ensure the integrity of packages you download from the public npm
35 registry, or any registry that supports signatures, you can verify the
36 registry signatures of downloaded packages using the npm CLI.
37 Registry signatures can be verified using the following audit command:
39 $ npm audit signatures
41 The npm CLI supports registry signatures and signing keys provided by
43 any registry if the following conventions are followed:
44 1. Signatures are provided in the package's packument in each published
46 version within the dist object:
47 "dist":{
50 "..omitted..": "..omitted..",
51 "signatures": [{
52 "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
53 "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809..."
54 }]
55 }
56 See this example https://registry.npmjs.org/light-cycle/1.4.3 of a
58 signed package from the public npm registry.
59 The sig is generated using the following template: ${pack‐
61 age.name}@${package.version}:${package.dist.integrity} and the keyid
62 has to match one of the public signing keys below.
63 1. Public signing keys are provided at registry-host.tld/-/npm/v1/keys
65 in the following format:
66 {
69 "keys": [{
70 "expires": null,
71 "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
72 "keytype": "ecdsa-sha2-nistp256",
73 "scheme": "ecdsa-sha2-nistp256",
74 "key": "{{B64_PUBLIC_KEY}}"
75 }]
76 }
77 Keys response:
79 • expires: null or a simplified extended <a
81 href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO
82 8601 format</a>: YYYY-MM-DDTHH:mm:ss.sssZ
83 • keydid: sha256 fingerprint of the public key
85 • keytype: only ecdsa-sha2-nistp256 is currently supported by the npm
87 CLI
88 • scheme: only ecdsa-sha2-nistp256 is currently supported by the npm
90 CLI
91 • key: base64 encoded public key
93 See this <a href="https://registry.npmjs.org/-/npm/v1/keys" tar‐
96 get="_blank">example key's response from the public npm registry</a>.
97 Audit Endpoints
99 There are two audit endpoints that npm may use to fetch vulnerability
100 information: the Bulk Advisory endpoint and the Quick Audit endpoint.
101 Bulk Advisory Endpoint
103 As of version 7, npm uses the much faster Bulk Advisory endpoint to op‐
104 timize the speed of calculating audit results.
105 npm will generate a JSON payload with the name and list of versions of
107 each package in the tree, and POST it to the default configured reg‐
108 istry at the path /-/npm/v1/security/advisories/bulk.
109 Any packages in the tree that do not have a version field in their
111 package.json file will be ignored. If any --omit options are specified
112 (either via the --omit config, or one of the shorthands such as --pro‐
113 duction, --only=dev, and so on), then packages will be omitted from the
114 submitted payload as appropriate.
115 If the registry responds with an error, or with an invalid response,
117 then npm will attempt to load advisory data from the Quick Audit end‐
118 point.
119 The expected result will contain a set of advisory objects for each de‐
121 pendency that matches the advisory range. Each advisory object con‐
122 tains a name, url, id, severity, vulnerable_versions, and title.
123 npm then uses these advisory objects to calculate vulnerabilities and
125 meta-vulnerabilities of the dependencies within the tree.
126 Quick Audit Endpoint
128 If the Bulk Advisory endpoint returns an error, or invalid data, npm
129 will attempt to load advisory data from the Quick Audit endpoint, which
130 is considerably slower in most cases.
131 The full package tree as found in package-lock.json is submitted, along
133 with the following pieces of additional metadata:
134 • npm_version
136 • node_version
138 • platform
140 • arch
142 • node_env
144 All packages in the tree are submitted to the Quick Audit endpoint.
147 Omitted dependency types are skipped when generating the report.
148 Scrubbing
150 Out of an abundance of caution, npm versions 5 and 6 would "scrub" any
151 packages from the submitted report if their name contained a / charac‐
152 ter, so as to avoid leaking the names of potentially private packages
153 or git URLs.
154 However, in practice, this resulted in audits often failing to properly
156 detect meta-vulnerabilities, because the tree would appear to be in‐
157 valid due to missing dependencies, and prevented the detection of vul‐
158 nerabilities in package trees that used git dependencies or private
159 modules.
160 This scrubbing has been removed from npm as of version 7.
162 Calculating Meta-Vulnerabilities and Remediations
164 npm uses the @npmcli/metavuln-calculator http://npm.im/@npm‐
165 cli/metavuln-calculator module to turn a set of security advisories
166 into a set of "vulnerability" objects. A "meta-vulnerability" is a de‐
167 pendency that is vulnerable by virtue of dependence on vulnerable ver‐
168 sions of a vulnerable package.
169 For example, if the package foo is vulnerable in the range >=1.0.2
171 <2.0.0, and the package bar depends on foo@^1.1.0, then that version of
172 bar can only be installed by installing a vulnerable version of foo.
173 In this case, bar is a "metavulnerability".
174 Once metavulnerabilities for a given package are calculated, they are
176 cached in the ~/.npm folder and only re-evaluated if the advisory range
177 changes, or a new version of the package is published (in which case,
178 the new version is checked for metavulnerable status as well).
179 If the chain of metavulnerabilities extends all the way to the root
181 project, and it cannot be updated without changing its dependency
182 ranges, then npm audit fix will require the --force option to apply the
183 remediation. If remediations do not require changes to the dependency
184 ranges, then all vulnerable packages will be updated to a version that
185 does not have an advisory or metavulnerability posted against it.
186 Exit Code
188 The npm audit command will exit with a 0 exit code if no vulnerabili‐
189 ties were found. The npm audit fix command will exit with 0 exit code
190 if no vulnerabilities are found or if the remediation is able to suc‐
191 cessfully fix all vulnerabilities.
192 If vulnerabilities were found the exit code will depend on the au‐
194 dit-level configuration setting.
195 Examples
197 Scan your project for vulnerabilities and automatically install any
198 compatible updates to vulnerable dependencies:
199 $ npm audit fix
201 Run audit fix without modifying node_modules, but still updating the
203 pkglock:
204 $ npm audit fix --package-lock-only
206 Skip updating devDependencies:
208 $ npm audit fix --only=prod
210 Have audit fix install SemVer-major updates to toplevel dependencies,
212 not just SemVer-compatible ones:
213 $ npm audit fix --force
215 Do a dry run to get an idea of what audit fix will do, and also output
217 install information in JSON format:
218 $ npm audit fix --dry-run --json
220 Scan your project for vulnerabilities and just show the details, with‐
222 out fixing anything:
223 $ npm audit
225 Get the detailed audit report in JSON format:
227 $ npm audit --json
229 Fail an audit only if the results include a vulnerability with a level
231 of moderate or higher:
232 $ npm audit --audit-level=moderate
234 Configuration
236 audit-level
237 • Default: null
238 • Type: null, "info", "low", "moderate", "high", "critical", or "none"
240 The minimum level of vulnerability for npm audit to exit with a
243 non-zero exit code.
244 dry-run
246 • Default: false
247 • Type: Boolean
249 Indicates that you don't want npm to make any changes and that it
252 should only report what it would have done. This can be passed into any
253 of the commands that modify your local installation, eg, install, up‐
254 date, dedupe, uninstall, as well as pack and publish.
255 Note: This is NOT honored by other network related commands, eg
257 dist-tags, owner, etc.
258 force
260 • Default: false
261 • Type: Boolean
263 Removes various protections against unfortunate side effects, common
266 mistakes, unnecessary performance degradation, and malicious input.
267 • Allow clobbering non-npm files in global installs.
269 • Allow the npm version command to work on an unclean git repository.
271 • Allow deleting the cache folder with npm cache clean.
273 • Allow installing packages that have an engines declaration requiring
275 a different version of npm.
276 • Allow installing packages that have an engines declaration requiring
278 a different version of node, even if --engine-strict is enabled.
279 • Allow npm audit fix to install modules outside your stated dependency
281 range (including SemVer-major changes).
282 • Allow unpublishing all versions of a published package.
284 • Allow conflicting peerDependencies to be installed in the root
286 project.
287 • Implicitly set --yes during npm init.
289 • Allow clobbering existing values in npm pkg
291 • Allow unpublishing of entire packages (not just a single version).
293 If you don't have a clear idea of what you want to do, it is strongly
296 recommended that you do not use this option!
297 json
299 • Default: false
300 • Type: Boolean
302 Whether or not to output JSON data, rather than the normal output.
305 • In npm pkg set it enables parsing set values with JSON.parse() before
307 saving them to your package.json.
308 Not supported by all npm commands.
311 package-lock-only
313 • Default: false
314 • Type: Boolean
316 If set to true, the current operation will only use the pack‐
319 age-lock.json, ignoring node_modules.
320 For update this means only the package-lock.json will be updated, in‐
322 stead of checking node_modules and downloading dependencies.
323 For list this means the output will be based on the tree described by
325 the package-lock.json, rather than the contents of node_modules.
326 omit
328 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
329 duction', otherwise empty.
330 • Type: "dev", "optional", or "peer" (can be set multiple times)
332 Dependency types to omit from the installation tree on disk.
335 Note that these dependencies are still resolved and added to the pack‐
337 age-lock.json or npm-shrinkwrap.json file. They are just not physically
338 installed on disk.
339 If a package type appears in both the --include and --omit lists, then
341 it will be included.
342 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
344 ment variable will be set to 'production' for all lifecycle scripts.
345 foreground-scripts
347 • Default: false
348 • Type: Boolean
350 Run all build scripts (ie, preinstall, install, and postinstall)
353 scripts for installed packages in the foreground process, sharing stan‐
354 dard input, output, and error with the main npm process.
355 Note that this will generally make installs run slower, and be much
357 noisier, but can be useful for debugging.
358 ignore-scripts
360 • Default: false
361 • Type: Boolean
363 If true, npm does not run scripts specified in package.json files.
366 Note that commands explicitly intended to run a particular script, such
368 as npm start, npm stop, npm restart, npm test, and npm run-script will
369 still run their intended script if ignore-scripts is set, but they will
370 not run any pre- or post-scripts.
371 workspace
373 • Default:
374 • Type: String (can be set multiple times)
376 Enable running a command in the context of the configured workspaces of
379 the current project while filtering by running only the workspaces de‐
380 fined by this configuration option.
381 Valid values for the workspace config are either:
383 • Workspace names
385 • Path to a workspace directory
387 • Path to a parent workspace directory (will result in selecting all
389 workspaces within that folder)
390 When set for the npm init command, this may be set to the folder of a
393 workspace which does not yet exist, to create the folder and set it up
394 as a brand new workspace within the project.
395 This value is not exported to the environment for child processes.
397 workspaces
399 • Default: null
400 • Type: null or Boolean
402 Set to true to run the command in the context of all configured
405 workspaces.
406 Explicitly setting this to false will cause commands like install to
408 ignore workspaces altogether. When not set explicitly:
409 • Commands that operate on the node_modules tree (install, update,
411 etc.) will link workspaces into the node_modules folder. - Commands
412 that do other things (test, exec, publish, etc.) will operate on the
413 root project, unless one or more workspaces are specified in the
414 workspace config.
415 This value is not exported to the environment for child processes.
418 include-workspace-root
420 • Default: false
421 • Type: Boolean
423 Include the workspace root when workspaces are enabled for a command.
426 When false, specifying individual workspaces via the workspace config,
428 or all workspaces via the workspaces flag, will cause npm to operate
429 only on the specified workspaces, and not on the root project.
430 This value is not exported to the environment for child processes.
432 install-links
434 • Default: false
435 • Type: Boolean
437 When set file: protocol dependencies that exist outside of the project
440 root will be packed and installed as regular dependencies instead of
441 creating a symlink. This option has no effect on workspaces.
442 See Also
444 • npm help install
445 • npm help config
447 September 2022 NPM-AUDIT(1)