174 lines
4.4 KiB
Groff
174 lines
4.4 KiB
Groff
|
.TH "NPM\-AUDIT" "1" "November 2019" "" ""
|
||
|
|
.SH "NAME"
|
||
|
|
\fBnpm-audit\fR \- Run a security audit
|
||
|
|
.SS Synopsis
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
npm audit [\-\-json|\-\-parseable|\-\-audit\-level=(low|moderate|high|critical)]
|
||
|
|
npm audit fix [\-\-force|\-\-package\-lock\-only|\-\-dry\-run]
|
||
|
|
|
||
|
|
common options: [\-\-production] [\-\-only=(dev|prod)]
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.SS Examples
|
||
|
|
.P
|
||
|
|
Scan your project for vulnerabilities and automatically install any compatible
|
||
|
|
updates to vulnerable dependencies:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit fix
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
Run \fBaudit fix\fP without modifying \fBnode_modules\fP, but still updating the
|
||
|
|
pkglock:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit fix \-\-package\-lock\-only
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
Skip updating \fBdevDependencies\fP:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit fix \-\-only=prod
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
Have \fBaudit fix\fP install semver\-major updates to toplevel dependencies, not just
|
||
|
|
semver\-compatible ones:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit fix \-\-force
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
Do a dry run to get an idea of what \fBaudit fix\fP will do, and \fIalso\fR output
|
||
|
|
install information in JSON format:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit fix \-\-dry\-run \-\-json
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
Scan your project for vulnerabilities and just show the details, without fixing
|
||
|
|
anything:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
Get the detailed audit report in JSON format:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit \-\-json
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
Get the detailed audit report in plain text result, separated by tab characters, allowing for
|
||
|
|
future reuse in scripting or command line post processing, like for example, selecting
|
||
|
|
some of the columns printed:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit \-\-parseable
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
To parse columns, you can use for example \fBawk\fP, and just print some of them:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit \-\-parseable | awk \-F $'\\t' '{print $1,$4}'
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
Fail an audit only if the results include a vulnerability with a level of moderate or higher:
|
||
|
|
.P
|
||
|
|
.RS 2
|
||
|
|
.nf
|
||
|
|
$ npm audit \-\-audit\-level=moderate
|
||
|
|
.fi
|
||
|
|
.RE
|
||
|
|
.SS Description
|
||
|
|
.P
|
||
|
|
The audit command submits a description of the dependencies configured in
|
||
|
|
your project to your default registry and asks for a report of known
|
||
|
|
vulnerabilities\. The report returned includes instructions on how to act on
|
||
|
|
this information\. The command will exit with a 0 exit code if no
|
||
|
|
vulnerabilities were found\.
|
||
|
|
.P
|
||
|
|
You can also have npm automatically fix the vulnerabilities by running \fBnpm
|
||
|
|
audit fix\fP\|\. Note that some vulnerabilities cannot be fixed automatically and
|
||
|
|
will require manual intervention or review\. Also note that since \fBnpm audit fix\fP
|
||
|
|
runs a full\-fledged \fBnpm install\fP under the hood, all configs that apply to the
|
||
|
|
installer will also apply to \fBnpm install\fP \-\- so things like \fBnpm audit fix
|
||
|
|
\-\-package\-lock\-only\fP will work as expected\.
|
||
|
|
.P
|
||
|
|
By default, the audit command will exit with a non\-zero code if any vulnerability
|
||
|
|
is found\. It may be useful in CI environments to include the \fB\-\-audit\-level\fP parameter
|
||
|
|
to specify the minimum vulnerability level that will cause the command to fail\. This
|
||
|
|
option does not filter the report output, it simply changes the command's failure
|
||
|
|
threshold\.
|
||
|
|
.SS Content Submitted
|
||
|
|
.RS 0
|
||
|
|
.IP \(bu 2
|
||
|
|
npm_version
|
||
|
|
.IP \(bu 2
|
||
|
|
node_version
|
||
|
|
.IP \(bu 2
|
||
|
|
platform
|
||
|
|
.IP \(bu 2
|
||
|
|
node_env
|
||
|
|
.IP \(bu 2
|
||
|
|
A scrubbed version of your package\-lock\.json or npm\-shrinkwrap\.json
|
||
|
|
|
||
|
|
.RE
|
||
|
|
.SS Scrubbing
|
||
|
|
.P
|
||
|
|
In order to ensure that potentially sensitive information is not included in
|
||
|
|
the audit data bundle, some dependencies may have their names (and sometimes
|
||
|
|
versions) replaced with opaque non\-reversible identifiers\. It is done for
|
||
|
|
the following dependency types:
|
||
|
|
.RS 0
|
||
|
|
.IP \(bu 2
|
||
|
|
Any module referencing a scope that is configured for a non\-default
|
||
|
|
registry has its name scrubbed\. (That is, a scope you did a \fBnpm login \-\-scope=@ourscope\fP for\.)
|
||
|
|
.IP \(bu 2
|
||
|
|
All git dependencies have their names and specifiers scrubbed\.
|
||
|
|
.IP \(bu 2
|
||
|
|
All remote tarball dependencies have their names and specifiers scrubbed\.
|
||
|
|
.IP \(bu 2
|
||
|
|
All local directory and tarball dependencies have their names and specifiers scrubbed\.
|
||
|
|
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
The non\-reversible identifiers are a sha256 of a session\-specific UUID and the
|
||
|
|
value being replaced, ensuring a consistent value within the payload that is
|
||
|
|
different between runs\.
|
||
|
|
.SS Exit Code
|
||
|
|
.P
|
||
|
|
The \fBnpm audit\fP command will exit with a 0 exit code if no vulnerabilities were found\.
|
||
|
|
.P
|
||
|
|
If vulnerabilities were found the exit code will depend on the \fBaudit\-level\fP
|
||
|
|
configuration setting\.
|
||
|
|
.SS See Also
|
||
|
|
.RS 0
|
||
|
|
.IP \(bu 2
|
||
|
|
npm help install
|
||
|
|
.IP \(bu 2
|
||
|
|
npm help package\-locks
|
||
|
|
.IP \(bu 2
|
||
|
|
npm help config
|
||
|
|
|
||
|
|
.RE
|