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:
- Does it exist? A name that was never published returns
E404. - Who publishes it, and is it a placeholder? A version ending in
-securitypublished bynpmmeans npm removed the original package, usually for malware. - Is it the name you meant? Compare it letter by letter with the popular package;
crossenvis notcross-env.
A name that does not exist:
$ 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:
$ 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:
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 repositoryReal output for four packages:
$ 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$ 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$ 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$ npx ai-guard verify-deps lodash AI GUARD Dependencies · 1 package · 0 blocked · 0 warnings ✔ 1 package checked, nothing to reportThe 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
| Blocked | Warning |
|---|---|
| The package does not exist on npm | Look-alike of a popular package that is established |
| The exact version or dist-tag does not exist | First published less than 30 days ago |
| npm replaced it with a security placeholder | Fewer than 100 downloads last week |
| Look-alike of a popular package that is new or rarely downloaded | Runs an install script |
| Install script on a new or rarely downloaded package | Deprecated |
| 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.