Overview
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:
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:
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:
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
:
$ 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):
$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.
2. Run the ws scan
in the root directory of your project:
$ 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 thenode_modules
directory. Make sure that the manifest file and either the lock file or thenode_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 themvn 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 thegradle 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 thepip 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
andproject.assests.json
files
-.csproj
andpackages.config
andpackages.lock.json
files
-packages.config
andpackages.lock.json
filesBundler (Ruby)
The open-source components used by your code will be detected using the lock files used by Bundler:Gemfile.lock
orgems.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:
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:
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:
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 theHTTP_PROXY
orHTTPS_PROXY
environment variables.
Limitations
Currently, only organizational administrators and auditors (read-only administrators) have permission to perform scans with the CLI.