npq

Safely install packages with npm or yarn by auditing them as part of your i...

Package ManagerSecurity
lirantal/npqnpq

README


npq


safely* install packages with npm/yarn by auditing them as part of your install process

Media coverage about npq:
- As mentioned on Thomas Gentilhomme
- 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:

  1. ```bash
  2. npq install express
  3. ```

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

If npq is prompted to continue with the install, it simply hands over the actual package install job to the package manager (npm by default).

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

Install


  1. ```bash
  2. npm install -g npq
  3. ```

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

Usage


Install packages with npq:


  1. ```bash
  2. npq install express
  3. ```

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.

  1. ```bash
  2. alias npm='npq-hero'
  3. ```

Offload to package managers


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

Example: create an alias with yarn as the package manager:

  1. ```bash
  2. alias yarn="NPQ_PKG_MGR=yarn npq-hero"
  3. ```

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

Marshalls


MarshallDescriptionNotes
---------
ageWillChecks
authorWillChecks
downloadsWill
readmeWill
repoWillChecks
scriptsWill
snykWillFor
licenseWillChecks
expiredWillChecks
signaturesWill
provenanceWill

Disabling Marshalls


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

Example, to disable the Snyk vulnerability marshall:

  1. ```
  2. MARSHALL_DISABLE_SNYK=1 npq install express
  3. ```

Run checks on package without installing it:


  1. ```sh
  2. npq install express --dry-run
  3. ```

Using with TravisCI


An example of using lockfile-lint with a .travis.yml configuration as part of your build:

  1. ```
  2. language: node_js
  3. before_script:
  4.   - npx lockfile-lint --path package-lock.json --validate-https --allowed-hosts npm
  5. install:
  6.   - yarn install
  7. script:
  8.   - yarn run test
  9. ```

FAQ

1. 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.
2. 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 apre-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.
3. 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.

Contributing


Please consult the CONTRIBUTING for guidelines on contributing to this project

Author

Liran Tal