WhiteSource SAST® ships with cross-platform (Windows, Linux , and macOS) API command line clients that provide a simple way to integrate the WhiteSource SAST® API into automated processes.
Minimum System Requirements
The minimum system Requirements for the Command Line (CLI) client are listed here.
Download Links
Linux Version – Download Link
https://downloads-sast.whitesourcesoftware.com/sast-cli/linux/wssastcli
Windows Version – Download Link
https://downloads-sast.whitesourcesoftware.com/sast-cli/windows/wssastcli.exe
MacOS
NOTE: On MacOS, you must install Docker before configuring WhiteSource SAST.
MacOS (Intel) Link
https://downloads-sast.whitesourcesoftware.com/sast-cli/mac/wssastcli
MacOS (ARM) Link
https://downloads-sast.whitesourcesoftware.com/sast-cli/macarm/wssastcli
Usage
NOTE: The CLI now automatically updates to the newest version before it runs.
When you onboard WhiteSource SAST, you can choose to:
configure the CLI interactively, in which case a wscli-config.json file will be created with all the set parameters inside and can be adapted afterwards, or
after completing the onboarding, you can specify the location of a pre-existing configuration file with the --config option.
Almost all the parameters can be defined as environment variables or as JSON variables in the configuration file.
Parameters
The command line client accepts the following parameters.
Authentication
parameter | |
---|---|
JSON: url | Specifies the URL of the WhiteSource SAST® API instance, in general, https://sast.whitesourcesoftware.com/ |
JSON: token | Specifies the WhiteSource SAST® API token to be used with all requests. |
Configuration
parameter | |
---|---|
--engines [list of engines] | Accepts a comma separated list of SAST engine/language IDs to be used in the analysis (e.g., 1,2). This list can also be set through the environment variable SASTCLI_ENGINES. If omitted, WhiteSource SAST® will perform an auto-language recognition. |
--template [name] | Specifies the scan configuration template created in the web UI. |
--dir [directory] | Specifies target directory for SAST testing. |
--app [application] | Specifies scan parent application name and inherits its parameters. |
--name [name] | Specifies scan name. This parameter is defined separately for each scan so cannot be defined as JSON or ENV variable. |
--baseline-[bool] | Indicates if the CLI should upload the scan data as a new baseline for incremental scans. The baseline will include minimum relevant fragments of code representation in order to enable incremental scans. |
--inc=[bool] | Indicates if the scan should be incremental. |
--config [path] | Specifies CLI JSON configuration file path. |
– baselinestorage [path] | Specifies the location of the baseline dump. |
Submitted Data
parameter | |
---|---|
--submitsnippets=[bool] | Indicates if vulnerability-relevant snippet files should be submitted with results |
--submitlogs=[bool] | Indicates if CLI and engine logs should be submitted to WhiteSource. The CLI and engine logs will be submitted to the SAST server, but if you want to manually review them, they are located under the user's HOME directory (%USERPROFILE% on Windows and $HOME on Linux), in the .sastcli/logs directory. |
--snippetsize [size] | Specifies the size of source code snippets submitted to the SAST server. The default value is 10, the minimum value 1. An example can be found below this table. |
WhiteSource SAST® will not upload your full source code to the cloud. It only stores as much information as necessary to help you understand the dataflow of a detected finding. By default, snippets with a length of 10 lines are uploaded, but you can further reduce this to one single line.
protected AttackResult injectableQuery(String accountName) { String query = ""; try (Connection connection = dataSource.getConnection()) { query = "SELECT * FROM user_data WHERE first_name = 'John' and last_name = '" + accountName + "'"; try (Statement statement = connection.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATABLE)) { if ((results != null) && (results.first())) { ResultSetMetaData resultsMetaData = results.getMetaData(); StringBuilder output = new StringBuilder();
Reports
parameter | |
---|---|
--report=[bool] | Indicates if the CLI should generate a report through the server. This parameter must be used in combination with --formats. Can be used in combination with --filename to specify the filename of generated reports (without extension). Reports can only be generated if --wait is not set to false (default is true and the wait parameter can be omitted). |
--formats [formats] | A comma separated list of report formats to be generated at the end of the scan (html,json,xml,pdf,csv,sarif) |
--filename [filename] | Specifies the filename of the generated report. The input should be without a file extension as the extension will be automatically appended based on the --formats input. If not specified, the filename will be automatically set Report-%ID%, where %ID% is the scan ID. |
Other
parameter | |
---|---|
--numcpu [num] | Specifies the number of logical CPUs for multicore processing. Default is maximum. |
--nocolor=[bool] | Indicates if the CLI should use colored standard output. |
--noprogress=[bool] | Indicates if the CLI should show a progress bar. |
Threshold Variables
The following variables can only be defined in the configuration file or as environment variables.
Their use is closely related to pipeline integrations, and enables breaking the build or pipeline process by returning an exit code 9 if a threshold is violated.
For example, if the threshold is set to "high:5" the build will be broken if the scan results contain 5 or more high risk vulnerabilities. If it is set to “low:3”, the build will be broken if the scan results contain a combination of 3 or more vulnerabilities of low risk, medium or high risk. Similarly, with a threshold of “medium:3” the build will be broken if it contains three or more vulnerabilities of medium and/or high risk.
NOTE: There is no automatic or implied dependency among the high, medium, and low thresholds. Each threshold must be specified separately, and they are ORed together. For example, “high:3”, “medium:4” and “low:5” means that if any of these thresholds is exceeded, the build will break.
The CWE threshold works somewhat differently: it does not take into account the number and severity of the findings. Instead the CWE threshold will break the build if any finding is reported whose CWE number matches one of the CWE numbers specified in the parameter. For example, "cwe": ["CWE-89", "CWE-77"] specifies that any finding for CWE number 89 (SQL Injection) or for CWE number 77 (Command Injection) will break the build. Other findings will not break the build.
These parameters can also be set through the SASTCLI_THRESHOLD environment variables (see the table below).
parameter | |
---|---|
JSON: threshold:high | |
JSON: threshold:medium | |
JSON: threshold:low | |
JSON: threshold:cwe |
Example Usage
Initiating a scan against a Git repository and generating HTML and JSON reports:
Command
export SAST_SERVER=https://sast.whitesourcesoftware.com/ export SASTCLI_TOKEN=e1e516458cdd1033xxxxxxxxdbc18574be9f9c3ac806da7187b8d7f96 ./wssastcli --app WebGoat.NET --report --formats "html,json" --filename "demoreport"
Output
[...] Testing application files from /NodeGoat... JavaScript / Node.js analysis in progress… [...] Tested 87 project files across 1 detected programming language(s). Found 23 vulnerabilities. -------… Found vulnerability types: ------------------------------ Language: JavaScript / Node.js SEVERITY | VULNERABILITY TYPE | COUNT -----------+--------------------------------+-------- High | Code Injection | 6 Medium | Unvalidated/Open Redirect | 2 Low | Hardcoded Password/Credentials | 7 Low | Weak Pseudo-Random | 8 -----------+--------------------------------+-------- 23 --------- Web dashboard URL: Submitting vulnerability snippet files... Vulnerability snippet files have been submitted for processing. -------------- Support token: 6dbe520fad6c2c46647d72a0b9a3d5542f8779bf992044 ====================================== [ + ] HTML report exported to demoreport.html [ + ] JSON report exported to demoreport.json ````
Example wscli-config.json File
Below is an example wscli-config.json file. All of these JSON parameters can also be specified as environment variables.
{ "connection": { "token": "………………………………………………………………………", "url": " ", "organizationId": "……………………………………………………………", "timeoutMin": 10, "insecureSkipVerify": false }, "proxy": { "enabled": false, "url": "", "username": "", "password": "" }, "cachePath": "", "scans": { "engines": [], "directory": "", "application": "", "template": "", "submitFiles": true, "submitLogs": true, "snippetSize": 10, "exclusions": [], "incremental": false, "uploadBaseline": false, "baselineStorage": "", "threshold": { "high": 0, "medium": 0, "low": 0, "cwe": [] } }, "reports": { "generate": false, "formats": [], "filename": "" }, "noColor": false, "noProgress": false }
Engine IDs reference
Engine ID | Language |
---|---|
1 | Java |
2 | C# |
3 | PHP |
4 | Python |
5 | Ruby |
6 | ASP Classic/Visual Basic/VBScript |
7 | VB.Net |
8 | JavaScript / Node.js |
9 | PLSQL |
10 | Android Java |
11 | iOS Objective-C |
12 | C/C++ (Beta) |
13 | ColdFusion |
14 | Groovy |
15 | TypeScript |
16 | Cobol |
17 | ABAP |
18 | Go |
19 | Swift |
20 | Apex |
21 | Kotlin |
22 | Xamarin (C#) |
23 | Kotlin Mobile |
24 | R |
```