Skip to content

How do I check an npm package before installing it?

Run npm view <name> to see whether the package exists, who publishes it and when it was released, then compare the name with the package you meant. To automate the same checks, run npx ai-guard verify-deps <name>: it blocks names that don’t exist, removed malware and suspicious look-alikes, and warns on new, rarely downloaded, deprecated or very fresh releases.

By the AI Guard maintainers · Last updated · Applies to v1.4.7

By hand with npm view

npm view reads the package document from the registry without installing anything. Three things to look for:

  1. Does it exist? A name that was never published returns E404.
  2. Who publishes it, and is it a placeholder? A version ending in -security published by npm means npm removed the original package, usually for malware.
  3. Is it the name you meant? Compare it letter by letter with the popular package; crossenv is not cross-env.

A name that does not exist:

terminal
$ npm view ai-guard-demo-no-such-packagenpm error code E404npm error 404 Not Found - GET https://registry.npmjs.org/ai-guard-demo-no-such-package - Not foundnpm error 404npm error 404  'ai-guard-demo-no-such-package@*' is not in this registry.

A package npm removed and replaced with a placeholder:

terminal
$ npm view crossenv [email protected] | Proprietary | deps: none | versions: 4security holding packagehttps://github.com/npm/security-holder#readme maintainers:- npm <[email protected]> dist-tags:latest: 0.0.2-security

(Output trimmed: the dist lines are omitted.) For publish dates, npm view <name> time --json lists when each version was published; downloads are on the package's npmjs.com page.

Automatically with ai-guard verify-deps

verify-deps does those lookups for you and turns them into a verdict. Run it on names, on what a change adds, or on everything:

bash
npx ai-guard verify-deps lodash expresss   # packages you namenpx ai-guard verify-deps                   # dependencies added since HEADnpx ai-guard verify-deps --base main       # dependencies this branch addsnpx ai-guard verify-deps --all             # every dependency in the repository

Real output for four packages:

terminal
$ npx ai-guard verify-deps ai-guard-demo-no-such-package   AI GUARD   Dependencies  ·  1 package  ·  1 blocked  ·  0 warnings   command line          error  ai-guard-demo-no-such-package  "ai-guard-demo-no-such-package" does not exist on npm. AI assistants often invent package names, and anyone can register an invented name later. package-not-found
terminal
$ npx ai-guard verify-deps crossenv   AI GUARD   Dependencies  ·  1 package  ·  1 blocked  ·  0 warnings   command line          error  crossenv  npm removed the package published as "crossenv" (usually for malware) and replaced it with an empty placeholder. Did you mean "cross-env"? security-holding
terminal
$ npx ai-guard verify-deps expresss   AI GUARD   Dependencies  ·  1 package  ·  0 blocked  ·  1 warning   command line          warn   expresss  "expresss" looks like the popular package "express". Make sure it is the package you meant. lookalike-name
terminal
$ npx ai-guard verify-deps lodash   AI GUARD   Dependencies  ·  1 package  ·  0 blocked  ·  0 warnings   ✔  1 package checked, nothing to report

The first two exit with code 1 (blocked); expresss and lodash exit with 0. Add --fail-on warning to fail on warnings too. Exit code 2 means some packages could not be checked, for example with no network; a check that did not run is never a pass.

What is blocked and what is a warning

BlockedWarning
The package does not exist on npmLook-alike of a popular package that is established
The exact version or dist-tag does not existFirst published less than 30 days ago
npm replaced it with a security placeholderFewer than 100 downloads last week
Look-alike of a popular package that is new or rarely downloadedRuns an install script
Install script on a new or rarely downloaded packageDeprecated
The version was published in the last 24 hours

The thresholds are options: --min-age (days), --min-downloads (per week) and --fresh-hours. More on the package checks page.

Limits

  • Blocking only on facts means some malicious packages pass with a warning. expresss, registered in 2016 with about 755 downloads a week, gets a look-alike warning, not a block.
  • Network use is opt-in and only queries the public npm registry. Packages from private registries are skipped, so they are not checked.

Sources