Table of Contents

Overview

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

The Mend Command Line Interface (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 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 the CLI

Linux

Run the following command:

Code Block
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:

Code Block
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 CLI, for example C:\Mend\cli and run the following command:

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

Or install the CLI step by step.

Installing step by step

In order to install the 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 CLI installation, simply type ws:

Code Block

$ ws
 __  __                _    ____ _     ___ 
|  \/  | ___ _ __   __| |  / ___| |   |_ _|
| |\/| |/ _ \ '_ \ / _  | | |   | |    | | 
| |  | |  __/ | | | (_| | | |___| |___ | | 
|_|  |_|\___|_| |_|\__,_|  \____|_____|___|

Usage:
  ws [command]

Available Commands:
  clear       Delete stored information
  completion  Generate autocompletion script
  configure   Configure Cli parameters
  help        Show help
  scan        Run a scan
  status      Check 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:

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

Code Block

$ws configure
URL selection:
  1. https://saas-eu.whitesourcesoftware.com
  2. https://saas.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.

...

Code Block

$ ws scan
Initializing: 
Scanning: /web-server [...../]
Retrieving: Security vulnerabilities and compliance information [...../]

Identified 91 dependencies

Found 9 vulnerabilities (6 High, 3 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     | 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       |
+----------+----------------------+------------------+-------------------------------------------------+
| MEDIUM   | minimist-0.0.8.tgz   | CVE-2021-44906   | Upgrade to version minimist - 1.2.6             |
+----------+----------------------+------------------+-------------------------------------------------+

Found 2 Policy violations
+----------------------+---------------------+-------------+
| LIBRARY              | POLICY TYPE         | POLICY NAME |
+----------------------+---------------------+-------------+
| base64-url-1.2.1.tgz | Vulnerability Score | CVSS score  |
+----------------------+---------------------+-------------+
| morgan-1.6.1.tgz     | Vulnerability Score | CVSS score  |
+----------------------+---------------------+-------------+

Paths at risk

P = policy violation
HIGH/MEDIUM/LOW = security vulnerability severity

express-3.21.2.tgz
|-- mkdirp-0.5.1.tgz
	|-- minimist-0.0.8.tgz [2 MEDIUM]
|-- 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 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 CLI.

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

Mend URL- Mend 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 Mend address by specifying the URL in the following format: https://<URL>
User Key - Mend access token, the only mandatory parameter.
API Key - Mend 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 Mend 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:

Code Block

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 Mend 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 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:

Code Block
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:

Code Block

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 Mend scope, by specifying the hierarchy (full or partial): -s ORGANIZATION//PRODUCT//PROJECT
  -u, --update          Update the inventory of the Mend project

status

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

version

The ws version command displays information on the 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 administrators) have permission to perform scans with the CLI.This page is available at: https://docs.mend.io/bundle/sca_user_guide/page/mend_cli.html

Versions Compared

Old Version 55

New Version 56

Key

Overview

Supported Platforms

Installing the CLI

Linux

macOS

Windows

Installing step by step

Verifying the Installation

Quick Start

Supported Package Managers and Languages

Usage

Getting Help

Commands

configure

help

clear

scan

status

version

Advanced

Limitations

Page Comparison

Versions Compared

Old Version 55

New Version 56

Key

Overview

Supported Platforms

Installing the CLI

Linux

macOS

Windows

Installing step by step

Verifying the Installation

Quick Start

Supported Package Managers and Languages

Usage

Getting Help

Commands

configure

help

clear

scan

status

version

Advanced

Limitations