Check for Security Vulnerabilities in your Project's NPM Packages and Dependencies
A security audit is a process that assesses package dependencies for security vulnerabilities. Security audits help you protect those who use your packages by helping you find and fix known vulnerabilities in dependencies that could cause data loss, service outages, unauthorized access to sensitive information, or other issues.
The npm audit
command submits a description of the dependencies
configured in your project's package(s) to your project's built-in NPM
registry and asks for a report of known vulnerabilities. If any
vulnerabilities are found, the impact and appropriate remediation are
calculated. The audit report includes the affected package name,
vulnerability severity and description, path, and other information, and, if
available, commands to apply patches to resolve vulnerabilities.
- Run
npm audit fix
to apply remediations to the package tree automatically. - Run the recommended commands individually to manually install updates to vulnerable dependencies.
If there are no patches available for the identified vulnerabilities, the audit report will provide information about the vulnerability to help you investigate further.
If no security vulnerabilities were found, this means that packages
with known vulnerabilities were not found in your package dependency tree.
However, since the advisory database can be updated at any time, you should
regularly run npm audit
manually (see Run npm audit Manually), or add a build step with npm audit
to your continuous
integration process.
npm audit
automatically runs whenever you install a package with npm
install
but, if you prefer, you can turn off npm
audit
on package installation:
- To turn off
npm audit
when installing a single package, use the--no-audit
flag:npm install <package-name> --no-audit
- To turn off
npm audit
when installing all packages, set theaudit
setting tofalse
in your user and global npmrc config files:npm set audit false
Run npm audit Manually
npm audit
:
- On the command line, type
cd path/to/your-package-name
and navigate to your package directory, then press Enter. - Make sure that your package contains
package.json
andpackage-lock.json
files. - Type
npm audit
and press Enter. - Review the audit report and run the recommended commands or investigate further, if needed.
Understand npm audit Exit Codes
The npm audit
command exits with a 0 exit
code when no vulnerabilities are found or a non-zero code when any
vulnerability is found. The npm audit fix
command
exit with a 0 exit code if no vulnerabilities are found or if the
remediation is able to successfully fix all vulnerabilities. If
vulnerabilities are found, the exit code depends on the audit-level
configuration setting. In CI environments, you may want to include
the --audit-level
argument to specify the minimum
vulnerability level that will cause the command to fail. This option
doesn't filter the report output, it simply changes the command's
failure threshold.
Examples
$ npm audit
$ npm audit fix --dry-run --json
The
dry-run
option indicates that you don't
want NPM to make any changes and that it should only report what it
would have done. This can be passed into any of the commands that
modify your local installation, such as install, update, uninstall,
pack, and publish. The json
option indicates
whether or not to output JSON data, rather than the normal
output.
$ npm audit fix
$ npm audit --audit-level=moderate
The
audit-level
option indicates the minimum
level of vulnerability ("info", "low", "moderate", "high",
"critical", or "none") for npm audit
to exit with a
non-zero exit code.