npm audit

How npm audit works

npm audit sends a description of your project's dependencies to your default registry and asks for known vulnerabilities. It needs a package-lock.json or shrinkwrap file, because that is how it knows which versions you have. See the npm docs for the details.

npm audit                       # report everything
npm audit --omit=dev            # skip dev dependencies
npm audit --audit-level=high    # fail only on high or critical
npm audit --json                # machine-readable output

How to read the report

• Severity comes from the advisory. It says how bad the flaw is in general, not how bad it is for you.
• The dependency path shows what pulled the package in. Most findings are transitive dependencies, and the fix is usually in the package above.
• Dev or production. A flaw in a test tool does not ship to users, though it still runs in your build, so do not ignore it entirely.

If you get a long list, start with what is exploited and what ships. See how to prioritize vulnerabilities.

npm audit fix, and when not to force it

Command	What it does	Risk
npm audit fix	Applies compatible updates within your version ranges	Low. Run your tests anyway, because it runs a full install
npm audit fix --force	Also allows changes outside your ranges, including major versions	High. It can break your application, and npm says not to use it without a clear idea of what you want

If a fix is not available, you can upgrade the parent package, or use the overrides field in package.json to force a patched transitive version. Test it, because the parent package was not built against that version.

Running npm audit in CI

By default, npm audit exits with a non-zero code when it finds anything, which fails the job on every low-severity advisory. Teams usually set a threshold. Note that --audit-level only changes the failure threshold and does not filter the report.

- run: npm ci
- run: npm audit --omit=dev --audit-level=high

A check like this can also fail a build with no code change, because a new advisory was published overnight. Decide who owns that failure before you turn it on. For more, see where to run SCA scans.

What npm audit misses

• Anything outside npm. Your base image, operating system packages, Python tools and GitHub Actions are not in package-lock.json.
• Code fetched during install. Install scripts can download files that no lockfile records. See what a lockfile does not record.
• New malicious packages. It matches published advisories, so a package with no advisory yet passes clean.
• What already shipped. It reports on the project in front of it. A new advisory for last year's release only shows up if someone reruns it on that version.
• Whether you are affected. It does not know if your code uses the vulnerable function. Reachability analysis addresses that.

npm audit signatures is a separate command that verifies registry signatures and provenance attestations of the packages you installed. It checks where a package came from, not whether it is safe.

npm audit and CRACI

Keep running npm audit on pull requests. It is free and catches known issues early. CRACI covers what it cannot see: as your GitHub Actions runner, it records every package each job actually fetched from npm and every other source, including packages restored from CI caches and files fetched by install hooks. It then keeps checking the SBOM of what shipped as new vulnerabilities are published. See the best SCA tools or build-time SBOM generation.

npm audit: frequently asked questions

What does npm audit do?

It sends a description of your dependencies to the npm registry, checks them against known security advisories and reports any vulnerable packages, with their severity and how they got into your project.

Is npm audit fix safe?

Plain npm audit fix is usually safe, because it stays within your version ranges, but run your tests afterward. npm audit fix --force can install new major versions and break your application.

Why does npm audit show so many vulnerabilities?

Most come from transitive dependencies and dev tooling. Use --omit=dev to focus on what ships, and prioritize by exploitation and exposure rather than the count.

How do you ignore a vulnerability in npm audit?

npm audit has no built-in ignore list. Teams use the overrides field to change the version, a threshold with --audit-level, or a wrapper tool that records accepted findings.

Does npm audit need a lockfile?

Yes, by default it needs package-lock.json or a shrinkwrap file. You can bypass that with --no-package-lock, but results may then differ between runs.

Does npm audit detect malware?

Only once an advisory has been published for the package. A new malicious package has no advisory, so it will not be reported on the day it appears.