NCM Overview

NodeSource Certified Modules

NodeSource Certified Modules provides a screen that provides an additional layer of safety to your use of third-party Node.js packages. Using a series of tests, we score every single package on npm to look for a number of weighted criteria. With the npm cli tool configured to use your Certified Modules registry, npm install will refuse to install any third-party package that does not meet the bar.

Overriding Certification Scores

You may occasionally come across a package that fails criteria but you don't yet have a work-around or alternate to use. Our whitelist tool can be used to override the certification screen and allow installation of any package.

Our suggestion is when you are forced to whitelist a package, you follow one of these paths to resolution versus keeping it indefinitely on the whitelist:

1. Find an alternate package that passes certification
2. PR or work with the package author to attempt to improve the certification score
3. Rewrite the functionality you need internally

NodeSource Platform

NodeSource Certified Modules access is set up and authenticated through the NodeSource Platform. The Platform provides a simple search interface for the certification scores for packages, user settings, and access to billing and subscription information.

How it Works

NodeSource Certified Modules works by putting a private registry between your code and the public npm registry. You connect to the private registry for all your package installation needs. The private repository is automatically updated with the recent changes to the public registry, and it will prevent any package that does not meet the certification criteria from installing, ensuring you have a safe environment. If a module has failed to meet our certification criteria but you've reviewed it and are willing to allow it to be installed, you may override the certification screen by adding it to your whitelist.

Quick Start Guide

NodeSource Certified Modules is a server-side solution and works with the existing npm client.

Authentication

To install npm packages from NCM, follow these steps:

Create an account in the NodeSource Platform

Open a browser and navigate to the NodeSource Platform. Next, create an account with your email address or by connecting to an existing GitHub or Google account.

Install the nscm command-line tool.

$ npm -g install nscm

Log into NodeSource Certified Modules at the command-line.

$ nscm signin

If you created your account with Github or Google as your identity provider, use:

$ nscm signin --github or $ nscm signin --google

See setup for more information on signing in.

You should now be set up to install packages via your normal npm workflow.

See Whitelisting Packages for more information about the nscm tool.

Configuring npm

Logging in with nscm

NodeSource Certified Modules provides a signin command from the nscm tool to authenticate with your registry. It will automatically set your local .npmrc registry URL to set up workspace-specific authentication.

• $ nscm signin
• $ nscm signin --github
• $ nscm signin --google

If you created your account with an email and password, run the command without the --github or --google flags and follow the prompts to log in. If you created your account using Single Sign-On provided by Google or Github, use the appropriate flag. This will open a browser window allowing you to sign in with your identity provider. Once signed in you will see an authentication code; copy the provided code and paste it into the prompt at the command-line.

You should now be authenticated in this project location for your NodeSource Certified Modules registry. You can repeat this process in each project you wish to use with NodeSource Certified Modules to configure each registry. Alternatively, you can copy your local .npmrc file from one project to another if you would like to use the same team and whitelist.

After you've logged in, you can use the following command to see what email address you are logged in with:

$ npm whoami

Note A project is any set of files governed by a single package.json file.

Signing out with nscm

To sign out, use the nscm signout command.

$ nscm signout

This will remove login token from your npm configuration information, but it will not change your registry URL configuration.

More information on npm configuration

For reference, here are links to npm's documentation on configuration:

• managing configuration files - https://docs.npmjs.com/cli/config
• using .npmrc files - https://docs.npmjs.com/files/npmrc
• npm configuration values - https://docs.npmjs.com/misc/config

NodeSource Certification Score

The NodeSource Certification Process is an extensive suite of tests based on attributes that are valuable to customers. We are attempting to capture the best signals that determine the quality, security, and overall health of any given package in the npm ecosystem.

We expect the calculation of this score to change over time as we incorporate feedback about additional signals that are important to professional users of Node.js.

Scoring Criteria

The current scoring criteria used are:

• Package has a README file
• Package's source code is in public source control
• Package and its dependency tree are open-source licensed with any of: Apache, BSD, ISC, or MIT
• Disk usage after npm install is < 25 MB
• There are no known security vulnerabilities in the package or its dependency tree

Whitelisting Packages

nscm is a simple utility to whitelist non-certified packages and can be used to generate a report of matching certified packages in a specified private registry.

Installation

You can install it from npm by running:

$ npm install --registry=https://registry.npmjs.org -g nscm

Note: nscm currently supports npm <= 4.x

Usage

This tool is meant to be used in the root folder of an application where the package.json file exists.

  NodeSource Certified Modules

  Usage: nscm [command] [options]

  Commands:

    config, c           Configure nscm options
    help                Display help
    report, r           Get a report of your packages
    signin, s, login    Sign in to nscm
    signout, o, logout  Sign out of nscm
    whitelist, w        Whitelist your packages

  Options:

    -c, --concurrency <n>  Concurrency of requests (defaults to 15)
    -d, --dot              Formats the report in Graphiz dot (disabled by default)
    -g, --github           Sign in using GitHub SSO (disabled by default)
    -G, --google           Sign in using Google SSO (disabled by default)
    -h, --help             Output usage information
    -j, --json             Formats the report in JSON (disabled by default)
    -p, --production       Only check production (disabled by default)
    -r, --registry         Certified modules registry (defaults to "")
    -s, --svg              Formats the report in SVG (disabled by default)
    -t, --token            Token for registry authentication (defaults to "")
    -v, --version          Output the version number

  Additional Help

    Add -h to the 'config' and 'whitelist' commands for additional help concerning those commands.

    nscm config -h
    nscm whitelist -h

nscm signin

Sign in to your NodeSource Certified Modules account, you can use Single Sign-On by passing --github or --google and it will prompt for an authentication code that will be given to you in a browser window.

Example:

$ nscm signin --google
open a browser and navigate to: https://nodesource.auth0.com/authorize?connection=google-oauth2&audience=https://nodesource.auth0.com/userinfo&scope=email%20offline_access%20openid&device=nscm&response_type=code&client_id=xxxxx&code_challenge=xxxxxx&code_challenge_method=S256&redirect_uri=https://platform.nodesource.io/pkce
a browser will launch and ask you to sign in.

once you have the authorization code, please enter it here:

nscm report (default)

Returns a report of matching certified packages and their certification scores.

$ nscm report
please wait while we process the information
┌────────────────────────────────────┬───────────────┬────────┐
│ Package                            │ Version       │ Score  │
├────────────────────────────────────┼───────────────┼────────┤
│ body-parser                        │ 1.15.2        │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ debug                              │ 2.2.0         │ 70     │
├────────────────────────────────────┼───────────────┼────────┤
│ ms                                 │ 0.7.1         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ bytes                              │ 2.4.0         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ content-type                       │ 1.0.2         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ depd                               │ 1.1.0         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ http-errors                        │ 1.5.1         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤
│ inherits                           │ 2.0.3         │ 100    │
├────────────────────────────────────┼───────────────┼────────┤

You can also pass --json to return the report in JSON format or --production to return only dependencies and not devDependencies.

$ nscm report --production --json
please wait while we process the information
[
  {
    "name": "body-parser",
    "version": "1.15.2",
    "from": "body-parser@>=1.15.2 <1.16.0",
    "score": 100
  },
  {
    "name": "debug",
    "version": "2.2.0",
    "from": "debug@>=2.2.0 <2.3.0",
    "score": 70
  },
  {
    "name": "ms",
    "version": "0.7.1",
    "from": "ms@0.7.1",
    "score": 100
  },
  {
    "name": "bytes",
    "version": "2.4.0",
    "from": "bytes@2.4.0",
    "score": 100
  },
...

You can also output the report in SVG format by passing --svg, or in Graphiz dot format by passing --dot.

nscm whitelist

Check which packages aren't certified, and start an interactive prompt to add packages to the whitelist.

$ nscm whitelist
please wait while we process the information

37 packages aren't certified, do you want to add them to the whitelist?
? add debug@2.2.0 Yes
? add setprototypeof@1.0.2 Yes
? add statuses@1.3.1 No
? add ee-first@1.1.1 No
? add unpipe@1.0.0 (ynaH) All

┌────────────────────────────────────┬───────────────┬────────┐
│ Package                            │ Version       │ Score  │
├────────────────────────────────────┼───────────────┼────────┤
│ debug                              │ 2.2.0         │ 70     │
├────────────────────────────────────┼───────────────┼────────┤
│ setprototypeof                     │ 1.0.2         │        │
├────────────────────────────────────┼───────────────┼────────┤
...
├────────────────────────────────────┼───────────────┼────────┤
│ source-list-map                    │ 0.1.8         │        │
├────────────────────────────────────┼───────────────┼────────┤
│ webpack-core                       │ 0.6.9         │        │
└────────────────────────────────────┴───────────────┴────────┘
35 packages added to the whitelist

You can also pass --all to add all the packages to the whitelist and --json to return the packages in a JSON format.

nscm whitelist add

Add a package and its dependencies to the whitelist.

$ nscm whitelist add debug@2.x

If you pass only the package name, nscm will use latest. You can also pass a semver range or a specific version. If a semver range is passed it will be resolved to the highest published version that matches the range.

nscm whitelist delete

Delete a package from the whitelist.

$ nscm whitelist delete debug

nscm whitelist list

Lists all whitelisted packages.

$ nscm whitelist list
┌────────────────────────────────────┬───────────────┬────────┐
│ Package                            │ Version       │ Score  │
├────────────────────────────────────┼───────────────┼────────┤
│ acorn                              │ 4.0.1         │        │
├────────────────────────────────────┼───────────────┼────────┤
│ isarray                            │ 2.0.1         │        │
└────────────────────────────────────┴───────────────┴────────┘
2 packages in the whitelist

nscm whitelist reset

Removes all packages from the whitelist. This does not remove packages from the project directory.

nscm config

Configuration Options

• token - Authentication Token. If not specified, it will be fetched from ~/.npmrc - required
• registry - Private NodeSource Certified Modules registry URL. If not specified, it will be fetched from ~/.npmrc - required
• concurrency - Concurrency of requests to package registry - default: 15

nscm config set <key> <value>

Modify the specified configuration option.

$ nscm config set concurrency 10

nscm config get

Displays a configuration key's value.

$ nscm config get registry
https://{registryId}.registry.nodesource.io

nscm config delete

Deletes a configuration option.

$ nscm config delete token

nscm config list

List all configuration options.

$ nscm config list
concurrency = 15
registry = https://{registryId}.registry.nodesource.io

User Management

Signing in to your account

You can sign in with the email address associated with your account, and your password.

1. Go to https://platform.nodesource.io/signin.
2. Select an identity provider, or enter your NodeSource Account email address and password.
3. Click SIGN IN.

Trial Team Creation

Within NodeSource Certified Modules, a team is a group of users who share a whitelist for a given project. Whitelists are override lists to allow installation of packages that fail certification. See "whitelisting" for more information about whitelists.

If you're not already on a team, you will be prompted to create a new team. Follow the steps to create your first team. Selecting "Trial" will give you a team with a maximum of 5 users (inluding you) for 14 days. You may upgrade at any time to switch to a full-fledged account. Choose a team name that you can associate to the project and a billing email address to use for any future billing invoices. Billing email addres is where we'll send invoices if you upgrade to a paid plan. Adding a billing email address does not add a new team member, and it is not necessary to create a NodeSource login for this email address. Click "Create Team" and you're all set! You've created your trial team.

Team Management

After you've set up your first team, you can invite additional members to join it (this is optional).

To add additional team members, click the 'Add Team Members' button.

Once the user is added, they will be shown as "pending" in the members list.

Once they have received their activation email and clicked the activation link, they will be able to use your team's NodeSource Certified Modules Registry for their npm needs.

Membership Roles

There are three roles available to NodeSource Accounts:

1. Member
2. Whitelist Admin
3. Admin

Member

Members of your team can use the team registry for npm installation and nscm lookups, but cannot edit the team's whitelist or view or update team settings or billing information. Each team member will use nscm to configure their npm tool to use the team-specific registry.

Whitelist Admin

A Whitelist Admin can do anything a Member can do and additionally add or remove items from the team's shared whitelist. A Whitelist Admin cannot view or update team settings or billing information.

Admin

An Admin can perform any action available to the team, performing any task that a Member or Whitelist Admin can do. In addition, an Admin can add and remove users or alter their roles, change team settings, and update billing information.

Changing Your Password

If you want to change your account password, proceed with the steps below.

1. In the upper right next to your name, click the three-line menu icon and select "Profile"
   
   
2. In the PASSWORD section, click CHANGE PASSWORD.
   
   
3. Type your old password as indicated and click NEXT.
   
   
4. Type the new password and click SAVE.
   
   

Searching For Certified Packages

To find information about a particular package in NodeSource Certified Modules, use the "Certified Modules" page.

1. Navigate to the "Certified Modules" search page

2. Enter a search term (e.g., 'express')

3. If the module you're looking for isn't on top, try sorting by name or download count

4. Clicking on any of the modules in the search results will take you to a detail page that provides details on the scoring criteria affecting the module's score.

Notes:

• Only the latest released version of each matching module will be returned. Newer modules with semver pre-release versions may be available, but they will not appear in search results.

• Use the "Prev" and "Next" buttons to navigate pages, or jump to a specific page by entering a different page number into the box at the bottom and hitting the enter or return key.

• Search results are currently limited to 1000 pages.

Subscription & Billing

NodeSource Certified Modules is a subscription-based service. Use our 14-day free trial to get started, or upgrade to our enterprise plan to get continuing access to secure, trusted, and reliable Node.js modules.

Subscription Plans

Please contact us to discuss an Enterprise subscription.