How to Run a Security Audit with npm audit

Last update on July 16 2024 13:05:10 (UTC/GMT +8 hours)

In the last tutorial we differentiated between modules and packages, we also covered how to prevent permission errors.

The tutorial you are about to read will teach you how to work with security audit.

About security audits

A security audit is an assessment of a package dependencies for security vulnerabilities. Security audits will help you to protect your packages user by enabling you to find and known vulnerabilities which can cause data loss, service outages, unauthorized access to sensitive information, or any other issue.

Running a security audit using npm audit

It should be noted that the npm audit command is available in npm@6. If you want to upgrade, you have to run npm install npm@latest -g.

The npm audit command will submit a description of the dependencies configured in your packages to your default registry and then requests for a report of known vulnerabilities. npm audit will check direct dependencies, devDependencies, bundledDependencies, and optionalDependencies, but it will not check peerDependencies.

Npm audit runs automatically, when you install a package with npm install. You can run npm audit manually on your locally installed packages as well, so as to conduct a security audit of the package and produce a report of its dependency vulnerabilities and, suggested patches if it is available.

On your command line, you should navigate to your package directory by typing cd path/to/your-package-name and pressing Enter.
You should ensure that your package contains package.json and package-lock.json files.
Then type npm audit and press Enter.
Finally, you should review the audit report and run recommended commands or investigate further if it is needed.

Resolving EAUDITNOPJSON and EAUDITNOLOCK errors

npm audit expects all packages to have package.json and package-lock.json files.

If you receive an EAUDITNOPJSON error, you should create a package.json file by following the steps in "Working with package.json".
If you receive an EAUDITNOLOCK error, you should make sure your package has a package.json file, then create the package lock file. You can do this by running npm i --package-lock-only.

How to review and act on the security audit report

Running npm audit produces a report of security vulnerabilities with the affected package name, vulnerability severity and description, path, and other information, and, when available, commands to apply patches to resolve vulnerabilities.

Security vulnerabilities found with suggested updates

In the case where security vulnerabilities are found and there are updates available, it is either:

You run the npm audit fix subcommand to automatically install compatible updates to vulnerable dependencies. or
You run the recommended commands individually to install updates to vulnerable dependencies. (Some updates might be semver-breaking changes.)

SEMVER warnings

In cases where the recommended action is a potential breaking change (semantic version major change), it will trigger a SEMVER WARNING. If the package that has the vulnerability has changed its API, you may have to make additional changes to your package's code.

Security vulnerabilities found requiring manual review

In there are no patches for the security vulnerabilities found, the audit report provides you with information about the vulnerability so that you can investigate further.

If you need to address the vulnerability, you can:

Check for mitigating factors
Update dependent packages if there is a fix
Fix the vulnerability
Open an issue in the package or dependent package issue tracker

Check for mitigating factors

You can review the security advisory in the "More info" field for mitigating factors that can allow you to continue using the package with the vulnerability in limited cases. For instance, the vulnerability may exist only when the code is used on specific operating systems, or when you call a specific function.

Update dependent packages if a fix exists

If a there is an available fix but packages that depend on the package with the vulnerability are not yet updated to include the fixed version, you can then open a pull or merge request on the dependent package repository to use the fixed version.

To find the package that should be updated, check the "Path" field for the location of the package that has the vulnerability, then check for the package that depends on it. For example, take for example, the case where the path to the vulnerability is @package-name > dependent-package > package-with-vulnerability, you will have to update dependent-package.
Go to npm public registry, find and select the dependent package and navigate to its repository.
In the repository of the dependent package, open a pull or merge request so as to update the version of the vulnerable package to a version with a fix.
After the pull or merge request has been merged and the package is updated in the npm public registry, you should update your copy of the package with npm update.

Fix the vulnerability

In the case where there is no fix, you may can suggest changes that address the vulnerability to the package maintainer in a merge or pull request on the package repository.

You should check the "Path" field for the location of the vulnerability.
Go to npm public registry, find and select the dependent package and navigate to its repository.
Open a pull or merge request in the package repository, to make the fix on the package repository.
After the fix is merged and the package is updated in the npm public registry, you should update your copy of the package that depends on the package with the fix.

Open an issue in the package or dependent package issue tracker

In the case where you neither want to fix the vulnerability nor update the dependent package yourself, you should open an issue in the package or dependent package issue tracker.

Go to the npm public registry, and find the package with the vulnerability or the dependent package that should be updated.
You should open an issue in the package and dependent package issue tracker, and include information from the audit report, including the vulnerability report that is from the "More info" field.

No security vulnerabilities found

If you don't find any security vulnerabilities, it means that packages with known vulnerabilities were not found in your package dependency tree. Since the advisory database can receive update at any time, it is recommended that you regularly run npm audit manually, or add npm audit to your continuous integration process.

Turning off npm audit on package installation

Installing a single package

If you want to turn off npm audit while installing a single package, you should use the --no-audit flag:

npm install example-package-name --no-audit

Installing all packages

If you want to turn off npm audit when installing all packages, you should set the audit setting to false in your user and global npmrc config files:

npm set audit false

Previous: Understanding packages and modules and preventing permissions errors
Next: Understanding Audit Reports and Requiring Two-Factor Authentication for Package Publishing and Settings Modification