nucleaus

CLI which can be used to interface with Nucleaus. Initiate scans, retrieve scan results, etc.

Usage no npm install needed!

<script type="module">
  import nucleaus from 'https://cdn.skypack.dev/nucleaus';
</script>

README

Nucleaus CLI

logo

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.

Table of Contents

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:

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]

Output

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.

TODO