How to check an npm package for malware before installing it
To check an npm package for malware, look before you install and audit after. Before: read what the package is with npm view, see whether it runs install scripts, and prefer versions that have been public for some days. After: verify signatures, then run npm audit against your lockfile, the file where npm records the exact version of every package. No single step proves a package safe. A failed check is a reason to stop and read.
Most of the damage in the npm incidents began at one moment: an install that ran a script. A few commands before that moment cost almost nothing. If you want to check an npm package for malware without reading its whole source, these are the cheapest steps. This page is the order that takes the least time. Steps 1 to 4 happen before the install. Steps 5 to 7 check what is already on your machine. The history behind it is on npm supply chain attack, and the signs of a bad package are on npm malware.
01How to check an npm package for malware: the list
| Step | When | What to run or look at | What it tells you |
|---|---|---|---|
| 1 | Before install | npm view | What the package is and what it depends on |
| 2 | Before install | The install scripts | Whether it runs code on install |
| 3 | Before install | Version age | Whether the version has been public for some days |
| 4 | Before install | Provenance | Where the build came from |
| 5 | After install | npm audit signatures | Whether registry signatures verify |
| 6 | After install | npm audit | Known vulnerabilities in your dependencies |
| 7 | After install | Your lockfile | Which package versions changed |
02Before install, step 1: look at the package with npm view
npm view shows data about a package and prints it to the terminal. Add a field name to see only that field. For example:
npm view ronn@0.3.5 dependenciesUse the same form with the package and version you are about to add. Read the dependency list. A small utility that pulls in many packages you do not recognize deserves a second look. Then ask three plain questions. Did you choose this name yourself? Is it spelled the way the real project spells it? Does it match what the real project's README tells you to install? An assistant can suggest a name that does not exist, and an attacker can register it. That case is covered in slopsquatting, and lookalike spellings in typosquatting.
03Before install, step 2: read the install scripts
npm 11 runs preinstall, install and postinstall after it places the modules in node_modules, in order. npm 12 blocks dependency install scripts by default until you approve them; npm 11 still runs them by default. You can read the scripts without installing: npm view takes any field name after the package and version, so put scripts where dependencies is:
npm view <package>@<version> scriptsA line such as postinstall means the package runs code on install. Shai-Hulud's poisoned versions carried a post-install script that harvested sensitive data.
If you do not need scripts, set the npm option ignore-scripts to true. Then npm does not run scripts specified in package.json files. npm config files such as ~/.npmrc are lists of key = value lines, so the line is:
ignore-scripts = trueTest your build afterwards, because some legitimate packages need their scripts. The setting is described in npm's config docs.
04Before install, step 3: let the version age
A brand-new version is the one nobody has had time to inspect. The npm option min-release-age builds the dependency tree so that only versions available for more than a given number of days are installed. It sits on the same config page, which gives this line as its example:
min-release-age = 7The number is days. Waiting a few days costs you little.
05Before install, step 4: look for provenance
Provenance is a public link from a package to its source code and its build instructions. It is signed through Sigstore, a public signing service, and logged in a public record that anyone can view. Publishing with provenance requires a cloud-hosted runner from a supported CI/CD provider, such as GitHub Actions or GitLab CI/CD. So a package built elsewhere has none to show. To check, open the package on npmjs.com and look for a green check mark in the Version field to the right of the README. Click it, then View more details. There you see the source commit the package was built from.
Provenance tells you where a build came from. It does not guarantee that the package has no malicious code.
06After install, step 5: verify signatures
npm audit signatures verifies the registry signatures of installed packages. Run it in the project folder after the install:
npm audit signaturesThe CLI errors if a package lacks a signature on a registry that supports them. That could mean an attacker is trying to get around verification. Treat that error as a stop sign.
07After install, step 6: how to check npm package vulnerabilities with npm audit
npm audit sends a description of your project's dependencies to your default registry. It asks for a report of known vulnerabilities. Run it from the project folder:
npm auditBy default it exits with a non-zero code if it finds any vulnerability. The --audit-level option sets the minimum level for that, which is handy in CI, the automatic test run on a server. It needs a package-lock or shrinkwrap file by default. You can run it with --no-package-lock, but the results can differ from run to run.
Keep in mind what the command is: a list of known vulnerabilities. It is not a malware scanner. A package that was poisoned an hour ago has no entry yet, so use it as one layer.
08After install, step 7: keep a lockfile, and read its diff
The lockfile is package-lock.json, written by npm. It lists the exact version of each package your project installed, and npm audit depends on it. Commit it. When an update changes it, read the diff, the list of changed lines, like code. A new package you did not ask for, or a version that jumped, needs an answer before you merge.
Agents make this more important. Auto mode in Claude Code allows installing dependencies declared in your lock files or manifests by default. What the lockfile lists can be installed without a prompt.
09Agents and installs
If an agent adds packages for you, the checks above belong at the moment it proposes a new name. In Claude Code, the rule Bash(npm run *) matches npm run build and npm run test but not npm install. So allowing build and test commands does not allow installs. Rule syntax is on the permissions page.
10When a check fails
Stop and do not install. Write down the name and version, and look the package up again from a clean terminal. Do not paste the install command back in to see what happens.
If the package already ran on your machine, use one order. First look for the file ~/Library/LaunchAgents/com.user.gh-token-monitor.plist. The Mini Shai-Hulud variant installs it, and its program tries to run rm -rf ~/ when the GitHub token it checks is revoked. If the file is there, don't revoke GitHub tokens yet, from any device. Stop the program first with launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.user.gh-token-monitor.plist, then delete that file, or wait until it exits after 24 hours. Only then revoke; the Shai-Hulud page has the steps. If the file is not there, go straight on. Then treat the secrets the package could reach as copied and replace credentials and sessions from a clean device, one that never installed the package, following leaked API key. A repo someone sent you needs its own check: malware in GitHub repositories. Python packages have their own page, PyPI malware.
Run the whole list each time you check an npm package for malware, and keep it short enough that you will actually do it. Reading npm view output takes a minute. Finding out later that a script ran takes a day of replacing keys, so the order is worth keeping.
To have lockfiles checked for you, the free, open-source core of Artificial Immunity checks npm, pnpm and Cargo lockfiles against public lists of known vulnerabilities and reports what it finds.
FAQ
How to check npm installed packages?
Run npm audit signatures. It verifies the registry signatures of the packages you have installed. The CLI errors if packages lack signatures on a registry that supports them, which could mean an attacker is trying to get around verification.
How to check malware virus on a Mac?
This page covers one source of malware, npm packages. For a Mac-wide question, use the infostealer check, which lists signs and the steps to take.
Does npm audit find malware?
It reports known vulnerabilities. It is not a malware scanner, so pair it with the other checks on this page.
Can a package with provenance still be bad?
Yes. Provenance links a package to its source code and build instructions, but it does not guarantee that the package has no malicious code.
Can I check a package before I install it?
Yes. npm view shows data about a package without installing it, and you can read its install scripts the same way.
Related guides
Sources
- npm docs, npm view
- npm docs, npm audit
- npm docs, verifying registry signatures
- npm docs, generating provenance statements
- npm docs, scripts
- npm docs, config
- Wiz, Shai-Hulud
- Wiz, Mini Shai-Hulud
- Socket, nodejs-smtp impersonating nodemailer
- Socket, slopsquatting
- Claude Code docs, permission modes
- Artificial Immunity