npq 3.19.6 → 3.21.0

package/README.md

@@ -78,6 +78,16 @@ brew install 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:
+
+```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.
@@ -130,15 +140,15 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 | --- | --- | ---
 | 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 within 21 days), **dormant maintainer** gaps (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
+| 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 | Will show a warning if a package has been found with one of its maintainers having an email address that includes an expired domain | Checks a dependency version for a maintainer with an expired domain
-| signatures | Will compare the package's signature as it shows on the registry's pakument with the keys published on the npmjs.com registry
-| 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)
+| 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 a warning if the specific version being installed was published less than 7 days ago | Helps identify recently published versions that may not have been reviewed by the community yet
 | 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.
@@ -257,6 +267,10 @@ When auto-continue is disabled, npq will always prompt for explicit confirmation
 
 * 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. 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

package/bin/npq-hero.js

@@ -12,6 +12,8 @@ const cliPrompt = require('../lib/helpers/cliPrompt.js')
 const { reportResults } = require('../lib/helpers/reportResults')
 const { Spinner } = require('../lib/helpers/cliSpinner')
 const { promiseThrottleHelper } = require('../lib/helpers/promiseThrottler')
+const RegistryConfig = require('../lib/helpers/registryConfig')
+const RegistryClient = require('../lib/helpers/registryClient')
 
 const PACKAGE_MANAGER_TOOL = process.env.NPQ_PKG_MGR
 const DISABLE_AUTO_CONTINUE = process.env.NPQ_DISABLE_AUTO_CONTINUE === 'true'
@@ -27,14 +29,17 @@ if (spinner) {
   spinner.start()
 }
 
-const marshall = new Marshall({
-  pkgs: cliArgs.packages,
-  progressManager: spinner,
-  promiseThrottleHelper
-})
-
-marshall
-  .process()
+RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
+  .then((registryConfig) => {
+    const registryClient = new RegistryClient(registryConfig)
+    const marshall = new Marshall({
+      pkgs: cliArgs.packages,
+      registryClient,
+      progressManager: spinner,
+      promiseThrottleHelper
+    })
+    return marshall.process()
+  })
   .then((marshallResults) => {
     if (spinner) {
       spinner.stop()
@@ -46,12 +51,20 @@ marshall
       Object.hasOwn(results, 'countErrors') &&
       Object.hasOwn(results, 'countWarnings')
     ) {
-      const { countErrors, countWarnings, useRichFormatting } = results
-      const isErrors = countErrors > 0 || countWarnings > 0
+      const {
+        countErrors,
+        countWarnings,
+        countNotEvaluated = 0,
+        useRichFormatting
+      } = results
+      const hasFindings = countErrors > 0 || countWarnings > 0
+      const hasReportableResults = hasFindings || countNotEvaluated > 0
 
-      if (isErrors) {
+      if (hasReportableResults) {
         console.log()
-        console.log('Packages with issues found:')
+        console.log(
+          hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:'
+        )
 
         if (useRichFormatting) {
           console.log(results.resultsForPrettyPrint)
@@ -63,9 +76,10 @@ marshall
       }
 
       return {
-        anyIssues: isErrors,
+        anyIssues: hasFindings,
         countErrors,
-        countWarnings
+        countWarnings,
+        countNotEvaluated
       }
     }
     return undefined

package/bin/npq.js

@@ -15,6 +15,8 @@ const cliPrompt = require('../lib/helpers/cliPrompt.js')
 const { reportResults } = require('../lib/helpers/reportResults')
 const { Spinner } = require('../lib/helpers/cliSpinner')
 const { promiseThrottleHelper } = require('../lib/helpers/promiseThrottler')
+const RegistryConfig = require('../lib/helpers/registryConfig')
+const RegistryClient = require('../lib/helpers/registryClient')
 
 const debug = util.debuglog('npq')
 
@@ -27,7 +29,12 @@ if (spinner) {
   spinner.start()
 }
 
-Promise.resolve()
+let registryClient
+
+RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
+  .then((registryConfig) => {
+    registryClient = new RegistryClient(registryConfig)
+  })
   .then(() => {
     if (cliArgs.packages.length === 0) {
       debug('\nNo packages specified, using project packages from package.json')
@@ -48,6 +55,7 @@ Promise.resolve()
 
     const marshall = new Marshall({
       pkgs: packages,
+      registryClient,
       progressManager: spinner,
       promiseThrottleHelper
     })
@@ -65,12 +73,20 @@ Promise.resolve()
       Object.hasOwn(results, 'countErrors') &&
       Object.hasOwn(results, 'countWarnings')
     ) {
-      const { countErrors, countWarnings, useRichFormatting } = results
-      const isErrors = countErrors > 0 || countWarnings > 0
-
-      if (isErrors) {
+      const {
+        countErrors,
+        countWarnings,
+        countNotEvaluated = 0,
+        useRichFormatting
+      } = results
+      const hasFindings = countErrors > 0 || countWarnings > 0
+      const hasReportableResults = hasFindings || countNotEvaluated > 0
+
+      if (hasReportableResults) {
         console.log()
-        console.log('Packages with issues found:')
+        console.log(
+          hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:'
+        )
 
         if (useRichFormatting) {
           console.log(results.resultsForPrettyPrint)
@@ -82,9 +98,10 @@ Promise.resolve()
       }
 
       return {
-        anyIssues: isErrors,
+        anyIssues: hasFindings,
         countErrors,
-        countWarnings
+        countWarnings,
+        countNotEvaluated
       }
     }
     return undefined