Sonatype IQ CLI
The Sonatype IQ 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.
Note
For detailed information on feature availability in each CLI version, please review the IQ CLI Release Notes. This will help you determine the precise CLI version required for your desired functionality.
Getting started with the Sonatype IQ CLI
You will need to perform a few tasks to run a Lifecycle analysis using the CLI.
Set up an environment to analyze.
Set credentials to use with the CLI.
Prepare an application in Lifecycle.
Set up an environment to analyze
IQ CLI for Java
Download latest version for Java:
nexus-iq-cli-latest.jar (ASC, SHA1)
The CLI JAR is a Java application that requires a Java Virtual Machine (JVM) in the environment you want to perform the analysis.
IQ CLI for Docker
The Sonatype IQ CLI and related documentation is also available as a Docker image on DockerHub. The PKI option is not supported by the Docker image.
Supported Docker image platforms
The sonatype/nexus-iq-cli Docker image is published as a multi-platform Linux image. Current Sonatype-published latest, latest-alpine, current versioned, and current versioned -alpine tags support the following platforms:
Platform | Description |
|---|---|
| Linux on x86-64 / Intel / AMD 64-bit systems |
| Linux on ARM64 / AArch64 systems |
These are Linux container images. Windows container images are not published for this image.
Platform support refers to the container image runtime platform, not to every possible host OS, Kubernetes distribution, or cloud instance type.
Use current Docker and container runtime versions that support multi-platform images.
Third-party or community images are outside the scope of Sonatype-published Docker image support.
This platform support applies to the Docker image that runs the Sonatype IQ CLI. It does not change the CLI feature matrix or the existing Docker image limitation that PKI authentication is not supported by the Docker image.
Docker automatically selects the image variant that matches the host platform when pulling a multi-platform tag. To request a specific platform, use the Docker --platform option.
docker pull sonatype/nexus-iq-cli:latest docker pull --platform linux/arm64 sonatype/nexus-iq-cli:latest docker pull --platform linux/amd64 sonatype/nexus-iq-cli:latest
For pinned versions, use the same pattern:
docker pull --platform linux/arm64 sonatype/nexus-iq-cli:<version>
This platform support applies to current Sonatype-published tags. Some older image tags may support fewer platforms. Before pinning an older tag, check the Docker Hub tag list or inspect the image manifest:
docker buildx imagetools inspect sonatype/nexus-iq-cli:<tag>
IQ CLI With Bundled JDK
Available for Linux, Mac, and Windows. See the Sonatype IQ CLI With Bundled JDK for details.
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
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.
If present, Sonatype CLM for Maven-generated module.xml files are automatically evaluated only when they are located in the default directories (i.e., directly under either the sonatype-clm or nexus-iq directory). To ensure a successful scan, the Maven plugin’s generated module.xml files must remain in their default locations.
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.
-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
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.
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
Reachability Analysis parameters
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.
Include the Sha256 in the scan file
-D includeSha256=true
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.
Reachability Analysis
See Reachability Analysis with Sonatype CLI for how to enable Reachability in Java/JVM builds, covering required permissions, parameters, and the default entry point strategy with tips for narrowing scope via namespaces.
Evaluation results
When the Sonatype CLI evaluation succeeds, the output includes a summary and a link to the scan report. If the target IQ server supports priorities URLs (with both developmentDashboardEnabled and prioritizedFindingsReportEnabled set), a link to the priorities URL is also provided.
[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 [INFO] The application priorities can be viewed online at http://localhost:8070/ui/links/developer/priorities/my-app/95c4c14e/cli
Centralized CI configuration
To centrally manage supported CI evaluation settings for Sonatype IQ CLI through the Lifecycle organization and application hierarchy, see the CI Configuration REST API.