Top

NCM Desktop

What is NCM?

NodeSource Certified Modules (NCM) is NodeSource's package monitoring tool for quality, compliance, and security assurance that helps you take advantage of third-party Node.js modules. By utilizing a set of strict certification criteria for public Node.js modules, NCM provides an added layer of trust and risk mitigation for your Node.js projects.

The NCM Desktop application, supported for macOS, Linux, and Windows, continuously monitors your local npm installs and can flag the installation of packages that do not meet critical trust criteria for your organization. This helps your team identify security vulnerabilities, manage module licenses, and operationalize Node.js package management, with the added benefit of a developer-friendly desktop application.

Feature Overview

NCM Desktop contains a potent combination of security tools and application management options. Below is a brief overview of each feature.

Project risk overview

A rich user interface gives an intuitive overview over your organizations projects and each project's risk level. Open a project list used modules and sort by name, number of issues, or score. In order to see actionable steps towards a healthier project, modules may be filtered by vulnerable, noncompliant, whitelisted, recently added, and recently removed.

Detailed module status

Our certification pipeline analyzes each and every module in the public npm registry, so NCM Desktop can help you assess a module's risk or potential. See which top level dependency brought in a questionable module, get detailed reports about found vulnerabilities and code quality, and ensure the project's license is not a deal breaker for you.

Whitelists

Depending on your project's risk profile and use case, you may wish to use a module which does not meet our certification threshold. In these cases, you can override the certification score by adding the module to your organization's whitelist. This allows you to acknowledge the issue but continue your work for now.

Yarn Support

NCM Desktop now supports Yarn as a first-class package manager, in addition to the npm cli application.

The Basics:

If you've already installed and used NCM 1.x, you can still try out the NCM Desktop Beta without making any irreversible changes to your current installation—both tools can work side by side.

NCM Desktop no longer needs the previous modifications it made to your .npmrc file. After deleting the file, continue with the installation steps below. NCM 1 - Migrate

Sign Up

Authentication and access for NCM Desktop is managed via the NodeSource Accounts service. A new account may be created by visiting the Sign Up page on accounts.nodesource.com. You can sign up using an email address, Google Account, or GitHub Account. Sign Up

Installation

You can install NCM Desktop Beta on your macOS, Linux, or Windows machine. To download and install, go to the downloads page in your NodeSource Account, select your operating system, and follow the instructions.

Sign In

While you will be required to create your NodeSource account on accounts.nodesource.com, you can sign in to NCM Desktop without exiting the application. To do so, select the specific sign in method used during sign up. Sign In

Reset Password

Your account password may be reset by selecting Reset Password on the Login page. You will be redirected to accounts.nodesource.com to reset your password. Sign In Reset

Add your project

The Projects List makes up the central hub for NCM Desktop. To add your first project to NCM Desktop, select the Add a Project button and continue to select the source of your project. Additional projects may be added by selecting the + icon, located in the title bar.

Once a project is linked to NCM Desktop, its dependencies will be watched and this and any further modifications to the project's state are tracked. This allows NCM Desktop to show you all packages and dependencies installed in a given project, as well as the license information, security details, and overall quality of packages installed. To obtain more information about a specific project, select it from the Projects List. Projects -Installs Projects - Installs List

Project Detail

By drilling down into the details of a specific project, NCM Desktop reveals additional information about each and every package installed. Each installed package is listed along with its certification score located on the left hand side; the current version is also displayed alongside the package name.

If a module has been brought in via another module, a little dependency icon will indicate this and on hover show you a list of all top level dependencies that require this one. Note that for performance reasons NCM Desktop will only inspect your project's lockfiles, if they're available, to deduct the dependency tree, so if your node_modules folder is out of date that won't be reflected in the app.

Located on the far right hand side of the list, tags are displayed which correspond to the package license status and any known security vulnerabilities introduced by the package, as well as indicating recently added or removed modules. Selecting the package will display the Module Detail view, providing further information.

Install Details

The top menu bar contains three additional features to help you navigate:

Install details toolbar

Sorting: On the left hand side, the Sort section enables the sorting of modules by Name, Issues, and Score.

Filtering: The Show section in the centre enables you to select whether to show vulnerable, noncompliant, or whitelisted modules, recently added or removed, or to display all installed.

Alternatively click on the vulnerability and compliance summaries in the header to also filter the list by vulnerable and noncompliant modules.

Keyword Search: On the right hand side, the search section will let you filter modules by name using text input.

Module Detail

The most granular details are available on the Module Details page, which can be accessed by selecting a package from the Projects List. The Module Details page provides a comprehensive status for a specific installed package.

The header gives a quick overview of the module's score, vulnerabilities and compliance issues, as well as when it was published.

If you're looking at a module implicitly brought in via another dependency, the Required By section will let you trace all the paths leading towards it.

Any security vulnerabilities, license compliance, or quality issues will be shown in this view, alongside upgrade suggestions for both security and compliance categories.

The package's README file is also available; just select View README on the right hand side of the Module Details pane.

You may add or remove a specific package from your organization's whitelist through the Add/Remove from whitelist action in the sidebar. Whitelisting is available on the Professional and Enterprise tier of NCM Desktop only.

In addition, by selecting More Details, the module's npm page will open in your browser, allowing for further insight into your installed packages. Module Detail

Settings

The Settings view is available by selecting the gear icon in the upper right hand corner of any page. The settings view is divided into two segments, all viewable near the top of the application.

The Preferences tab handles local preference settings for NCM Desktop. Clicking the Clear Cache button clears the cache of packages managed by npm. Periodic clearing of the cache will free up disk space and help avoid module version issues. Preferences

The Linked Projects tab lists all projects with their respective file paths and last modification date. Click the x icon to stop watching a project's files. Projects

Organizations

Organizations allow the collaborative use of NCM Desktop across your team or company. Projects may be filtered by Organization using the organization selector dropdown, located on the right hand side of the title bar. You are able to switch between organization accounts and your personal NodeSource account through this menu, as well as return to the Projects List from anywhere in the app.

Inactive Org

When your team's trial period ends, you will be met with the Inactive Organization page. From here, you may create another organization, or receive your team owner's email in order to contact them directly regarding your inactive organization. Users can continue to use NCM Desktop with Developer tier entitlements selecting the Personal option from the drop down selector located in the top right corner. Organization Inactive

Simultaneously, your Organization Admin will be notified next time they intend to log in. By selecting the Upgrade button, admins may upgrade their organization to the Professional or Enterprise Tier via accounts.nodesource.com. Individual members of your organization will still be able to use NCM Desktop but will not be able to do so collaboratively as part of an Organization until your account has been upgraded. Trial Over

Application Menu

From the application menu, you are able to manage application settings. The menu allows for clearing of the npm cache and enabling or disabling Launch at Login. Additionally, you can log out or quit the application from this menu. Tray Menu

Migrating from NCM Desktop 2.0.0-beta2

There was an issue around generated package-lock.json, npm-shrinkwrap.json, and yarn.lock files in which the local NCM Desktop Beta registry proxy is locked as the source registry in each of these files.

This potentially caused issues for anyone without NCM Desktop Beta installed and running who tries to npm install or yarn install, as the registries outlined in package-lock.json, npm-shrinkwrap.json, and yarn.lock won't be accessible and the modules will fail to install.

NCM Desktop will offer to migrate a project when it first detects install activity in it:

Migration Wizard

NCM CI

Overview

Use ncm-ci to bring NodeSource Certified Modules to your CICD systems, and ensure on each commit that only certified modules or the ones you whitelisted yourself can make it into your dependency tree.

example

First create a service token, then set it up in your CICD system.

Create a token

Log in to accounts and head over to your organization settings page to create a new service token:

Service Tokens

Give the token any name, but it's important that it has the following permissions:

  • NCM Whitelist : read
  • NCM Certification Data : read

Take note of the generated token, as you will need to set it as an environment variable on your CICD system. The token will allow access with the designated permissions to your organization and should be kept private to your team.

Setup

ncm-ci is distributed via npm and is best invoked via npx, which was introduced to npm in `npm@5.2.0`:

$ npx @nodesource/ncm-ci

Set the environment variable NCM_TOKEN to the service token created in the last step and run ncm-ci in your project's root directory. A non-0 exit code will tell your CICD pipeline that verification failed, with a concise report of the modules in question:

fail

pass

Recipes

Following are a couple example configurations for popular CICD providers.

Check out nodesource/ncm-ci-example for a fully set up repository with various CICD systems configured and active.

Travis

sudo: false
language: node_js
node_js:
  - node
script:
  - npm test
  - npx @nodesource/ncm-ci

AppVeyor

install:
  - ps: Install-Product node ''
test_script:
  - npm test
  - npx @nodesource/ncm-ci
build: off

CircleCI

version: 2
jobs:
  build:
    docker:
      - image: node:10.0
    steps:
      - checkout
      - run: npm install
      - run: npm test
      - run: npx @nodesource/ncm-ci