@@ -17,118 +17,180 @@ npm audit fix [--force|--package-lock-only|--dry-run]
1717common options: [--production] [--only= (dev| prod)]
1818```
1919
20+ ### Description
21+
22+ The audit command submits a description of the dependencies configured in
23+ your project to your default registry and asks for a report of known
24+ vulnerabilities. If any vulnerabilities are found, then the impact and
25+ appropriate remediation will be calculated. If the ` fix ` argument is
26+ provided, then remediations will be applied to the package tree.
27+
28+ The command will exit with a 0 exit code if no vulnerabilities were found.
29+
30+ Note that some vulnerabilities cannot be fixed automatically and will
31+ require manual intervention or review. Also note that since `npm audit
32+ fix` runs a full-fledged ` npm install` under the hood, all configs that
33+ apply to the installer will also apply to ` npm install ` -- so things like
34+ ` npm audit fix --package-lock-only ` will work as expected.
35+
36+ By default, the audit command will exit with a non-zero code if any
37+ vulnerability is found. It may be useful in CI environments to include the
38+ ` --audit-level ` parameter to specify the minimum vulnerability level that
39+ will cause the command to fail. This option does not filter the report
40+ output, it simply changes the command's failure threshold.
41+
42+ ### Audit Endpoints
43+
44+ There are two audit endpoints that npm may use to fetch vulnerability
45+ information: the ` Bulk Advisory ` endpoint and the ` Quick Audit ` endpoint.
46+
47+ #### Bulk Advisory Endpoint
48+
49+ As of version 7, npm uses the much faster ` Bulk Advisory ` endpoint to
50+ optimize the speed of calculating audit results.
51+
52+ npm will generate a JSON payload with the name and list of versions of each
53+ package in the tree, and POST it to the default configured registry at
54+ the path ` /-/npm/v1/security/advisories/bulk ` .
55+
56+ Any packages in the tree that do not have a ` version ` field in their
57+ package.json file will be ignored. If any ` --omit ` options are specified
58+ (either via the ` --omit ` config, or one of the shorthands such as
59+ ` --production ` , ` --only=dev ` , and so on), then packages will be omitted
60+ from the submitted payload as appropriate.
61+
62+ If the registry responds with an error, or with an invalid response, then
63+ npm will attempt to load advisory data from the ` Quick Audit ` endpoint.
64+
65+ The expected result will contain a set of advisory objects for each
66+ dependency that matches the advisory range. Each advisory object contains
67+ a ` name ` , ` url ` , ` id ` , ` severity ` , ` vulnerable_versions ` , and ` title ` .
68+
69+ npm then uses these advisory objects to calculate vulnerabilities and
70+ meta-vulnerabilities of the dependencies within the tree.
71+
72+ #### Quick Audit Endpoint
73+
74+ If the ` Bulk Advisory ` endpoint returns an error, or invalid data, npm will
75+ attempt to load advisory data from the ` Quick Audit ` endpoint, which is
76+ considerably slower in most cases.
77+
78+ The full package tree as found in ` package-lock.json ` is submitted, along
79+ with the following pieces of additional metadata:
80+
81+ * ` npm_version `
82+ * ` node_version `
83+ * ` platform `
84+ * ` arch `
85+ * ` node_env `
86+
87+ All packages in the tree are submitted to the Quick Audit endpoint.
88+ Omitted dependency types are skipped when generating the report.
89+
90+ #### Scrubbing
91+
92+ Out of an abundance of caution, npm versions 5 and 6 would "scrub" any
93+ packages from the submitted report if their name contained a ` / ` character,
94+ so as to avoid leaking the names of potentially private packages or git
95+ URLs.
96+
97+ However, in practice, this resulted in audits often failing to properly
98+ detect meta-vulnerabilities, because the tree would appear to be invalid
99+ due to missing dependencies, and prevented the detection of vulnerabilities
100+ in package trees that used git dependencies or private modules.
101+
102+ This scrubbing has been removed from npm as of version 7.
103+
104+ #### Calculating Meta-Vulnerabilities and Remediations
105+
106+ npm uses the
107+ [ ` @npmcli/metavuln-calculator ` ] ( http://npm.im/@npmcli/metavuln-calculator )
108+ module to turn a set of security advisories into a set of "vulnerability"
109+ objects. A "meta-vulnerability" is a dependency that is vulnerable by
110+ virtue of dependence on vulnerable versions of a vulnerable package.
111+
112+ For example, if the package ` foo ` is vulnerable in the range `>=1.0.2
113+ <2.0.0` , and the package ` bar` depends on ` foo@^1.1.0`, then that version
114+ of ` bar ` can only be installed by installing a vulnerable version of ` foo ` .
115+ In this case, ` bar ` is a "metavulnerability".
116+
117+ Once metavulnerabilities for a given package are calculated, they are
118+ cached in the ` ~/.npm ` folder and only re-evaluated if the advisory range
119+ changes, or a new version of the package is published (in which case, the
120+ new version is checked for metavulnerable status as well).
121+
122+ If the chain of metavulnerabilities extends all the way to the root
123+ project, and it cannot be updated without changing its dependency ranges,
124+ then ` npm audit fix ` will require the ` --force ` option to apply the
125+ remediation. If remediations do not require changes to the dependency
126+ ranges, then all vulnerable packages will be updated to a version that does
127+ not have an advisory or metavulnerability posted against it.
128+
129+ ### Exit Code
130+
131+ The ` npm audit ` command will exit with a 0 exit code if no vulnerabilities
132+ were found. The ` npm audit fix ` command will exit with 0 exit code if no
133+ vulnerabilities are found _ or_ if the remediation is able to successfully
134+ fix all vulnerabilities.
135+
136+ If vulnerabilities were found the exit code will depend on the
137+ ` audit-level ` configuration setting.
138+
20139### Examples
21140
22141Scan your project for vulnerabilities and automatically install any compatible
23142updates to vulnerable dependencies:
143+
24144``` bash
25145$ npm audit fix
26146```
27147
28148Run ` audit fix ` without modifying ` node_modules ` , but still updating the
29149pkglock:
150+
30151``` bash
31152$ npm audit fix --package-lock-only
32153```
33154
34155Skip updating ` devDependencies ` :
156+
35157``` bash
36158$ npm audit fix --only=prod
37159```
38160
39- Have ` audit fix ` install semver-major updates to toplevel dependencies, not just
40- semver-compatible ones:
161+ Have ` audit fix ` install SemVer-major updates to toplevel dependencies, not
162+ just SemVer-compatible ones:
163+
41164``` bash
42165$ npm audit fix --force
43166```
44167
45168Do a dry run to get an idea of what ` audit fix ` will do, and _ also_ output
46169install information in JSON format:
170+
47171``` bash
48172$ npm audit fix --dry-run --json
49173```
50174
51- Scan your project for vulnerabilities and just show the details, without fixing
52- anything:
175+ Scan your project for vulnerabilities and just show the details, without
176+ fixing anything:
177+
53178``` bash
54179$ npm audit
55180```
56181
57182Get the detailed audit report in JSON format:
58- ``` bash
59- $ npm audit --json
60- ```
61-
62- Get the detailed audit report in plain text result, separated by tab characters, allowing for
63- future reuse in scripting or command line post processing, like for example, selecting
64- some of the columns printed:
65- ``` bash
66- $ npm audit --parseable
67- ```
68183
69- To parse columns, you can use for example ` awk ` , and just print some of them:
70184``` bash
71- $ npm audit --parseable | awk -F $' \t ' ' {print $1,$4} '
185+ $ npm audit --json
72186```
73187
74188Fail an audit only if the results include a vulnerability with a level of moderate or higher:
189+
75190``` bash
76191$ npm audit --audit-level=moderate
77192```
78193
79- ### Description
80-
81- The audit command submits a description of the dependencies configured in
82- your project to your default registry and asks for a report of known
83- vulnerabilities. The report returned includes instructions on how to act on
84- this information. The command will exit with a 0 exit code if no
85- vulnerabilities were found.
86-
87- You can also have npm automatically fix the vulnerabilities by running `npm
88- audit fix`. Note that some vulnerabilities cannot be fixed automatically and
89- will require manual intervention or review. Also note that since ` npm audit fix `
90- runs a full-fledged ` npm install ` under the hood, all configs that apply to the
91- installer will also apply to ` npm install ` -- so things like `npm audit fix
92- --package-lock-only` will work as expected.
93-
94- By default, the audit command will exit with a non-zero code if any vulnerability
95- is found. It may be useful in CI environments to include the ` --audit-level ` parameter
96- to specify the minimum vulnerability level that will cause the command to fail. This
97- option does not filter the report output, it simply changes the command's failure
98- threshold.
99-
100- ### Content Submitted
101-
102- * npm_version
103- * node_version
104- * platform
105- * node_env
106- * A scrubbed version of your package-lock.json or npm-shrinkwrap.json
107-
108- #### Scrubbing
109-
110- In order to ensure that potentially sensitive information is not included in
111- the audit data bundle, some dependencies may have their names (and sometimes
112- versions) replaced with opaque non-reversible identifiers. It is done for
113- the following dependency types:
114-
115- * Any module referencing a scope that is configured for a non-default
116- registry has its name scrubbed. (That is, a scope you did a ` npm login --scope=@ourscope ` for.)
117- * All git dependencies have their names and specifiers scrubbed.
118- * All remote tarball dependencies have their names and specifiers scrubbed.
119- * All local directory and tarball dependencies have their names and specifiers scrubbed.
120-
121- The non-reversible identifiers are a sha256 of a session-specific UUID and the
122- value being replaced, ensuring a consistent value within the payload that is
123- different between runs.
124-
125- ### Exit Code
126-
127- The ` npm audit ` command will exit with a 0 exit code if no vulnerabilities were found.
128-
129- If vulnerabilities were found the exit code will depend on the ` audit-level `
130- configuration setting.
131-
132194### See Also
133195
134196* [ npm install] ( /cli-commands/install )
0 commit comments