safely* install packages with npm/yarn by auditing them as part of your install process
Once npq is installed, you can safely* install packages:
npq install express
npq
will perform the following steps to sanity check the package is safe by employing syntactic heuristics and querying a CVE database:
- Consult snyk.io database of publicly disclosed vulnerabilities to check if a 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 pre/post install scripts
If npq is prompted to continue with the install it simply handovers 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 disclosure published and passes npq's checks.
npm install -g npq
npq install express
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'
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:
alias yarn="NPQ_PKG_MGR=yarn npq-hero"
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.
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 |
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 | |
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 |
To disable a marshall altogether set an environment variable using with the marshall's shortname.
Example, to disable snyk:
MARSHALL_DISABLE_SNYK=1 npq install express
- 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 either npm or yarn (depends on your choosing).
- How is NPQ different from npm audit?
- npm audit is reserved for npm, but NPQ works for both npm and yarn users
- npm audit installs a module even if it has vulnerabilities, NPQ will display the issues detected and prompt the user for confirmation whether to proceed installing it.
- NPQ will run synthathic 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. Where as, npm audit will not perform any such checks and only consult a vulnerability database for known security issues. - npm audit can better be compared with snyk, rather than NPQ.
- Do I require to have a snyk API key in order to use NPQ?
- It's not required. If NPQ won't be able to detect a snyk API key for the user running NPQ then it will skip database vulnerabilities check. We do however greatly encourage you to use snyk and connect it with NPQ for broader security.
Please consult the CONTRIBUTING for guidelines on contributing to this project
Liran Tal [email protected]