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.