How to use the ZeroNorth™ Command-Line Interface (CLI) and download

nischit · January 16, 2022, 4:30am

Prerequisites

The steps described in this article assume that you have:

ZeroNorth License and Credentials
Access to ZeroNorth and the Scanning tools
Platform supported by our CLI executable

Usage

Windows: zn_cli.exe [options] [options] ...
Ubuntu: zn_cli [options] [options] ...

To see a complete list of the options, run zn_cli.exe --help :

Tips

On some operating systems, it will be necessary to set the following two environment variables:

export LC_ALL=en_US.utf-8
export LANG=en_US.utf-8

…or…

export LC_ALL=C.UTF-8
export LANG=C.UTF-8

The CLI will need to use a temporary folder for zipping up the contents of the folder pointed to by the --code_path parameter. Specific to Unix/Linux, the default location for this is /tmp and is irrespective of what value you set for the --results_path parameter. To override the location of the temporary folder, set the environmental variable TMP to the desired location:

export TMP=/home/myhome/tmp

In DOS (CMD):

set TMP="C:\Temp"

In PowerShell:

$env:TMP="C:\Temp"

Examples

Below are couple of examples:

1) Scanning the WebGoat project using WhiteSource:

zn_cli.exe --api_key <your ZeroNorth API token> --code_path c:\GitHub\WebGoat\ --results_path c:\Temp\ --policy_id <ZeroNorth policy ID>

TIPS:

The command syntax for the Linux variants of CLI is identical, except for the use of the forward slashes ("/") in the paths.
The Windows command syntax can also accept forward slashes in the paths, assuming you are running the executable from the same drive (e.g. “C:”) as where the scan target is.
In Windows, you should always use the trailing [back] slash for the code_path parameter value. For example: c:\myworkdir\myproject\ , not c:\myworkdir\myproject .
We always recommend the use of the api_key option instead of username and password. See the article Obtaining your ZeroNorth API Token for information on obtaining your API token.

2) Scanning the WebGoat project using SonarQube

SonarQube scans require additional parameters when the target project is a Java project:

zn_cli.exe --api_key <your ZeroNorth api token> --code_path c:\GitHub\WebGoat\ --results_path c:\Temp\ --scenario sonarqube-agent --sonar_java_library_dir "webgoat-container/target/classes/static/js/libs,webgoat-container/src/main/resources/static/js/libs" --sonar_java_binary_dir "webwolf,webgoat-container,webgoat-lessons,webgoat-server" --policy_name WebGoat-SQ-Scan

where:

sonar_java_library_dir is a comma-separated list of folders within the project that contain all of the project’s library files (e.g. .jar files). These paths must be specified using forward slashes ("/’) relative to the project root.
sonar_java_binary_dir is a comma-separated list of folders within the project that contain all of the project’s compiled binaries (e.g. .class files). These paths must be specified using forward slashes ("/’) relative to the project root
policy_name when specified, will be used in naming the auto-created policy. Alternatively, use policy_id to specify an existing policy. See the article Manage Security Policies for instructions on obtaining a policy_id.

3) Using the CLI to dynamically auto-create the Target and the Policy for an upload/scan use case

In this use case, you let the CLI to automatically create the necessary Target and the appropriate Policy for you. This is useful when you are integrating the CLI into many similar CI/CD pipelines and you want to eliminate the need to manually create the Target and the Policy in advance.

We use the WebGoat / WhiteSource example from above, but with modifications:

zn_cli.exe --api_key ..... --code_path c:\GitHub\WebGoat\ --results_path c:\Temp\ --scenario MyWSScenarioName --target_name WebGoatBuild --policy_name WebGoatBuild_WS

HINTS:

The named Scenario must already exist in your ZeroNorth account.
The named Target and Policy will be dynamically created using the following rules:
1. IF no match THEN create the object using the specified name
2. IF more than one match THEN die
3. IF exactly one match THEN (re)use that object
By default, the CLI will perform a build artifact upload/scan.

Viewing Results

Use ZeroNorth’s web UI to view your scan results.
You can also see the raw output in the scan.out file within the folder specified via the results_path parameter.

DOWNLOAD - ZeroNorth CLI Executable

Use one of the download links at the bottom of this page to download the desired edition of the ZeroNorth CLI executable.

The CLI executable is currently available for the following platforms:

Ubuntu 64-bit
CentOS/RH 64-bit
Windows 64-bit

Below are the hash keys for the files:

md5sum :

49688f3923e732a28cc844a371839b12 *zn_cli_centos7_20211103
b3d1c40f320f28c79ca65ef2ed04b493 *zn_cli_ubuntu1604_20211103
548ff9ffd4054dd31f408465590f2476 *zn_cli_ubuntu1804_20211103
510387b520f2a40244b02b137f1c4c01 *zn_cli_ubuntu2004_20211103
45aa1b40525846a15f1e5ad0877e314b *zn_cli_win64_20211103.exe

sha512sum :

1db26e73163f7e32de4843df7b9e04e4abe55bd6f814cb3d8aa6cd86e748b674190707c7367571ec98618229c08954b9e58215ecb9fc6f080d096482762fdbc8 *zn_cli_centos7_20211103
b6b3f912e6eda1b4ce6dc0be61d90da6d513592a4b54f362b06e72c24d3db00aaa9245653daa99e5b5705bb45682150e5cf1cf4964b10f30d726852876189e1e *zn_cli_ubuntu1604_20211103
3c400c17650b8cec4596beb7b62e3e09d711a66f1cd2150484747b17ce805aac308d8507804487ca2f33a46b59dcc41d474b8114d92b77be598c96f9c1f9fb31 *zn_cli_ubuntu1804_20211103
d9b05ee7b581abbc2aad212578f56b93167160cfb52b2bb782bf4e4d6a239b696e0957e789b52c27cdbcc0fe2350025b70936976260ae4699dc8b8ce8a58cd6a *zn_cli_ubuntu2004_20211103
f84ba7a4b0ccd93b592567a5b7ab9539744934ab922a44a15436d1eee982647f243b98e55bdff0f8464dd2ceb1ce519702be8b93c138e63045fc9a406084f6ba *zn_cli_win64_20211103.exe