WhiteSource CLI

Overview

The WhiteSource CLI is currently in beta. For broader support of languages and package managers, see the Unified Agent.

The WhiteSource Command Line Interface (WS CLI) is a tool that enables you to detect the security vulnerabilities and compliance data related to the open-source components within your development projects using a command-line shell. With a minimal configuration, the WS CLI enables you to start scanning your projects in your favorite terminal program:

  • Unix shells – Use shell programs to run commands on Linux and macOS.

  • Windows command line – On Windows, run commands at the Windows Command Prompt or in PowerShell.

Supported Platforms

  • macOS amd64

  • Linux amd64

  • Windows amd64

Installing WS CLI

Linux

Run the following command:

1 sudo curl "http://downloads.whitesourcesoftware.com/ws-cli/master/latest/ws-cli-linux-amd64/ws" -o "/usr/local/bin/ws" && sudo chmod +x "/usr/local/bin/ws"

Or install the CLI step by step.

macOS

Run the following command:

1 sudo curl "http://downloads.whitesourcesoftware.com/ws-cli/master/latest/ws-cli-darwin-amd64/ws" -o "/usr/local/bin/ws" && sudo chmod +x "/usr/local/bin/ws"

Or install the CLI step by step.

Windows

Create a designated directory for the WS CLI, for example C:\WhiteSource\cli and run the following command:

1 curl "http://downloads.whitesourcesoftware.com/ws-cli/master/latest/ws-cli-windows-amd64/ws.exe" -o "C:\WhiteSource\cli\ws.exe"

Or install the CLI step by step.

Installing step by step

In order to install the WS CLI, download the relevant binary for your system:

After downloading the ws binary, ensure that it is available on the PATH. You can either locate it in a directory that is already in your PATH (such as /usr/local/bin on Linux) or add the relevant directory to the PATH

Refer here for instructions on setting the PATH on macOS and Linux and here for instructions on setting the PATH on Windows.

Verifying the Installation

To verify the WS CLI installation, simply type ws:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 $ ws __ ___ _ _ ____ ____ _ ___ \ \ / / |__ (_) |_ ___/ ___| ___ _ _ _ __ ___ ___ / ___| | |_ _| \ \ /\ / /| '_ \| | __/ _ \___ \ / _ \| | | | '__/ __/ _ \ | | | | | | \ V V / | | | | | || __/___) | (_) | |_| | | | (_| __/ | |___| |___ | | \_/\_/ |_| |_|_|\__\___|____/ \___/ \__,_|_| \___\___| \____|_____|___| Usage: ws [command] Available Commands: clear Delete stored information completion Generate autocompletion script configure Configure WhiteSource parameters help Show help scan Run a scan status Check WhiteSource status version Display version and build details Flags: -h, --help Show help for command --no-colors Disable colored output Use "ws [command] --help" for more information about a command.

Quick Start

In order to start scanning your projects to detect the security vulnerabilities and compliance data related to the open-source components used by your code, follow these steps:

  1. Run the ws configure command to choose the WhiteSource URL and set the access token (User Key):

1 2 3 4 5 6 7 8 9 10 11 12 $ws configure WhiteSource URL selection: 1. https://saas.whitesourcesoftware.com 2. https://saas-eu.whitesourcesoftware.com 3. https://app.whitesourcesoftware.com 4. https://app-eu.whitesourcesoftware.com 5. https://essentials-saas.whitesourcesoftware.com 6. other Please select your choice [1]: User Key []: 123456e9e62d447a82caef5879a5f39349b87a21ab94420f87a5d07d7c654321 API Key []: Automatic Download [yes]:

Two more optional configurations are available: API key and Automatic Download. The API key can be set automatically if not provided. The Automatic Download setting determines if the user is prompted when additional components need to be downloaded.

2. Run the  ws scan in the root directory of your project:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 $ ws scan Initializing: Scanning: /web-server [...../] Retrieving: Security vulnerabilities and compliance information [...../] Identified 91 dependencies Found 9 vulnerabilities (7 High, 2 Medium, 0 Low) +----------+----------------------+------------------+-------------------------------------------------+ | SEVERITY | LIBRARY | ID | TOP FIX | +----------+----------------------+------------------+-------------------------------------------------+ | HIGH | base64-url-1.2.1.tgz | WS-2018-0111 | Upgrade to version 2.0.0 | +----------+----------------------+------------------+-------------------------------------------------+ | HIGH | fresh-0.3.0.tgz | CVE-2017-16119 | Upgrade to version fresh - 0.5.2 | +----------+----------------------+------------------+-------------------------------------------------+ | HIGH | mime-1.3.4.tgz | CVE-2017-16138 | Upgrade to version 1.4.1,2.0.3 | +----------+----------------------+------------------+-------------------------------------------------+ | HIGH | minimist-0.0.8.tgz | CVE-2021-44906 | Upgrade to version minimist - 1.2.6 | +----------+----------------------+------------------+-------------------------------------------------+ | HIGH | morgan-1.6.1.tgz | CVE-2019-5413 | Upgrade to version 1.9.1 | +----------+----------------------+------------------+-------------------------------------------------+ | HIGH | negotiator-0.5.3.tgz | CVE-2016-10539 | Upgrade to version 0.6.1 | +----------+----------------------+------------------+-------------------------------------------------+ | HIGH | qs-4.0.0.tgz | CVE-2017-1000048 | Upgrade to version qs - 6.0.4,6.1.2,6.2.3,6.3.2 | +----------+----------------------+------------------+-------------------------------------------------+ | MEDIUM | debug-2.2.0.tgz | CVE-2017-16137 | Upgrade to version 2.6.9 | +----------+----------------------+------------------+-------------------------------------------------+ | MEDIUM | minimist-0.0.8.tgz | CVE-2020-7598 | Upgrade to version minimist - 0.2.1,1.2.3 | +----------+----------------------+------------------+-------------------------------------------------+ Found 3 Policy violations +----------------------+---------------------+-------------+ | LIBRARY | POLICY TYPE | POLICY NAME | +----------------------+---------------------+-------------+ | morgan-1.6.1.tgz | Vulnerability Score | CVSS score | +----------------------+---------------------+-------------+ | base64-url-1.2.1.tgz | Vulnerability Score | CVSS score | +----------------------+---------------------+-------------+ | minimist-0.0.8.tgz | Vulnerability Score | CVSS score | +----------------------+---------------------+-------------+ Paths at risk express-3.21.2.tgz |-- mkdirp-0.5.1.tgz |-- minimist-0.0.8.tgz [1 HIGH, 1 MEDIUM, P] |-- fresh-0.3.0.tgz [1 HIGH] |-- send-0.13.0.tgz |-- mime-1.3.4.tgz [1 HIGH] |-- connect-2.30.2.tgz |-- morgan-1.6.1.tgz [1 HIGH, P] |-- qs-4.0.0.tgz [1 HIGH] |-- compression-1.5.2.tgz |-- accepts-1.2.13.tgz |-- negotiator-0.5.3.tgz [1 HIGH] |-- express-session-1.11.3.tgz |-- uid-safe-2.0.0.tgz |-- base64-url-1.2.1.tgz [1 HIGH, P] |-- debug-2.2.0.tgz [1 MEDIUM]

Supported Package Managers and Languages

The following package managers are supported natively:

  • NPM (Node.js)
    The open-source components used by your NPM project will be detected using the manifest (package.json) file of the project and the lock file (package-lock.json) or the node_modules directory. Make sure that the manifest file and either the lock file or the node_modules directory exist prior to the scan.

  • Yarn (Node.js)
    The open-source components used by your yarn project code will be detected using the manifest file (package.json) and the lock file (yarn.lock) of the project. Make sure that the manifest file and the lock file exist prior to the scan.

  • Maven (Java)
    The open-source components used by your Maven project will be detected using the Maven package manager. Make sure that Maven is installed and that your project is built (using the mvn clean install command) prior to the scan.

  • Gradle (Java)
    The open-source components used by your code will be detected using the Gradle package manager. Make sure that Gradle is installed and that your Gradle project is built (using the gradle build command) prior to the scan.

  • PIP (Python)
    The open-source components used by your code will be detected using the pip package manager. Make sure that pip is installed and that your Python project is built (using the pip install command) prior to the scan.

  • NuGet (C#)
    The open-source components used by your code will be detected using the declarative files of your C# project. Make sure that your project contains one of the following set of files:
    - .csproj and project.assests.json files
    - .csproj and packages.config and packages.lock.json files
    - packages.config and packages.lock.json files

  • Bundler (Ruby)
    The open-source components used by your code will be detected using the lock files used by Bundler:  Gemfile.lock or gems.locked. Make sure that either of them exists prior to the scan.

  • Composer (PHP)
    The open-source components used by your PHP project will be detected using the manifest (composer.json) and lock file (composer.lock) of the project. Make sure that the manifest file and the lock file exist prior to the scan.

  • Modules (Go)
    The open-source components used by your Go Modules project will be detected using the Go binary. Make sure that Go is installed and that your project includes the manifest file (go.mod) prior to the scan.

In addition, the CLI supports more than 200 programming languages by detecting source files and binaries via the Extended scanning option (when running ws scan -e).

Usage

Getting Help

In order to display the list of the supported WS CLI commands, type ws or ws help and a short description of any of the available commands will be displayed. 

In order to access more detailed information on each of the available commands, use the following syntax: ws [command] help

Commands

configure

The ws configure command enables the setting of the WS CLI.

This is an interactive command that enables you to set the WhiteSource URL, User Key, API Key, and the Automic Download settings.

  • WhiteSource URL- WhiteSource server URL. By choosing a number between 1 to 5 you can set one of the available URLs. The default value 1 corresponds to the https://saas-eu.whitesourcesoftware.com URL. By choosing number 6, you can set your own hosted WhiteSource address by specifying the URL in the following format: https://<URL>

  • User Key - WhiteSource access token, the only mandatory parameter. 

  • API Key - WhiteSource organization token. This is an optional parameter: if not provided, the organization will be set automatically.  

  • Automatic Download - determines if additional components will be downloaded automatically or the user will be prompted beforehand.

After all the parameters are set, the configuration will be validated by attempting to connect to the WhiteSource servers. If the validation is successful, the configuration will be cached locally.

Additionally, the ws configure command can be run in a non-interactive mode by passing the relevant parameters in the command-line.

The following flags are available:

1 2 3 4 5 6 7 Flags: --api-key string Set organization token -h, --help Show help for command --no-auto-download If set, no components (e.g. a portable JRE, the Unified Agent) will be downloaded automatically --url string Set WhiteSource URL (mandatory parameter in a non-interactive mode) --user-key string Set user key (mandatory parameter in a non-interactive mode)

help

The ws help command displays a short description of the available WS CLI commands. 

In order to get more detailed information on each of the available commands, the following syntax should be used: ws [command] help

clear

The ws clear command enables deleting the previously stored configuration and/or cache under the ~/.ws directory.

The following sub-commands are available:

1 2 cache Clear cache config Clear configuration

scan

The ws scan command enables detection of the security vulnerabilities and compliance data related to the open-source components used by development projects.

Run the ws scan command in the root directory of your project.
The following flags are available:

1 2 3 4 5 6 Flags: -e, --extended Perform a file system scan for source files and binaries, in addition to the package manager based dependencies resolution --format string Set the command output format. Supported formats are: json and text (default "text") -h, --help Show help for command -s, --scope string Set the WhiteSource scope, by specifying the hierarchy (full or partial): -s ORGANIZATION//PRODUCT//PROJECT -u, --update Update the inventory of the WhiteSource project

status

The ws status command enables validating the connectivity to the WhiteSource servers. The output Status: OK indicates the validation was successful.  

version

The ws version command displays information on the WS CLI version and build. 

Advanced

  • Proxy
    Proxy settings are available via the HTTP_PROXY or HTTPS_PROXY environment variables. 

Limitations

Currently, only organizational administrators and auditors (read-only administrator) have permission to perform scans with the WS CLI tool.