1NPM-AUDIT(1)                                                      NPM-AUDIT(1)
2
3
4

NAME

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
73npm_version
74
75node_version
76
77platform
78
79arch
80
81node_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)
Impressum