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 fornscm
(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 knownnsolid
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 thewhitelist
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.