Npq

npq allows you to audit npm packages before you install them

TL;DR how to use npq:

$ npx npq install express --dry-run

What it does: the npx tool downloads and execute npq package, runs an install check for the express package and --dry-run means npq exists regardless of success/errors.

Here's a screenshot of npq in action:

Media coverage about npq:

• As mentioned on Thomas Gentilhomme's French book of Become a Node.js Developer
• Tao Bojlén's A web of trust for npm
• Zander's favorite list of command line tools
• Ran Bar Zik's npq review to install safe modules
• ostechnix's How To Safely Install Packages Using Npm Or Yarn On Linux
• debricked's How to evaluate the security of your NPM Package dependencies
• JavaScript January advent calendar's post on Open Source From Heaven, Modules From Hell
• Liran Tal's Malicious Modules — what you need to know when installing npm packages

About

Once npq is installed, you can safely* install packages:

npq install express

npq will perform the following steps to sanity check that the package is safe by employing syntactic heuristics and querying a CVE database:

• Consult the snyk.io database of publicly disclosed vulnerabilities to check if a security vulnerability exists for this package and its version.
• Package age on npm
• Package download count as a popularity metric
• Package has a README file
• Package has a LICENSE file
• Package has pre/post install scripts

IMPORTANT: npq by default uses an auto-continue mode when warnings are detected (no errors), waiting 15 seconds before proceeding with the installation. You can disable this behavior via the --disable-auto-continue CLI flag or the NPQ_DISABLE_AUTO_CONTINUE=true environment variable to enforce a strict review and security hardened installs. See the auto-continue documentation for more details.

When npq completes its signal checks it hands over the actual package install job to the package manager (npm by default, or as specified via the NPQ_PKG_MGR environment variable).

DISCLAIMER: there's no guaranteed absolute safety; a malicious or vulnerable package could still exist that has no security vulnerabilities publicly disclosed and passes npq's checks.

Demo

https://github.com/user-attachments/assets/619ab3f6-aa3f-483c-9560-0f18e033e6bf

Install

npm install -g npq

Note: we recommend installing with npm rather than yarn. That way, npq can automatically install shell aliases for you.

You can also install npq via Homebrew on macOS or Linux:

brew install npq

Usage

Install packages with npq

npq install express

Embed in your day to day

Since npq is a pre-step to ensure that the npm package you're installing is safe, you can safely embed it in your day-to-day npm usage so there's no need to remember to run npq explicitly.

alias npm='npq-hero'

Offload to package managers

If you're using yarn, pnpm, or generally want to explicitly tell npq which package manager to use you can specify an environment variable: NPQ_PKG_MGR=<package-manager>

Examples:

Using yarn 1.x:

alias yarn="NPQ_PKG_MGR=yarn npq-hero"

Using yarn 4.x:

NPQ_PKG_MGR=yarn yarn run npq-hero

or

NPQ_PKG_MGR=yarn yarn exec npq-hero

Using pnpm:

NPQ_PKG_MGR=pnpm npx npq install fastify

Using pnpm with alias:

alias pnpm="NPQ_PKG_MGR=pnpm npq-hero"

Note: npq by default will offload all commands and their arguments to the npm (or other package manager as specified) after it finished its due-diligence checks for the respective packages.

Marshalls

| Marshall Name | Description | Notes | --- | --- | --- | age | Will show a warning for a package if its age on npm is less than 22 days | Checks a package creation date, not a specific version | author | Will show a warning if a package has been found without an author field | Checks the latest version for an author | downloads | Will show a warning for a package if its download count in the last month is less than 20 | readme | Will show a warning if a package has no README or it has been detected as a security placeholder package by npm staff | repo | Will show a warning if a package has been found without a valid and working repository URL | Checks the latest version for a repository URL | scripts | Will show a warning if a package has a pre/post install script which could potentially be malicious | snyk | Will show a warning if a package has been found with vulnerabilities in Snyk's database | For Snyk to work you need to either have the snyk npm package installed with a valid API token, or make the token available in the SNYK_TOKEN environment variable, and npq will use it | license | Will show a warning if a package has been found without a license field | Checks the latest version for a license | expired domains | Will show a warning if a package has been found with one of its maintainers having an email address that includes an expired domain | Checks a dependency version for a maintainer with an expired domain | signatures | Will compare the package's signature as it shows on the registry's pakument with the keys published on the npmjs.com registry | provenance | Will verify the package's attestations of provenance metadata for the published package | version-maturity | Will show a warning if the specific version being installed was published less than 7 days ago | Helps identify recently published versions that may not have been reviewed by the community yet | newBin | Will show a warning if the package version being installed introduces a new command-line binary (via the bin field in package.json) that was not present in its previous version. | Helps identify potentially unexpected new executables being added to your node_modules/.bin/ directory. | typosquatting | Will show a warning if the package name is similar to a popular package name, which could indicate a potential typosquatting attack. | Helps identify packages that may be trying to trick users into installing them by mimicking popular package names. | deprecation | Will show a warning if the package version is deprecated on npm or if its GitHub repository has been archived. | Helps identify packages that are no longer maintained or recommended for use. Set GITHUB_TOKEN environment variable for higher GitHub API rate limits.

Disabling Marshalls

To disable a marshall altogether, set an environment variable using with the marshall's shortname.

Example, to disable the Snyk vulnerability marshall:

MARSHALL_DISABLE_SNYK=1 npq install express

Available Marshall Environment Variables

Here are all the available environment variable names for disabling specific marshalls:

| Marshall Name | Environment Variable | Description | |------------------|-----------------------------------------------|-----------------------------------------------------| | age | MARSHALL_DISABLE_AGE | Disable package age checks | | author | MARSHALL_DISABLE_AUTHOR | Disable package author verification | | downloads | MARSHALL_DISABLE_DOWNLOADS | Disable download count checks | | expired domains | MARSHALL_DISABLE_MAINTAINERS_EXPIRED_EMAILS | Disable expired domain checks for maintainer emails | | license | MARSHALL_DISABLE_LICENSE | Disable license availability checks | | provenance | MARSHALL_DISABLE_PROVENANCE | Disable package provenance verification | | repo | MARSHALL_DISABLE_REPO | Disable repository URL validation | | scripts | MARSHALL_DISABLE_SCRIPTS | Disable pre/post install script checks | | signatures | MARSHALL_DISABLE_SIGNATURES | Disable registry signature verification