lirantal/npq

safely install npm packages by auditing them pre-install stage

Summary

npq is a command-line tool that audits npm packages before installing them, running a set of checks called "marshalls" against npm registry metadata and vulnerability databases. After the checks complete, npq hands off to npm, yarn, or pnpm to perform the actual install. The project is Apache-2.0 licensed, written in JavaScript, and ships as the npq and npq-hero executables.

What it is useful for

Engineers routinely install npm packages without scrutinizing their supply chain risk. npq sits between "I want to install X" and "X is installed" and surfaces common red flags: known CVEs via the Snyk database, package age under 22 days, low monthly download counts, missing README/LICENSE files, presence of pre/post-install scripts, typosquatting names, expired maintainer domains, and suspicious new binaries introduced via the bin field.

It is useful when onboarding an unfamiliar dependency, vetting a one-off script from a new author, or hardening CI so a vulnerable package cannot slip through silently. npq also supports scoped and private registries, checks registry signatures, and verifies provenance attestations, which helps teams that publish or consume internal packages.

Documented limitations worth keeping in mind: npq explicitly disclaims any guarantee of safety, and project-mode audits only inspect declared direct dependencies in the current package.json; transitive dependencies and lockfile entries are not covered.

How engineers can use it

Install globally:

npm install -g npq

Or on macOS/Linux via Homebrew (brew install npq). To audit a package without installing it:

npx npq install express --dry-run

To run npq before every install transparently, alias npm to the flag-free npq-hero wrapper:

alias npm='npq-hero'

For yarn 1.x use alias yarn="NPQ_PKG_MGR=yarn npq-hero", and for pnpm set NPQ_PKG_MGR=pnpm in the same shape. To enforce a strict review instead of the default 15-second auto-continue countdown, pass --disable-auto-continue or set NPQ_DISABLE_AUTO_CONTINUE=true.

For CI, run with --json to get a non-interactive audit-only report; exit codes are 0 for clean, 1 for findings, 2 when the audit cannot complete. The Snyk marshall requires SNYK_TOKEN or an authenticated snyk CLI, otherwise it is skipped, and any marshall can be turned off individually via variables such as MARSHALL_DISABLE_SNYK=1.