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 Certified Modules 2 also works in offline mode.

Migration Guide

If you are upgrading from NCM 1, here are the need-to-know steps for migrating to NCM 2.

Overview

NodeSource Certified Modules 2 (NCM 2) is a security, compliance and curation tool around the 3rd-Party Node.js & JavaScript package ecosystem. It is designed to be used in conjunction with npm to provide a layer of protection against known security vulnerabilities, potential license compliance issues, and providing general quality or risk assessment information to improve your ability to work with the 3rd-Party ecosystem.

Since the release of N|Solid 4.1.0, we have consolidated NCM 2 into a single product with NCM’s features being pulled into N|Solid as well as the N|Solid Console for optimal user experience.

Differences between NCM 1 and 2

  • ncm-cli (https://github.com/nodesource/ncm-cli) is a replacement for nscm (NCM 1), which is the command-line tool for NodeSource Certified Modules.

  • NCM 2 has been integrated into the N|Solid strict mode which can be used with the prompt nsolid-strict instead of the well known nsolid since the release of N|Solid 4.1.0 (ncm-cli is now the optional tool).

  • No private NCM registry required in NCM 2, whereas NCM 1 required.

  • 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.
  • NCM 2 also works in offline mode, whereas NCM 1 didn't support the offline mode.

Migrating data from NCM 1

whitelist is the only data that needs to be migrated from NCM 1 if you would like to keep using it. You can easily retrieve your existing whitelist of NCM 1 by running the command below:

$ nscm whitelist

Copy your whitelist and past it in the step Configuring-the-nsolid-strict-mode

Migrating CI/CD usage of NCM 1

Note: This step is only required if you are using NCM 1 with CI/CD

Since ncm-cli (https://github.com/nodesource/ncm-cli) replaced nscm, you can use the following environment variable with ncm for CI/CD.

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

Learn more about obtaining service tokens and configuring permissions here.

N|Solid strict mode

The N|Solid strict mode can be used with the prompt nsolid-strict instead of the well known nsolid, the key difference between strict and regular mode is that the strict mode will stop any application with encountered vulnerabilities identified by the NodeSource Certified Modules 2. See the N|Solid strict mode documentation for more information.

Configuring the N|Solid strict mode

Note: This feature is available in the latest version (higher than 4.4.1) of N|Solid.

The N|Solid strict mode allows custom configuration using JSON-based configuration. Run the prompt nsolid-strict with an option --config or -c to edit the JSON-based configuration file using your system's default text editor.

$ nsolid-strict --config

JSON-based Configuration File Structure

Below is the default configuration file that you can edit when you run the prompt nsolid-strict with an option --config or -c.

{
  "name": "nsolid-strict-config",
  "whitelist": {
     "package-name-to-whitelist": "^1.0.1"
  },
  "rules": [
     "readme-exists",
     "readme-size",
     "disk-usage-expanded-size",
     "disk-usage-file-count",
     "disk-usage-dir-count",
     "has-scm-info",
     "scm-tagged-versions",
     "has-install-scripts",
     "has-gyp-file",
     "uses-eval",
     "uses-dynamic-require",
     "missing-strict-mode",
     "has-unsafe-regexps",
     "uses-deprecated-node-apis",
     "has-lost-callback-errs",
     "has-abandoned-promises",
     "has-callback-in-async-function",
     "has-async-without-await",
     "license",
     "deprecated"
  ]
}

package-name-to-whitelist in the whitelist is just an example and you may delete this.

Key Description
name An arbitrary name of your custom configuration. You may change this, but if this is empty, your custom configuration will not be applied and considered as invalid.
whitelist Whitelist is specified in a simple object that maps a package name to a version range. The version range is a string which has one or more space-separated descriptors. You can also set a semver range or a specific version.
rules An array of scoring rules defined in NCM 2 (At least 1 rule should be set to make this valid). If no rules are set, it will be ignored. As such, you may remove this if you want the strict mode to ignore your modification on this.

Rules

nsolid-strict leverages all of the scoring rules of NCM 2 which are enabled by default. Rules in nsolid-strict are grouped by category to help you understand their purpose.

Rule: 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.

Rule: 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 build lifecycle step or rebuild command.

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

Rule: 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.

Rule: 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.

Rule: 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.

Rule: 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.

Rule: 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.

Rule: 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.

Rule: 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.

Rule: 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.

Rule: 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.

Rule: 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.

Rule: 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.

Rule: has-scm-info

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

Always severity HIGH or NONE.

Rule: 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.

Using NCM 2 with the Console

See the using-ncm2-with-the-console documentation for instructions on using this.

Using ncm-cli

ncm-cli (https://github.com/nodesource/ncm-cli) is a replacement for nscm (NCM 1), which is the command-line tool for NodeSource Certified Modules. See the Certified Modules 2 documentation for instructions on using this.

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.