Top

NCM 2

Node Certified Modules v2

Overview

NodeSource Certified Modules 2 provides you and your teams with actionable insights into the risk levels that are present in your use of third-party packages. Using a series of tests, we score packages on npm to look for a number of weighted criteria. With the NCM 2 CLI you can scan your projects, for existing security vulnerabilities, license concerns, code risk and code quality. This helps you understand the level of risk exposure and how to mitigate it.

NodeSource Risk Score

NodeSource Certified Modules 2 (NCM 2) calculates a risk score for every third party package on npm. Each module is assessed for security vulnerabilities, license concerns and a series of package risk and quality attributes.

Terminology and their respective scoring criteria are included below:

  • "Package": a bundled module, as distributed by npm.
  • "Criteria": a programmatic rule run against a package.
  • "Cert": the raw output data from a criteria.
  • "Score": the processed, user-facing output data for a criteria.
  • "Score Group": a set of related scores.
  • "Severity": the approximate level of impact a score has, related to its score group.

Scoring Output NCM 2 - Risk Level

Scoring in NCM 2 is substantially different than it was in NCM 1. Instead of providing a 0-100 trust score, NCM 2 assesses packages based on security, compliance, package risk and quality attributes. Combined, these attributes result in an overall risk-level for each package which allows you to:

  • Manage acceptable risk levels incurred through third-party code.
  • Understand current security vulnerabilities and their severity introduced via third party modules.
  • Understand license and compliance risks introduced via third party modules.
  • Understand potential risk vectors not yet surfaced in security vulnerabilities.
  • Obtain insights into quality attributes that align with best-practices making your code more manageable and secure.

The following paragraphs detail the NCM 2 scores, score groups, severity levels, and what all of those mean.

Security

The Security group surfaces if a certain module contains security vulnerabilities, along with their respective vulnerability-severity and if available, a path to their remediation.

Security Severity

Security vulnerabilities have severity levels. Each severity level contributed to the respective risk level. i.e.:

  • Low Severity -> Low Risk
  • Medium Severity -> Medium Risk
  • High Severity -> High Risk

Security Score : vulnerability

Security vulnerabilities as reported by Snyk. Severity output is per reported vulnerability severity.

Compliance

The Compliance group is for special criteria which have elevated legal and/or security implications.

Compliance Severity

Any Compliance failure should be considered to have an elevated criticality, regardless of the severity level.

A module with CRITICAL compliance severity should never be used.

Compliance Score: license

The license score is intended to indicate that a given module has a license which is permissible for use, allows redistribution & modification, and does not require source disclosure. The list of currently acceptable licenses:

MIT
ISC
Apache-1.0
Apache-1.1
Apache-2.0
BSD-1-Clause
BSD-2-Clause
BSD-3-Clause
BSD-4-Clause

Severity output:

  • HIGH if no license.
  • HIGH if license is invalid.
  • MEDIUM if license is unacceptable as per the list above.
  • NONE otherwise.

Risk

The Risk group is for criteria which are intended to indicate whether a package's usage or installation may be abnormally risky, outside of purely security.

Some examples of things considered risky:

  • Packages which include code which could have severe implications if misused.
  • Packages which are likely to cease functioning in a future Node.js major upgrade.
  • Packages which have poor error handling.

Risk Severity

The risk group has a more fine grained severity ranking, although severity will still vary somewhat by score.

  • CRITICAL: Avoid install without manually inspecting this package's code & scripts.
  • HIGH: Manually inspecting this package's code & scripts before install is recommended.
  • MEDIUM: Inspecting this package's code before use is recommended.
  • LOW: This package does something less-than-ideal that could manifest risk in some circumstances.
  • NONE: Nothing of note.

Risk Score Overview:

NCM 2 captures the following set of Risk Scores. This set continues to expand. Each property is outlined in more detail below:

Risk Score: has-install-scripts

This score indicates whether any npm lifecycle scripts which trigger on install were detected.

Lifecycle scripts which trigger on install can be useful but are inherently risky, as they may run unwanted CLI commands before other tools or the user can inspect the package.

The list of npm lifecycle scripts which may run on install (and are as such considered risky):

preinstall
install
postinstall
preuninstall
uninstall
postuninstall

Note: npm "scripts" are package-author-defined shell snippets which are defined in a package.json.

Additionally, gyp build files from native modules are also considered install scripts under this score, as they may execute arbitrary code and also run on install.

Identifying this risk attribute in a package means that its risk score will be elevated to Critical.

Risk Score: has-gyp-file

An additional score to compliment has-install-scripts which indicates specifically the presence of a gyp build file (as required by native modules).

For more about gyp files and building native addons, please see node-gyp, which is invoked by npm during the buildlifecycle step or rebuild command.

Identifying this risk attribute in a package means that its risk score will be elevated to Critical.

Risk Score: uses-eval

This score indicates whether static code analysis of the package detected any eval() or implied eval (Function(), etc) usage.

Regardless if an actual security vulnerability exists, any code that uses eval is at risk of receiving & executing unverified upstream data.

Identifying this risk attribute in a package means that its risk score will be elevated to High.

Risk Score: has-unsafe-regexps

This score indicates whether static code analysis of the package detected any exponential-time Regular Expressions, which could be a DOS attack vector ("ReDoS") for unverified upstream data.

Identifying this risk attribute in a package means that its risk score will be elevated to Medium.

Risk Score: uses-deprecated-node-apis

This score indicates whether static code analysis of the package detected any deprecated Node.js core APIs. A package which uses deprecated Node.js apis may not function in a future Node.js major version upgrade.

A list of all deprecated Node.js core APIs can be found in the official Node.js documentation.

This criteria may not detect all Node.js deprecations and also will not detect ones within some time of the deprecation being issued.

Identifying this risk attribute in a package means that its risk score will be elevated to Medium.

Risk Score: has-lost-callback-errs

This score indicates whether static code analysis of the package detected any callback error arguments which were not checked, where any potential runtime error may be "lost".

Not doing checks & proper handling for errors in callbacks that take error parameters could cause state, memory, and/or resource, leaks.

Identifying this risk attribute in a package means that its risk score will be elevated to High.

Risk Score: has-abandoned-promises

This score indicates whether static code analysis of the package detected any Promise-s which did not have some form of finalization handling. This includes .catch() or a second argument to .then(), .finally(), and most common user promise library provided handlers.

Not doing proper finalization and/or error handling Promise-s could cause state, memory, and/or resource, leaks.

Identifying this risk attribute in a package means that its risk score will be elevated to High.

Risk Score: missing-strict-mode

This score indicates whether static code analysis of the package detected the lack of strict mode ('use strict') in any of the package's code.

Not using strict mode can result in code that has silent errors or is non-optimizable by the javascript engine.

Identifying this risk attribute in a package means that its risk score will be elevated to Low.

Quality

The Quality group is for criteria which are intended to indicate whether a package conforms to good open-source practices.

Good practice is things such as:

  • Including documentation.
  • Links to a source control repository.

Quality Severity

Quality criteria currently do not feature a severity dimension since the pipeline is intended to provide users with actionable information to help them reduce the risk-level that is present in their code. A quality criteria implies adherence to best-practices which result in more manageable and secure code. Since a quality criteria does not offset a security vulnerability or risk attribute, NCM 2 does not assign an impact severity to a quality attribute. Quality scores do therefore not affect a package’s risk level. This is determined by the lowest risk level that is present as determined by its security/ risk attributes.

Quality Scores

NCM 2 captures the following set of Quality Scores. This set continues to expand. Each property is outlined in more detail below:

Quality Score: readme-exists

This score indicates whether a readme file of some sort is present.

Identifying this attribute in a package means that its score will be elevated to Medium.

Quality Score: readme-size

This score indicates the size of a readme file (if a readme file is present).

Severity:

  • NONE if readme is of decent size.
  • LOW if readme size is under 1kb.
  • MEDIUM if readme size is under 500 bytes.

Quality Score: disk-usage-expanded-size

This score indicates the uncompressed size of the package on disk. Severity:

  • NONE if package size is under 20kb.
  • LOW if package size is over 20kb.
  • MEDIUM if package size is over 50kb.
  • HIGH if package size is over 100kb.
  • CRITICAL if package size is over 1mb.

Quality Score: disk-usage-file-count

This score indicates the number of files within a package.

Severity MEDIUM if a package contains over 100 files, otherwise NONE.

Quality Score: disk-usage-dir-count

This score indicates the number of directories within a package.

Severity MEDIUM if a package contains over 20 directories, otherwise NONE.

Quality Score: has-scm-info

This score indicates whether the package has source control information defined within its package.json.

Always severity HIGH or NONE.

Quality Score: scm-tagged-versions

This score indicates whether an acceptable percentage of this package's version have a corresponding tag in their source control repository (if it exists).

Always severity MEDIUM or NONE.

Getting Started

ncm-cli is a command-line tool for NodeSource Certified Modules 2.0, designed to make code quality, security, and compliance a breeze. This allows you to generate a custom project report, fetch compliance and security information, manage organizational whitelists, and inspect specific packages in greater detail -- all from the command-line.

Installation

npm install -g ncm-cli

Usage

"usage"

Authentication

ncm-cli supports three forms of authentication.

1. NodeSource Account:

Sign-in interactively using your NodeSource account email and password.

$ ncm signin

2. Single Sign-on

  • Using a Google account: ncm signin -G, --google
  • Using a GitHub account: ncm signin -g, --github

3. Environment Variable (CI/CD)

$ NCM_TOKEN=<token> ncm <command> [options]

Learn more about obtaining service tokens and configuring permissions here.

Reports

ncm report

Generate and return a project report (defaults to the current directory) outlining package certification. To specify a directory on which to generate a report, simply pass the directory following the command. The top five riskiest modules will be displayed alongside your concise project report.

"report screen"

By passing --long, -l, the returned report will be formatted to give greater detail into individual package certification. This will include the module name, version, risk score, license compliance, and respective security vulnerabilities.

"extended report"

The report feature also includes the ability to filter depending on specified criteria.

Filter: Compliance

To display only non-compliant packages, pass the --compliance, -c flag.

Filter: Security

To display packages which contain at least one security vulnerability, pass the --security, -s flag.

Filter: Vulnerability Severity

You may also filter the report based on one or more severity levels. ncm-cli supports the following levels of severity: critical, high, medium, low. Passing the --filter= flag along with one or more of these filter parameters will result in a report that displays only packages that contain at least one such vulnerability.

"vulnerability"

ncm details <module{@version}>

Returns a detailed report about a specific module with version. ncm-cli will default to using the latest version.

"ncm details"

Whitelisting Packages

ncm whitelist

Display and modify your organization’s module whitelist.

ncm whitelist --list

Returns a list containing each module in your organization’s whitelist. Public modules are listed alongside their risk score, license compliance, and security summary.

"whitelist list"

ncm whitelist --add <module@version>

Add a module to your organization’s whitelist.

"whitelist add"

ncm whitelist --remove <module@version>

Remove a module to your organization’s whitelist.

"whitelist remove"

Switching Orgs & Config

ncm orgs

Change your active organization interactively by entering the orgs command without passing an <orgname>. By passing an organization name, ncm-cli will switch the active organization without prompting for input.

"switching orgs"

ncm config

ncm-cli allows access to various configuration settings. For more information, use the help command: ncm config --help

Help

ncm help

Display the NodeSource Certified Modules help menu. For more information on a specific command, run ncm <command> --help.