Nucleaus NPM | npm.io

Nucleaus CLI

Making Code Scanning as Easy as Spell Check™

Command line interface (CLI) which can be used to interact with Nucleaus. Initiate scans, retrieve scan results, etc.

Overview
Installation
Authentication
Commands
Output
Release Notes

Overview

The primary goal of this project is to enable automation for use cases like CI/CD or other machine to machine type integrations. Using the CLI directly or through a script, you can for example initiate the scan of a repository and await the results.

Installation

Please review the release notes for updates on new features and potential breaking changes between versions.

The Nucleaus CLI requires Node.js >= 10.0.0. Install the CLI using: npm install -g nucleaus

Authentication

CLI commands require authentication which is accomplished by passing a token using either the --token option or by setting an environment variable NUCLEAUS_TOKEN.

Commands

The CLI supports a handful of commands. The basic format is: nucleaus <command> [options] where a command is required and may have zero or more options, some of which may be required.

The supported commands are as follows:

Config
Results
Scan

The default help output returned when running the CLI with no command specified of by supplying the --help or -h options can be seen below:

Usage: nucleaus <command> [options]

Commands:
  nucleaus config   Manage configuration/cache
  nucleaus results  Retrieve the results of a scan
  nucleaus scan     Scan a repository

Options:
  --token          Authentication token                      [string] [required]
  --tenant-id, -t  Id of the tenant                          [string] [required]
  --verbose, -v    Verbose output                                      [boolean]
  -h, --help       Show help                                           [boolean]
  -V, --version    Show version number                                 [boolean]

Options can all be defined using NUCLEAUS_ prefixed environment variables. For example, to provide the --tenant-id option via an environment variable, define and set an environment variable called NUCLEAUS_TENANT_ID.

Command specific help can be retrieved using nucleaus <command> --help or nucleaus <command> -h and is provided below for the available commands for reference.

Config

nucleaus config

Manage configuration/cache

Commands:
  nucleaus config clear  Clear the cached config

Options:
  --token                           [string] [required] [default: "placeholder"]
  --tenant-id, -t                   [string] [required] [default: "placeholder"]
  --verbose, -v    Verbose output                                      [boolean]
  -h, --help       Show help                                           [boolean]
  -V, --version    Show version number                                 [boolean]

Clear

nucleaus config clear

Clear the cached config

Options:
  --token                           [string] [required] [default: "placeholder"]
  --tenant-id, -t                   [string] [required] [default: "placeholder"]
  --verbose, -v    Verbose output                                      [boolean]
  -h, --help       Show help                                           [boolean]
  -V, --version    Show version number                                 [boolean]

Results

nucleaus results

Retrieve the results of a scan

Options:
  --token          Authentication token                      [string] [required]
  --tenant-id, -t  Id of the tenant                          [string] [required]
  --verbose, -v    Verbose output                                      [boolean]
  --scan-id, -s    Id of the scan                            [string] [required]
  --summary-type   Type of summary to return
                  [required] [choices: "ALL", "RISK_MANAGEMENT_EXCEPTIONS_ONLY",
                                "RISK_MANAGEMENT_EXCEPTIONS_EXCLUDED"] [default:
                                          "RISK_MANAGEMENT_EXCEPTIONS_EXCLUDED"]
  --format, -f     Format of the results              [string] [default: "json"]
  -h, --help       Show help                                           [boolean]
  -V, --version    Show version number                                 [boolean]

Scan

nucleaus scan

Scan a repository

Options:
  --token             Authentication token                   [string] [required]
  --tenant-id, -t     Id of the tenant                       [string] [required]
  --verbose, -v       Verbose output                                   [boolean]
  --repository, -r    Url of the repository                  [string] [required]
  --branch, -b        Name of the branch            [string] [default: "master"]
  --summary-type      Type of summary to return
                  [required] [choices: "ALL", "RISK_MANAGEMENT_EXCEPTIONS_ONLY",
                                "RISK_MANAGEMENT_EXCEPTIONS_EXCLUDED"] [default:
                                          "RISK_MANAGEMENT_EXCEPTIONS_EXCLUDED"]
  --async, -a         Queue a repository for scanning but do not wait for
                      completion                      [boolean] [default: false]
  --max-duration, -m  Max runtime duration in seconds    [number] [default: 900]
  -h, --help          Show help                                        [boolean]
  -V, --version       Show version number                              [boolean]

Exit Codes

The CLI uses exit codes to indicate success, errors and whether vulnerabilities were found for a given scan. The potential exit codes returned and their meaning are defined below:

0 = Command was successful / No vulnerabilities were found
1 = Command resulted in an error
2 = Vulnerabilities were found

Standard Output/Standard Error

Output (e.g. scan results formatted as json) is sent to standard output stdout whereas all other messaging (e.g. status/progress updates, errors, etc.) is sent to standard error stderr. This separation enables you to cleanly pipe or redirect output.

Release Notes

2.0.0

BREAKING CHANGES

Requires Node.js >= 10.0.0
With the introduction of Risk Management Exceptions, scan results and the summary details (e.g. vulnerability counts) will by default take into account any risk management exceptions that may apply to vulnerabilities of that scan. This means for example that if a scan finds one (1) potential vulnerability and that vulnerability has an approved non-expired risk management exception that applies to it, the vulnerability count returned will be zero (0). This impacts the results payload written to stdout along with how the returned exit code is determined. To override this default, see the summary-type parameter which can be provided when initiating a scan or when retrieving results.

The structure of the scan results payload written to stdout has been modified and improved to support risk management exceptions.

New tenant.scan.summary introduced which includes additional detail not returned previously
tenant.scan.vulnerabilityCount is now located under tenant.scan.summary.vulnerabilityCount
tenant.scan.severitySummary is now located under tenant.scan.summary.vulnerabilityCountBySeverity

Previously an example payload looked like:

{
  "tenant": {
    "id": "<TENANT_ID>",
    "scan": {
      "id": "<SCAN_ID>",
      "queuedAt": "2020-08-11T19:40:50.202Z",
      "startedAt": "2020-08-11T19:42:04.689Z",
      "completedAt": "2020-08-11T19:44:29.245Z",
      "resultStatus": "SUCCESS",
      "repository": {
        "url": "<REPOSITORY_URL>"
      },
      "branch": "master",
      "commitHash": "<COMMIT_HASH>",
      "vulnerabilityCount": 1,
      "vulnerabilities": [
        {
          "id": "NPM-1528"
        },
      ],
      "severitySummary": {
        "critical": 0,
        "high": 0,
        "medium": 1,
        "low": 0
      }
    }
  }
}

Now it will look this:

{
  "tenant": {
    "id": "<TENANT_ID>",
    "scan": {
      "id": "<SCAN_ID>",
      "queuedAt": "2020-08-11T19:40:50.202Z",
      "startedAt": "2020-08-11T19:42:04.689Z",
      "completedAt": "2020-08-11T19:44:29.245Z",
      "resultStatus": "SUCCESS",
      "repository": {
        "url": "<REPOSITORY_URL>"
      },
      "branch": "master",
      "commitHash": "<COMMIT_HASH>",
      "vulnerabilities": [
        {
          "id": "NPM-1528"
        },
      ],
      "summary": {
        "vulnerabilityCount": 1,
        "vulnerabilityCountBySeverity": {
          "critical": 0,
          "high": 0,
          "medium": 1,
          "low": 0
        },
        "vulnerabilityTypes": [
          {
            "vulnerabilityType": "dependency",
            "vulnerabilityIds": [
              "NPM-1528",
            ]
          },
        ],
        "riskManagementExceptionCount": 0,
        "riskManagementExceptionTypes": []
      }
    }
  }
}

Features

Updates existing capabilities to take into account Risk Management Exceptions which enables an organization to define rules that can mark vulnerabilities as false positives, acceptable risk or if there's a compensating control in place.
Updates to leverage the latest dependencies and replaces the now deprecated request.