Get the free coreGet core

How to check an npm package for malware before installing it

Updated 6 min readSection 05 / Threats
SHORT ANSWER

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

StepWhenWhat to run or look atWhat it tells you
1Before installnpm viewWhat the package is and what it depends on
2Before installThe install scriptsWhether it runs code on install
3Before installVersion ageWhether the version has been public for some days
4Before installProvenanceWhere the build came from
5After installnpm audit signaturesWhether registry signatures verify
6After installnpm auditKnown vulnerabilities in your dependencies
7After installYour lockfileWhich 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 dependencies

Use 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> scripts

A 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 = true

Test 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 = 7

The 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 signatures

The 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 audit

By 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.

Sources

  1. npm docs, npm view
  2. npm docs, npm audit
  3. npm docs, verifying registry signatures
  4. npm docs, generating provenance statements
  5. npm docs, scripts
  6. npm docs, config
  7. Wiz, Shai-Hulud
  8. Wiz, Mini Shai-Hulud
  9. Socket, nodejs-smtp impersonating nodemailer
  10. Socket, slopsquatting
  11. Claude Code docs, permission modes
  12. Artificial Immunity
Installing packages with an agent on your Mac? Artificial Immunity watches the Mac where your agents work.Get the free core