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 pro‐
16 vided, 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 Package lock
34 By default npm requires a package-lock or shrinkwrap in order to run
35 the audit. You can bypass the package lock with --no-package-lock but
36 be aware the results may be different with every run, since npm will
37 re-build the dependency tree each time.
38 Audit Signatures
40 To ensure the integrity of packages you download from the public npm
41 registry, or any registry that supports signatures, you can verify the
42 registry signatures of downloaded packages using the npm CLI.
43 Registry signatures can be verified using the following audit command:
45 $ npm audit signatures
47 The npm CLI supports registry signatures and signing keys provided by
49 any registry if the following conventions are followed:
50 1. Signatures are provided in the package's packument in each pub‐
52 lished version within the dist object:
53 "dist":{
56 "..omitted..": "..omitted..",
57 "signatures": [{
58 "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
59 "sig": "a312b9c3cb4a1b693e8ebac5ee1ca9cc01f2661c14391917dcb111517f72370809..."
60 }]
61 }
62 See this example ⟨https://registry.npmjs.org/light-cycle/1.4.3⟩ of a
64 signed package from the public npm registry.
65 The sig is generated using the following template: ${pack‐
67 age.name}@${package.version}:${package.dist.integrity} and the keyid
68 has to match one of the public signing keys below.
69 2. Public signing keys are provided at registry-host.tld/-/npm/v1/keys
71 in the following format:
72 {
75 "keys": [{
76 "expires": null,
77 "keyid": "SHA256:{{SHA256_PUBLIC_KEY}}",
78 "keytype": "ecdsa-sha2-nistp256",
79 "scheme": "ecdsa-sha2-nistp256",
80 "key": "{{B64_PUBLIC_KEY}}"
81 }]
82 }
83 Keys response:
85 • expires: null or a simplified extended ISO 8601 format
87 ⟨https://en.wikipedia.org/wiki/ISO_8601"⟩: YYYY-MM-DDTHH:mm:ss.sssZ
88 • keydid: sha256 fingerprint of the public key
90 • keytype: only ecdsa-sha2-nistp256 is currently supported by the npm
92 CLI
93 • scheme: only ecdsa-sha2-nistp256 is currently supported by the npm
95 CLI
96 • key: base64 encoded public key
98 See this example key's response from the public npm registry
101 ⟨https://registry.npmjs.org/-/npm/v1/keys"⟩.
102 Audit Endpoints
104 There are two audit endpoints that npm may use to fetch vulnerability
105 information: the Bulk Advisory endpoint and the Quick Audit endpoint.
106 Bulk Advisory Endpoint
108 As of version 7, npm uses the much faster Bulk Advisory endpoint to op‐
109 timize the speed of calculating audit results.
110 npm will generate a JSON payload with the name and list of versions of
112 each package in the tree, and POST it to the default configured reg‐
113 istry at the path /-/npm/v1/security/advisories/bulk.
114 Any packages in the tree that do not have a version field in their
116 package.json file will be ignored. If any --omit options are specified
117 (either via the --omit config ⟨/using-npm/config#omit⟩, or one of the
118 shorthands such as --production, --only=dev, and so on), then packages
119 will be omitted from the submitted payload as appropriate.
120 If the registry responds with an error, or with an invalid response,
122 then npm will attempt to load advisory data from the Quick Audit end‐
123 point.
124 The expected result will contain a set of advisory objects for each de‐
126 pendency that matches the advisory range. Each advisory object contains
127 a name, url, id, severity, vulnerable_versions, and title.
128 npm then uses these advisory objects to calculate vulnerabilities and
130 meta-vulnerabilities of the dependencies within the tree.
131 Quick Audit Endpoint
133 If the Bulk Advisory endpoint returns an error, or invalid data, npm
134 will attempt to load advisory data from the Quick Audit endpoint, which
135 is considerably slower in most cases.
136 The full package tree as found in package-lock.json is submitted, along
138 with the following pieces of additional metadata:
139 • npm_version
141 • node_version
143 • platform
145 • arch
147 • node_env
149 All packages in the tree are submitted to the Quick Audit endpoint.
152 Omitted dependency types are skipped when generating the report.
153 Scrubbing
155 Out of an abundance of caution, npm versions 5 and 6 would "scrub" any
156 packages from the submitted report if their name contained a / charac‐
157 ter, so as to avoid leaking the names of potentially private packages
158 or git URLs.
159 However, in practice, this resulted in audits often failing to properly
161 detect meta-vulnerabilities, because the tree would appear to be in‐
162 valid due to missing dependencies, and prevented the detection of vul‐
163 nerabilities in package trees that used git dependencies or private
164 modules.
165 This scrubbing has been removed from npm as of version 7.
167 Calculating Meta-Vulnerabilities and Remediations
169 npm uses the @npmcli/metavuln-calculator ⟨http://npm.im/@npm‐
170 cli/metavuln-calculator⟩ module to turn a set of security advisories
171 into a set of "vulnerability" objects. A "meta-vulnerability" is a de‐
172 pendency that is vulnerable by virtue of dependence on vulnerable ver‐
173 sions of a vulnerable package.
174 For example, if the package foo is vulnerable in the range >=1.0.2
176 <2.0.0, and the package bar depends on foo@^1.1.0, then that version of
177 bar can only be installed by installing a vulnerable version of foo. In
178 this case, bar is a "metavulnerability".
179 Once metavulnerabilities for a given package are calculated, they are
181 cached in the ~/.npm folder and only re-evaluated if the advisory range
182 changes, or a new version of the package is published (in which case,
183 the new version is checked for metavulnerable status as well).
184 If the chain of metavulnerabilities extends all the way to the root
186 project, and it cannot be updated without changing its dependency
187 ranges, then npm audit fix will require the --force option to apply the
188 remediation. If remediations do not require changes to the dependency
189 ranges, then all vulnerable packages will be updated to a version that
190 does not have an advisory or metavulnerability posted against it.
191 Exit Code
193 The npm audit command will exit with a 0 exit code if no vulnerabili‐
194 ties were found. The npm audit fix command will exit with 0 exit code
195 if no vulnerabilities are found or if the remediation is able to suc‐
196 cessfully fix all vulnerabilities.
197 If vulnerabilities were found the exit code will depend on the audit-
199 level config ⟨/using-npm/config#audit-level⟩.
200 Examples
202 Scan your project for vulnerabilities and automatically install any
203 compatible updates to vulnerable dependencies:
204 $ npm audit fix
206 Run audit fix without modifying node_modules, but still updating the
208 pkglock:
209 $ npm audit fix --package-lock-only
211 Skip updating devDependencies:
213 $ npm audit fix --only=prod
215 Have audit fix install SemVer-major updates to toplevel dependencies,
217 not just SemVer-compatible ones:
218 $ npm audit fix --force
220 Do a dry run to get an idea of what audit fix will do, and also output
222 install information in JSON format:
223 $ npm audit fix --dry-run --json
225 Scan your project for vulnerabilities and just show the details, with‐
227 out fixing anything:
228 $ npm audit
230 Get the detailed audit report in JSON format:
232 $ npm audit --json
234 Fail an audit only if the results include a vulnerability with a level
236 of moderate or higher:
237 $ npm audit --audit-level=moderate
239 Configuration
241 audit-level
242 • Default: null
243 • Type: null, "info", "low", "moderate", "high", "critical", or
245 "none"
246 The minimum level of vulnerability for npm audit to exit with a non-
249 zero exit code.
250 dry-run
252 • Default: false
253 • Type: Boolean
255 Indicates that you don't want npm to make any changes and that it
258 should only report what it would have done. This can be passed into any
259 of the commands that modify your local installation, eg, install, up‐
260 date, dedupe, uninstall, as well as pack and publish.
261 Note: This is NOT honored by other network related commands, eg dist-
263 tags, owner, etc.
264 force
266 • Default: false
267 • Type: Boolean
269 Removes various protections against unfortunate side effects, common
272 mistakes, unnecessary performance degradation, and malicious input.
273 • Allow clobbering non-npm files in global installs.
275 • Allow the npm version command to work on an unclean git repository.
277 • Allow deleting the cache folder with npm cache clean.
279 • Allow installing packages that have an engines declaration requir‐
281 ing a different version of npm.
282 • Allow installing packages that have an engines declaration requir‐
284 ing a different version of node, even if --engine-strict is en‐
285 abled.
286 • Allow npm audit fix to install modules outside your stated depen‐
288 dency range (including SemVer-major changes).
289 • Allow unpublishing all versions of a published package.
291 • Allow conflicting peerDependencies to be installed in the root
293 project.
294 • Implicitly set --yes during npm init.
296 • Allow clobbering existing values in npm pkg
298 • Allow unpublishing of entire packages (not just a single version).
300 If you don't have a clear idea of what you want to do, it is strongly
303 recommended that you do not use this option!
304 json
306 • Default: false
307 • Type: Boolean
309 Whether or not to output JSON data, rather than the normal output.
312 • In npm pkg set it enables parsing set values with JSON.parse() be‐
314 fore saving them to your package.json.
315 Not supported by all npm commands.
318 package-lock-only
320 • Default: false
321 • Type: Boolean
323 If set to true, the current operation will only use the package-
326 lock.json, ignoring node_modules.
327 For update this means only the package-lock.json will be updated, in‐
329 stead of checking node_modules and downloading dependencies.
330 For list this means the output will be based on the tree described by
332 the package-lock.json, rather than the contents of node_modules.
333 package-lock
335 • Default: true
336 • Type: Boolean
338 If set to false, then ignore package-lock.json files when installing.
341 This will also prevent writing package-lock.json if save is true.
342 omit
344 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
345 duction', otherwise empty.
346 • Type: "dev", "optional", or "peer" (can be set multiple times)
348 Dependency types to omit from the installation tree on disk.
351 Note that these dependencies are still resolved and added to the pack‐
353 age-lock.json or npm-shrinkwrap.json file. They are just not physically
354 installed on disk.
355 If a package type appears in both the --include and --omit lists, then
357 it will be included.
358 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
360 ment variable will be set to 'production' for all lifecycle scripts.
361 include
363 • Default:
364 • Type: "prod", "dev", "optional", or "peer" (can be set multiple
366 times)
367 Option that allows for defining which types of dependencies to install.
370 This is the inverse of --omit=<type>.
372 Dependency types specified in --include will not be omitted, regardless
374 of the order in which omit/include are specified on the command-line.
375 foreground-scripts
377 • Default: false
378 • Type: Boolean
380 Run all build scripts (ie, preinstall, install, and postinstall)
383 scripts for installed packages in the foreground process, sharing stan‐
384 dard input, output, and error with the main npm process.
385 Note that this will generally make installs run slower, and be much
387 noisier, but can be useful for debugging.
388 ignore-scripts
390 • Default: false
391 • Type: Boolean
393 If true, npm does not run scripts specified in package.json files.
396 Note that commands explicitly intended to run a particular script, such
398 as npm start, npm stop, npm restart, npm test, and npm run-script will
399 still run their intended script if ignore-scripts is set, but they will
400 not run any pre- or post-scripts.
401 workspace
403 • Default:
404 • Type: String (can be set multiple times)
406 Enable running a command in the context of the configured workspaces of
409 the current project while filtering by running only the workspaces de‐
410 fined by this configuration option.
411 Valid values for the workspace config are either:
413 • Workspace names
415 • Path to a workspace directory
417 • Path to a parent workspace directory (will result in selecting all
419 workspaces within that folder)
420 When set for the npm init command, this may be set to the folder of a
423 workspace which does not yet exist, to create the folder and set it up
424 as a brand new workspace within the project.
425 This value is not exported to the environment for child processes.
427 workspaces
429 • Default: null
430 • Type: null or Boolean
432 Set to true to run the command in the context of all configured
435 workspaces.
436 Explicitly setting this to false will cause commands like install to
438 ignore workspaces altogether. When not set explicitly:
439 • Commands that operate on the node_modules tree (install, update,
441 etc.) will link workspaces into the node_modules folder. - Commands
442 that do other things (test, exec, publish, etc.) will operate on
443 the root project, unless one or more workspaces are specified in
444 the workspace config.
445 This value is not exported to the environment for child processes.
448 include-workspace-root
450 • Default: false
451 • Type: Boolean
453 Include the workspace root when workspaces are enabled for a command.
456 When false, specifying individual workspaces via the workspace config,
458 or all workspaces via the workspaces flag, will cause npm to operate
459 only on the specified workspaces, and not on the root project.
460 This value is not exported to the environment for child processes.
462 install-links
464 • Default: false
465 • Type: Boolean
467 When set file: protocol dependencies will be packed and installed as
470 regular dependencies instead of creating a symlink. This option has no
471 effect on workspaces.
472 See Also
474 • npm help install
475 • npm help config
477 November 2023 NPM-AUDIT(1)