lirantal/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

Custom registries

NPQ reads standard npm registry configuration, including default and scoped registries, authentication, proxies, and TLS settings. You can also select a registry on the command line; the option is shared with the package manager used for installation:

npq install @company/tool --registry=https://artifactory.example.com/artifactory/api/npm/npm-virtual/

See Custom registries for .npmrc examples, configuration precedence, private CA setup, skipped capability behavior, and NPQ's no-fallback privacy guarantee.

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"
pnpm --filter workspace... add express

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

Older release suggestions

When a requested version fails the version-maturity check, npq may show the highest older semver published outside its 30-day package-version recency window:

 │
 │ ℹ Suggested older release · @openai/[email protected] — published 33 days ago
 │   Clears npq's package-version recency windows. Re-run npq to audit this
 │   version; compatibility is not evaluated.

The suggestion:

• can cross a major-version boundary for tags such as latest;
• is based on cached package publication metadata and is not automatically installed;
• is not a statement that the older release is safe or that it passes every npq check;
• does not evaluate API or runtime compatibility.

Run npq again with the suggested version and review its compatibility before installing it.

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:

Run checks on package without installing it

Running npq without an install / i / add subcommand (for example from a project directory with a package.json) audits dependencies only and does not run the package manager. The same applies to npq <package>: checks only, no install passthrough. Use npq install … when you want npq to hand off to npm (or NPQ_PKG_MGR) after the checks.

npq install express --dry-run

Force non-rich text output

npq install express --plain

Machine-readable audits

Use --json for a non-interactive, audit-only result suitable for CI:

npq install express --json

When npq detects a supported coding-agent environment, it automatically uses the same audit-only JSON mode. This applies to npq and to install commands intercepted by npq-hero; non-install npq-hero commands still pass through to the configured package manager. See JSON audit output.

JSON mode never invokes the package manager. It exits 0 for a clean audit, 1 for findings, and 2 when the audit cannot complete. See JSON audit output.

Disable auto-continue countdown

By default, when npq detects only warnings (no errors), it automatically proceeds with installation after a 15-second countdown. To disable this behavior and always require explicit confirmation:

Using the CLI flag:

npq install express --disable-auto-continue

Using the environment variable:

export NPQ_DISABLE_AUTO_CONTINUE=true
npq install express

Or set it permanently in your shell profile (.bashrc, .zshrc, etc.):

export NPQ_DISABLE_AUTO_CONTINUE=true

When auto-continue is disabled, npq will always prompt for explicit confirmation before proceeding with installation, even when only warnings are detected.

Learn Node.js Security

FAQ

1. What is the difference between npq and npq-hero?

• npq is meant to be its own stand-alone CLI so it has command line flags like --dry-run and others (see npq --help). However, when you want to alias the npm CLI to NPQ you should use npq-hero as the executable of the alias to npm (e.g: alias npm=npq), which means npq-hero can't have its own command-line flags because they could conflict with the npm executable.

2. Can I use NPQ without having npm or yarn?

• NPQ will audit a package for possible security issues, but it isn't a replacement for npm or yarn. When you choose to continue installing the package, it will offload the installation process to your choice of either npm or yarn.

3. How is NPQ different from npm audit?

• npm install will install a module even if it has vulnerabilities; NPQ will display the issues detected, and prompt the user for confirmation on whether to proceed installing it.
• NPQ will run synthetic checks, called marshalls, on the characteristics of a module, such as whether the module you are going to install has a pre-install script which can be potentially harmful for your system and prompt you whether to install it. Whereas npm audit will not perform any such checks, and only consults a vulnerability database for known security issues.
• npm audit is closer in functionality to what Snyk does, rather than what NPQ does.

4. Do I require a Snyk API key in order to use NPQ?

• It's not required. If NPQ is unable to detect a Snyk API key for the user running NPQ, then it will skip the database vulnerabilities check. We do, however, greatly encourage you to use Snyk, and connect it with NPQ for broader security.

5. Why is NPQ connecting to external domains like gmail.com or personal websites during installation?

• This is not telemetry. NPQ does not collect any usage data. When auditing a package, NPQ fetches the maintainers/authors of the dependency and checks their email addresses to verify they are valid and not associated with expired domains. Expired domains can be abused by attackers for account takeover (ATO) attacks to compromise packages with malicious versions. Hence, NPQ may make DNS requests to domains like gmail.com or personal domains found in maintainer emails. After a simple two-label domain returns NXDOMAIN and its top-level domain resolves, NPQ may fetch the official IANA RDAP bootstrap and query the selected authoritative HTTPS RDAP service, sending only the normalized two-label domain. Additionally, NPQ makes HTTP requests to osv.dev to fetch security vulnerability data (or uses Snyk if configured, as a prioritized option).

Documentation

• Project documentation - development, testing, architecture, and conventions.

Contributing

Please consult the CONTRIBUTING for guidelines on contributing to this project

Author

Liran Tal [email protected]