npq allows you to audit npm packages _before_ you install them [![npm](https://img.shields.io/npm/v/npq)](https://www.npmjs.com/package/npq) [![license](https://img.shields.io/npm/l/npq)](LICENSE) [![codecov](https://img.shields.io/codecov/c/gh/lirantal/npq/main)](https://codecov.io/gh/lirantal/npq) [![CI](https://img.shields.io/github/actions/workflow/status/lirantal/npq/main.yml?branch=main&label=CI&logo=github)](https://github.com/lirantal/npq/actions/workflows/main.yml?query=branch%3Amain) [![Security Responsible Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow)](SECURITY.md) TL;DR how to use npq: ```sh $ 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: ![npq demo screenshot](.github/npq.png) Media coverage about npq: - As mentioned on [Thomas Gentilhomme](https://github.com/fraxken)'s French book of [Become a Node.js Developer](https://docs.google.com/document/d/1JHgmEFkc8Py4XSuCB8_DQ5FFEJoogyeninFK6ucTd4o/edit#) - Tao Bojlén's [A web of trust for npm](https://btao.org/posts/2020-10-02-npm-trust/) - Zander's [favorite list of command line tools](https://zander.wtf/blog/terminal-commands) - Ran Bar Zik's [npq review to install safe modules](https://internet-israel.com/%D7%A4%D7%99%D7%AA%D7%95%D7%97-%D7%90%D7%99%D7%A0%D7%98%D7%A8%D7%A0%D7%98/%D7%91%D7%A0%D7%99%D7%99%D7%AA-%D7%90%D7%AA%D7%A8%D7%99-%D7%90%D7%99%D7%A0%D7%98%D7%A8%D7%A0%D7%98-%D7%9C%D7%9E%D7%A4%D7%AA%D7%97%D7%99%D7%9D/%D7%91%D7%93%D7%99%D7%A7%D7%94-%D7%A2%D7%9D-npq-%D7%9B%D7%93%D7%99-%D7%9C%D7%95%D7%95%D7%93%D7%90-%D7%94%D7%AA%D7%A7%D7%A0%D7%94-%D7%AA%D7%A7%D7%99%D7%A0%D7%94-%D7%A9%D7%9C-%D7%9E%D7%95%D7%93%D7%95/) - ostechnix's [How To Safely Install Packages Using Npm Or Yarn On Linux](https://ostechnix.com/how-to-safely-install-packages-using-npm-or-yarn-on-linux) - debricked's [How to evaluate the security of your NPM Package dependencies](https://debricked.com/blog/2020/03/11/how-to-evaluate-the-security-of-your-npm-package-dependencies) - JavaScript January advent calendar's post on [Open Source From Heaven, Modules From Hell](https://www.lirantal.com/blog/2019-01-26) - Liran Tal's [Malicious Modules — what you need to know when installing npm packages](https://www.lirantal.com/blog/malicious-modules-what-you-need-to-know-when-installing-npm-packages-12b2f56d3685) ## About Once npq is installed, you can safely\* install packages: ```bash 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](https://snyk.io/vuln) 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](docs/feature/auto-continue.md) 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 ## Install ```bash 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](https://brew.sh) on macOS or Linux: ```bash brew install npq ``` ## Usage ### Install packages with npq ```bash 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: ```sh npq install @company/tool --registry=https://artifactory.example.com/artifactory/api/npm/npm-virtual/ ``` See [Custom registries](docs/feature/custom-registry.md) 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. ```bash 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=` Examples: **Using yarn 1.x:** ```bash alias yarn="NPQ_PKG_MGR=yarn npq-hero" ``` **Using yarn 4.x:** ```bash NPQ_PKG_MGR=yarn yarn run npq-hero ``` or ```bash NPQ_PKG_MGR=yarn yarn exec npq-hero ``` **Using pnpm:** ```bash NPQ_PKG_MGR=pnpm npx npq install fastify ``` **Using pnpm with alias:** ```bash 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 | 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 | Validates the resolved version’s publisher (`_npmUser`), flags a **new** maintainer on the package (first publish by that email or trusted publisher configuration within 21 days), **dormant maintainer** gaps on versions published within 30 days (warning if over ~6 months since their last publish on that package, error if over ~9 months), and very **recent** publishes | See [docs/feature/author-marshall.md](docs/feature/author-marshall.md) | | downloads | Will show a warning for a package if its download count in the last month is less than 20 | Reports `not evaluated` for custom-registry packages instead of querying the public npm downloads service | | 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 | Normalizes and checks complete maintainer email hosts, then corroborates a simple two-label DNS failure through authoritative RDAP before warning | Multipart and otherwise inconclusive results are reported as not evaluated; see [expired-domain marshall documentation](docs/feature/expired-domains.md) | | signatures | Will compare the package's signature as it shows on the registry's packument with signing keys published by the selected registry | Reports `not evaluated` if the selected registry does not expose signing keys | | provenance | Will verify the package's attestations of provenance metadata for the published package, and **error** on [provenance regression](docs/feature/provenance.md) (an older semver had registry provenance metadata but the version you install does not) | Reports `not evaluated` if the selected registry does not expose signing keys or attestations | | version-maturity | Will show an error if the specific version being installed was published less than 7 days ago | Suggests the highest older semver outside npq's 30-day version-recency window when one is available | | 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. | ### 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: ```text │ │ ℹ Suggested older release · @openai/codex@0.121.0 — 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: ```bash 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 | | snyk | `MARSHALL_DISABLE_SNYK` | Disable Snyk vulnerability checks | | typosquatting | `MARSHALL_DISABLE_TYPOSQUATTING` | Disable typosquatting detection | | version-maturity | `MARSHALL_DISABLE_VERSION_MATURITY` | Disable version maturity checks | | newBin | `MARSHALL_DISABLE_NEWBIN` | Disable new binary introduction checks | | deprecation | `MARSHALL_DISABLE_DEPRECATION` | Disable deprecation checks | ### 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 `: checks only, no install passthrough. Use `npq install …` when you want npq to hand off to npm (or `NPQ_PKG_MGR`) after the checks. Project-mode audits currently cover only declared direct dependencies from the current project's `package.json` (`dependencies` and `devDependencies`). They do not read lockfiles or discover transitive dependencies. ```sh npq install express --dry-run ``` ### Force non-rich text output ```sh npq install express --plain ``` ### Machine-readable audits Use `--json` for a non-interactive, audit-only result suitable for CI: ```sh npq install express --json ``` When npq detects a supported coding-agent environment, non-install audits still use the same audit-only JSON mode automatically. Explicit `npq install ...` and recognized `npq-hero install ...` commands keep the normal audit/install pipeline instead, using coding-agent detection as an authorization for warning-only installs. See the [full coding-agent detection signal table](docs/feature/json-output.md#coding-agent-detection) for the supported signals and contextual matchers. 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](docs/feature/json-output.md). ### Non-interactive installs npq never uses the warning countdown when standard input is not interactive. If an audit reports warnings or errors in CI, npq exits nonzero and does not invoke the package manager. For ordinary automation that intentionally wants warning-only installs to continue, opt in explicitly: ```sh npq install express --allow-non-interactive-install NPQ_ALLOW_NON_INTERACTIVE_INSTALL=true npq install express ``` When you use `npq-hero` or an aliased package manager, the ordinary opt-in is environment-only because the wrapper does not expose its own CLI flags: ```sh NPQ_ALLOW_NON_INTERACTIVE_INSTALL=true npm install express ``` Detected coding-agent environments are treated as an explicit opt-in for `npq install express` and `npq-hero install express`, so agent-driven package-manager installs continue without the extra flag. Explicit `--json` remains audit-only and never invokes the package manager. ### 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 require explicit confirmation in an interactive terminal: **Using the CLI flag:** ```sh npq install express --disable-auto-continue ``` **Using the environment variable:** ```sh export NPQ_DISABLE_AUTO_CONTINUE=true npq install express ``` Or set it permanently in your shell profile (`.bashrc`, `.zshrc`, etc.): ```sh export NPQ_DISABLE_AUTO_CONTINUE=true ``` When auto-continue is disabled, npq prompts for explicit confirmation in an interactive terminal. Non-interactive warning-only installs remain fail-closed unless the explicit non-interactive install opt-in or coding-agent authorization applies. ## Learn Node.js Security

Node.js Security

![Screenshot 2024-09-12 at 20 14 27](.github/nodejs-security-screenshot.png)

Learn Node.js Secure Coding techniques and best practices from Liran Tal

## 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](https://github.com/lirantal/npq#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](./docs/README.md) - development, testing, architecture, and conventions. ## Contributing Please consult the [CONTRIBUTING](CONTRIBUTING.md) for guidelines on contributing to this project ## Author Liran Tal