Skip to main content

Sonatype CLI

The Sonatype Lifecycle Command Line Interface (CLI) is the multi-tool for performing a Lifecycle Analysis. Evaluations of your applications are either run manually or automatically using the CLI in many environments.

Sonatype Lifecycle CLI

Java 17 is supported as of release 175. Use Java 11 from releases 89 to 174, and Java 8 for earlier releases.

Getting started with the Sonatype CLI

You will need to perform a few tasks to run a Lifecycle analysis using the CLI.

  1. Setup an environment to analyze

  2. Set credentials to use with the CLI

  3. Prepare an application in Lifecycle

Setup an environment to analyze

The CLI jar is a Java application that requires a JVM in the environment you want to perform the analysis.

Download latest version for Java:

nexus-iq-cli-latest.jar (ASCSHA1)

Requires the Java Virtual Machine.

Download latest version for Windows:

Requires the Visual C++ Runtime. This is included in the zip, or it can be installed and maintained by Windows Update.

Download latest version for Linux:

The Linux CLI can be installed on distributions supporting Deb or RPM packages. Tested on Centos 7.1+, RHEL 7.3+, Debian 8+, Ubuntu 14.04+

Download latest version for Mac:

This Mac pkg installer places files in the /usr/local/bin directory and has been tested on both M1 and Intel chipsets.

How to install the latest version using Homebrew

Begin by entering the command brew tap sonatype/nexus-iq-cli (this is a one-time step).

Once completed, proceed with brew install --cask nexus-iq-cli

The Sonatype CLI and related documentation is also available as a docker image on DockerHub

Native binaries which do not require a JVM are available for Linux, Mac, and Windows. See the Sonatype CLI Binaries for details.

  • We recommend using the same version of the CLI as your Lifecycle server version. Newer versions of the CLI are often not compatible with older versions of the server.

  • The PKI option is not supported by the docker image.

CLI Authentication

For automated systems, we recommend passing a user token instead of a username and password. You may consider configuring a dedicated service account with the minimum access privileges.

The authentication credentials require the Evaluate applications permissions for the specific application or organization to perform an analysis. We recommend using the default Application Evaluator role for simplicity.

Parameters such as user credentials should be obfuscated using a parameter file or environment variables.

See Passing CLI parameters from a file for details.

Evaluating an Application

The CLI will need an application configured in the Lifecycle server to determine which policy to use and to associate the finished scan report. Applications may be added beforehand or during evaluation using the Using Automatic application creation with the CLI feature.

Applications may be analyzed as a built archive file or a directory (build workspace) containing the application code.

As a Java application, the CLI is started using a java command with the required parameters. The syntax below represents the minimum set of options required to evaluate an application.

Example Lifecycle CLI Evaluation

The CLI requires the following parameters to run a scan: the applicationId, the Lifecycle URL, and credentials with permissions to analyze this application.

java -jar [sonatype-cli] -a [username:password] -i [--application-id] -s [--server-url] [scan-target]

Example command

java -jar nexus-iq-cli*.jar \
  -a username:password \
  -i sandbox-application \
  -s http://localhost:8070 \
  ./sample-application.zip

Access the CLI help by running it without parameters

java -jar ./nexus-iq-cli*.jar

Reachability Analysis with Sonatype CLI

You can now configure Sonatype CLI to perform Reachability Analysis, which can detect method signatures in your application code that contain components with potentially exploitable security vulnerabilities. These vulnerable components are labeled as Security-Reachable and can be viewed on the component details page in the resulting application report.

How Reachability Analysis Works in Sonatype CLI

Reachability Analysis leverages the Callflow feature in Sonatype CLI.

By including an additional parameter in the CLI command you can enable the Callflow feature. The scan process will then analyze all application and dependency Java (or any JVM language) binaries located in the scan target.

This allows you to detect reachable vulnerabilities, even in proprietary components within your application.

Using Reachability Analysis in Sonatype CLI
  1. On first execution, the Security-Reachable label is automatically created as a new component label and attached to the relevant components.

  2. We recommend creating a policy that includes a constraint condition with the label Security-Reachable and determining the threat level based on the priority of remediation needs. This allows subsequent calls to trigger policy violations, providing immediate visibility.

CLI parameters

sonatype-cli

The path to the Sonatype CLI jar file or native binary.

-a, --authentication

Provide credentials in the following format: username:password

--pki-authentication

Delegate authentication to the JVM environment.

-i, --application-id

The PublicId for the application. When Automatic Applications is enabled and the PublicId has not yet been used, a new application will be created.

-O, --organization-id

The ID for the organization to which the application belongs. When automatic application creation is enabled and the application does not exist, it will be created under the organization having the provided organization ID.

See Using Automatic application creation with the CLI

-s, --server-url

The location of your Lifecycle server (e.g. http://localhost:8070).

Scan-Target

Path to specific files, directory, or docker image. Include one or more scan targets at the end of the command. See supported file formats in Analysis.

Reachability Analysis parameters

-c, --call-flow-analysis

Perform a call flow analysis in Java or JVM language binaries to determine the method signatures that trigger a security vulnerability. See Reachability Analysis with Sonatype CLI

-cn, --call-flow-analysis-namespaces

Limit the call flow analysis to a specific namespace for faster, more precise results. Multiple namespaces are set by repeating the parameter.

-cn com.package1 -cn org.package2

Additional parameters

Additional options to use in evaluating applications with the Sonatype CLI.

-t, --stage

Specify the development lifecycle stage for the analysis. Defaults to the build stage

-r, --result-file

Send the output to a specific file path as a JSON data object.

See Example Scan Result File

-m, --metadata-file

Specify the file path providing a JSON object containing the commit hash for the SCM integrations.

{"commitHash": "<git-commit-hash>"}
--module-exclude

Specify module files to ignore via Apache Ant-styled patterns. Repeat the option for multiple specifications.

**/sonatype-clm/module.xml
-w, --fail-on-policy-warnings

Causes a failure of the evaluation if any warnings are encountered.

-e, --ignore-system-errors

Ignore system errors (e.g. IO, Network, server, etc.) when running on continuous integration servers to avoid unintentional build failures.

-E, --ignore-scanning-errors

Ignore scanning errors (e.g. invalid files, inaccessible files, etc) when the code base contains invalid files for testing purposes. Scanning these files may cause unintentional build failures.

-X, --debug

Enables debug logging for troubleshooting. Use with caution as this log may expose sensitive information.

-h, --help

Output help context for CLI.

-v, --version

Output version of the CLI

-k, --keep-scan-file

Retain the temporary scan file normally deleted at the end of the scan.

-o

Set the directory to write scan output files.

Proxy parameters

-p, --proxy

Specify a proxy to use when connecting to the Lifecycle server. This property is set using the format <host[:port]>, otherwise, the CLI uses the default HTTP proxy for the JVM.

-U, --proxy-user

Specify proxy credentials in the following format: <username:password>

Note

The CLI will use the proxy configuration when the system property java.net.useSystemProxies is set to true. This property can be changed on the command line or in the JRE installation file lib/net.properties

Java parameters for the CLI

The -D switch is a Java parameter for setting system parameters. There are a few parameters that require this content when passed to the CLI.

includeSha256

Include the Sha256 in the scan file

-D includeSha256=true
excludeMavenDependencyManagement

Enable this parameter to limit analysis to the project's dependencies section of a pom file while excluding the components under the dependencyManagement section.

When the component's version is specified in the dependencyManagement section rather than the project's dependencies section, the version will continue to be picked up from the dependencyManagement section even when this parameter is set.

-D excludeMavenDependencyManagement=true

Scan Targets

You may specify multiple scan targets ( directories or files) separated by spaces:

test/dir/*/*.jar test/*/*.ear

Scan targets use standard glob expansion as defined by the shell the CLI is running on.

Evaluation results

When the Sonatype CLI evaluation is successful, the output provides a summary and a link to the resulting scan report. Use this link to navigate directly to the report.

[INFO] Policy Action: Warning
[INFO] Summary of policy violations: 4 critical, 85 severe, 46 moderate
[INFO] The detailed report can be viewed online
at http://localhost:8070/ui/links/application/my-app/report/95c4c14e