Nexus IQ CLI
Overview
While tools offering full integration for evaluations are provided (e.g. Nexus Repository Manager, Eclipse, and Hudson/Jenkins), any application can be evaluated against your policies simply by using the Nexus IQ Command Line Interface (CLI).
Before you get started, there are a few things you should make sure you have, including:
- A general familiarity with the CLI (you don’t need to be an expert, but basic knowledge helps).
- Installed and set up the IQ Server
- Set up an organization and application
- Created or imported a policy for your application, or the organization that contains your application.
Downloading the Nexus IQ CLI
To use the Nexus IQ CLI, download the jar file or binary from IQ Download and Compatibility and place the file in its own directory.
Be sure to remember where you placed the file you downloaded. As a recommendation, it’s best to have the Nexus IQ CLI in its own directory, and not shared with the IQ Server.
Nexus IQ CLI Docker Image
The Nexus IQ CLI is also available as a docker image at https://hub.docker.com/r/sonatype/nexus-iq-cli. The documentation there details how to use the image to perform an evaluation.
Currently, the pki option is not available via the docker image.
Usage
Locating Your Application ID
Before you start an evaluation, you need to have your Application ID. To get this…
- Log into your IQ Server with a user account with at least a developer role for the application you plan on evaluating.
- Click the Organization & Policies icon .
- Click on an organization in the menu on the left to display a list of applications, and then click on the application you want to find the Application ID for. You will see a screen similar to the following example:
Locate the text to the right of the application name. The application ID is the text in parenthesis.
The application ID will be truncated if it is too long. The full application ID can be copied to the clipboard from the Actions menu.
An alternative is to enable automatic application creation. If you do so, an application with the specified ID will automatically be created if it does not already exist in IQ Server.
Evaluating an Application
Now that you have the Nexus IQ CLI set up, you are ready to evaluate an application. The application can be an archive file, a directory containing such archives or a Docker image.
As a Java application, it can be started using the java command, and adding the necessary parameters. The syntax below represents the minimum set of options required to evaluate an application.
Note - The actual user account you will be evaluating with needs at least an "Application Evaluator" role for the IQ Application the evaluation will run against.
Evaluating a File or Directory
Include one or more scan targets at the end of the command.
java -jar [nexus-iq-cli jar] -i [application id] -s [server URL] -a [username:password] [scan targets]
Here's an example of that command using the 1.139.0-01 CLI .jar, the default server URL and credentials, for an application file called sample-application.zip and with an application ID of Test123.
java -jar ./nexus-iq-cli-1.139.0-01.jar -i Test123 -s http://localhost:8070 -a admin:admin123 ./sample-application.zip
Evaluating a Docker Image
Use the Docker CLI to save a Docker image:
docker save -o [target].tar [image name]
Then, evaluate the resulting tarred repository as you would an archive as described above.
Parameters
nexus-iq-cli jar
This is the path to the Nexus IQ CLI jar file e.g. ./nexus-iq-cli-<version>.jar
-a, --authentication
Using the switch -a, enter the user name:password (e.g. MyUserName:MyUserPassword).
Authentication will permit (or prevent) the ability to submit an application for evaluation, as well as retrieve the summary results and URL.
--pki-authentication
Delegate to the JVM for authentication.
-i, --application-id
Using the switch -i, enter the application id for your application (see instructions above). If automatic application creation is enabled and the application does not exist, it will be created.
-s, --server-url
Using the switch -s enter the location of your IQ Server (e.g. http://localhost:8070).
Target
This is the path to a specific application archive file, a directory containing such archives or the ID of a Docker image. For archives, a number of formats are supported, including jar, war, ear, tar, tar.gz, zip and many others.
Listed in the options below, you can specify the specific stage. However, if you do not include this option the system will default to the Build stage.
Additional Parameters
There are several additional options that can be used in the construction of the syntax for evaluating an application with the Nexus IQ CLI.
-w, --fail-on-policy-warnings
using the switch -w will cause a failure of the evaluation if any warnings are encountered. By default, this is set to false.
-e, --ignore-system-errors
Using the switch -e, allows you to ignore any system errors (e.g. IO, Network, server, etc.). This is most helpful when using the Nexus IQ CLI with continuous integration servers, as these errors can cause the unintentional failure of a build.
-p, --proxy
Using the switch -p, you can specify a proxy to use in connecting to the IQ Server. The format is <host[:port]>.
-U, --proxy-user
Using the switch -U, you can specify credentials for the proxy. The format is <username:password>.
-r, --result-file
Using the switch -r, you can specify the name and location of a JSON file that will store the results of the policy evaluation in a machine-readable format or information about an error if one occurs
-t, --stage
Using the switch -t, you can specify the stage you wish the report to be associated with. This is an optional parameter, and if it is not specified, the report will be associated with the Build stage by default.
-m, --metadata-file
Using the switch -m, you can specify a file containing JSON to be passed into the policy evaluation request. This gives Nexus IQ for SCM the information it needs to send GitHub Status checks to GitHub commits. The format is: {"commitHash": "<git commit hash>"}. Please see Nexus IQ for SCM for details.
At this time only the Build, Stage Release, and Release stages will display a report in the IQ Server Reports area. For a full list of stages, use the CLI help provided with the tool.
--module-exclude
NEW IN RELEASE 125
Using this option, you can specify module information files to be ignored via Apache Ant styled patterns (i.e. **/sonatype-clm/module.xml). For multiple specifications you can repeat the option.
-X, --debug
This switch enables debug logging to help troubleshooting.
The resulting debug log may contain sensitive information. Use this option with care.
-k, --keep-scan-file
NEW IN RELEASE 132
Starting on release 132 the temporary scan file is deleted at the end. If this switch is used, the file is not deleted, and it could be inspected after the evaluation ends.
Scan Targets
You can specify multiple scan targets ( directories or files) separated by spaces:
test/dir/*/*.jar test/*/*.ear
Scan targets on the command line use standard glob expansion as defined by the shell the CLI is running on.
In the case of npm application scanning the package.json manifest file will be included in the scan by default along with any lock files that match the scan targets. This is to enhance the results with component dependency data. See NPM Application Analysis documentation for more information.
Loading Parameters from a File
The parameters can be passed to the Nexus IQ CLI via a file. To do that, specify the file name prefixed by an "@" character, e.g. @some/path/myparamfile
.
- The file uses the JVM's default character encoding.
- Parameters specified on the command line can be mixed with parameters specified in a file.
- There can be any number of parameter files.
Inside a parameter file:
- Parameter names and their values must be on separate lines.
- Both short and long parameter names are supported.
- File paths within the parameter file are relative to the process' current directory, not the parameter file. Absolute file paths are supported as well.
- Multiple file paths can be specified, one per line.
The following example assumes all the referenced files are in the current working directory:
java -jar ./nexus-iq-cli-<version>.jar @cli-params.txt
and
-i Test123 -a username:password -s http://localhost:8070 -t build ./sample-application.zip
Or, if you just want to hide the credentials:
java -jar ./nexus-iq-cli-<version>.jar @cli-auth.txt -i Test123 -s http://localhost:8070 -t build ./sample-application.zip
and
-a username:password
Example Lifecycle Evaluation
In an example scenario, let’s say you have downloaded the latest CLI jar as well as the application you want to examine to a specific directory e.g. ~/nexus-iq-server-test
. The application’s filename is sample-application.zip
.
To evaluate this application you have to identify the application ID and supply it with the -i
switch, supply the URL of your IQ Server with -s
, and add -a
to authentiate with your username and password. As an option, and what is demonstrated below, you can also specify a particular stage with the -t
switch.
The following example shows the command line for an Application ID Test123
and a URL of http://localhost:8070
. Replace <version> in the jar file path with your version of the CLI.
java -jar ./nexus-iq-cli-<version>.jar -i Test123 -s http://localhost:8070 -a username:password -t release sample-application.zip
To access help content for the Nexus IQ CLI, run it without supplying parameters:
java -jar ./nexus-iq-cli-<version>.jar
Go ahead and try an evaluation yourself. The Nexus IQ CLI will accept a number of file types, including jar, war, and zip files. If your evaluation is successful, the log output of the command execution will provide a summary as well as a link to the produced results similar to:
[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
Example Lifecycle Evaluation (using --result-file option)
In this example scenario, we do the same as in the previous one, but also specify the --result-file parameter with the name of the file. The results of the policy evaluation will be written not only into the console, but also in a file now.
java -jar ./nexus-iq-cli-<version>.jar -i Test123 -s http://localhost:8070 -a username:password -t release -r cli.log sample-application.zip
If your evaluation is successful, the log output of the command execution will provide a summary as well as a link to the produced results similar to:
[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
The output to the console is the same as in the previous example, but now we also have a cli.log file created with evaluation results which looks like this:
{ "applicationId" : "...", "scanId" : "...", "reportHtmlUrl" : "http://...", "reportPdfUrl" : "http://.../pdf", "reportDataUrl" : "http://.../raw", "policyAction" : "None", "policyEvaluationResult" : { "alerts" : [...detailed list of components which caused the violation...], "affectedComponentCount" : 15, "criticalComponentCount" : 4, "severeComponentCount" : 65, "moderateComponentCount" : 36, "criticalPolicyViolationCount" : 4, "severePolicyViolationCount" : 85, "moderatePolicyViolationCount" : 46, "grandfatheredPolicyViolationCount" : 0 } }
applicationId - is the application in IQ Server against which you run policy evaluation
scanId - can be used in some rest api (see https://help.sonatype.com/iqserver/automating/rest-apis/promote-scan-rest-api---v2)
reportHtmlUrl, reportPdfUrl, reportDataUrl - report with policy evaluation results in different formats
policyAction - policy evaluation outcome (can be None, Warn, Fail)
policyEvaluationResult - contains summary of the evaluation:
alerts - contains information about components which caused a policy violation
affectedComponentCount - number of components which caused a policy violation
criticalComponentCount - number of critical components which caused a policy violation
severeComponentCount - number of severe components which caused a policy violation
moderateComponentCount - number of moderate components which caused a policy violation
criticalPolicyViolationCount - number of critical policies which were violated
severePolicyViolationCount - number of severe policies which were violated
moderatePolicyViolationCount - number of moderate policies which were violated
grandfatheredPolicyViolationCount - number of policies which were violated, but moved to grandfathered
If an error happened during the policy evaluation (such as a user has provided wrong application ID or IQ Server is just down, etc.),
you get the following format of the result file:
{ "errorMessage" : "<some error message>", "isSystemError" : <true or false> }
errorMessage - a test of the error message happened during the CLI run
isSystemError - an indicator of whether it is a system or configuration error
Let's see two examples:
1. User has provided wrong application ID (this is a configuration error, i.e. "isSystemError" is false)
{ "errorMessage" : "The application ID testapp02 is invalid.", "isSystemError" : false }
2. IQ Server is down (this is a system error, i.e. "isSystemError" is true)
{ "errorMessage" : "The IQ Server http://localhost:8070 could not be contacted: Unknown host: localhost: nodename nor servname provided, or not known", "isSystemError" : true }
Using the Nexus IQ CLI with a CI Server
We won’t be covering a specific CI here, but in general, all you need to identify (in your CI), is the location for adding a build step that includes processing a simple shell script during the building of your application.
Once you are there, make sure your script calls the Nexus IQ CLI using the following syntax:
java -jar [ScannerJar] -i [AppID] -e [IgnoreSystemErrors] -w [FailOnPolicyWarning] -s [ServerURL] -a [username:password] [Target]
Each of the areas in the syntax above are described in the Evaluating an Application section.
Given a typical setup, your syntax, including all available options, will likely look similar to the following:
java -jar /scanner/nexus-iq-cli-<version>.jar -i tester123 -s http://localhost:8070 -a username:password ./target/sample-app.war
Now, when your application is built, the build step you have added will call the Nexus IQ CLI, evaluate your application, and upload results of the evaluation to the IQ Server. By default this will be placed below the build column in the Reports and Application area on the IQ Server, for your application.
We advise you to use a separate application identifier for each of your unique applications. Using the same application identifier will result in report results being overwritten each time an application is built. While this is always the case, matching the latest evaluation to the right application can prove difficult.
Nexus IQ CLI Binaries
About
The binary CLI version is a drop-in replacement without any JVM requirement. All parameters are the same as defined above in 'Parameters' with the addition of some to handle binary-specific SSL customizations (see below).
Downloads
The native binary versions of the Nexus IQ CLI are available for direct download on the main IQ Download and Compatibility page next to the JAR version.
Linux
The Linux CLI can be installed on distrubutions supporting deb
or rpm
packages:
Mac/Homebrew
The Mac CLI can be installed via the Homebrew package manager like so:
Usage
Linux & Mac OS:
./nexus-iq-cli
Windows:
nexus-iq-cli.exe
SSL Parameters
The JAR version of the CLI uses the standard approach to SSL that is found in all Java applications. Namely the '-Djavax.net.ssl.trustStore
' and '-Djavax.net.ssl
.keyStore
' family of options. For that native binaries we must explicitly pass in the equivalent values via additional parameters:
--ssl-key-store-password
Password for custom SSL key store (equivalent to -Djavax.net.ssl.keyStorePassword
JVM property)
--ssl-key-store-path
Path to custom SSL key store (equivalent to -Djavax.net.ssl.keyStore
JVM property)
--ssl-key-store-type
Type of custom SSL key store (equivalent to -Djavax.net.ssl.keyStoreType
JVM property)
--ssl-trust-store-password
Password for custom SSL trust store (equivalent to -Djavax.net.ssl.trustStorePassword
JVM property)
--ssl-trust-store-path
Path to custom SSL trust store (equivalent to -Djavax.net.ssl.trustStore
JVM property)
--ssl-trust-store-type
Type of custom SSL trust store (equivalent to -Djavax.net.ssl.trustStore
Type JVM property)
Release Notes
Version 1.133.0-01 (March 2022)
- Dependency Information for CycloneDX SBOM scans
Version 1.132.0-02 (January 2022)
- Bug fix for false positives in docker image scans
Version 1.130.0-01 (December 2021)
- Update logback library version to remediate a low/moderate vulnerability (Nexus IQ Server does not use log4j)
- Cran and Cargo matching improvements
- Conda matching improvements
Version 1.125.0-01 (October 2021)
- Conan Matching Improvements
- Conan data and matching have been improved for both Lifecycle and Firewall.
- Dependency Information Improvements for NPM
- NPM Dependency Information detection has been improved to display more accurate results.
- Added support for analyzing Java 17 bytecode.
Version 1.123.0-01 (September 2021)
- Fixed an issue with some NPM scans that was causing IQ Server 122 evaluations to fail when reading dependency information.
Version 1.122.0-01 (September 2021)
- Dependency Information for NPM
- NPM project scans with manifests allow displaying dependency information for NPM components (Direct and Transitive). Please refer to NPM Application Analysis and Application Composition Report for more information.
Version 1.120.0-01 (July 2021)
- Added support for container scanning via Nexus Container
Version 1.119.0-03 (July 2021)
- SBOM Improvements and Bug Fixes:
- CycloneDX SBOM scans have been improved to display better results in the report and some bugs have been fixed as well
Version 1.118.0-01 (June 2021)
- Swift Application Analysis:
- IQ Server can now be used to evaluate policies against components from the dependency file of a Swift application.
Version 1.117.0-01 (June 2021)
- Support for CycloneDX 1.3:
- CycloneDX Application Analysis has been extended to support the schema version CycloneDX 1.3 for XML format.
Version 1.116.0-01 (June 2021)
- Improvements to Python Application Analysis:
- IQ Server now supports evaluating policies against Python components defined in poetry.lock files.
Version 1.114.0-01 (May 2021)
- Support for CycloneDX 1.2:
- CycloneDX Application Analysis have been extended to support the schema version CycloneDX 1.2 for XML format
Version 1.107.0-01 (March 2021)
- Java Manifest Application Analysis:
- IQ Server now supports evaluating policies against Java components in pom.xml and build.gradle files
Version 1.106.0-01 (March 2021)
- Improvements to manifest analysis:
- Updated CLI scanner to exclude development dependencies when scanning package-lock.json files.
- Updated CLI scanner to parse package-lock.json files stored inside an archive.
- Fixed parsing errors when scanning yarn.lock and *.csproj files.
Version 1.105.0-01 (Feb 2021)
- Fixed initialization error in NuGet manifest scanning
Version 1.104.0-02 (Jan 2021)
- Application analysis of components for:
- NPM, as defined in yarn.lock, pnpm-lock.yaml, package-lock.json, and npm-shrinkwrap.json files.
- NuGet, as defined in * .csproj and packages.config files.
Version 1.103.0-01 (Dec 2020)
- Added support for analyzing Java 14 and 15 bytecode.
Version 1.101.0-01 (Nov 2020)
- Nexus IQ CLI no longer supports Lifecycle XC. IQ Server now has native support for all languages that were supported in Lifecycle XC.
Version 1.98.0-01 (Sep 2020)
- Application analysis of components for:
- Go components defined in a Gopkg.lock
Version 1.97.0-01 (Aug 2020)
- Application analysis of components for:
- C/C++ components defined in a conaninfo.txt file.
- Go components defined in a go.list file
Version 1.94.0-01 (Jun 2020)
- Now releasing in sync with Nexus IQ Server releases (which may or may not include updates relevant to this docker image's release)
- Application analysis of components for:
- C/C++ conanfile.py Files
- Yum
- Alpine
- Debian
- Drupal
- R (CRAN)
- Rust (Cargo)
Version 1.88.0-02 (Mar 2020)
- Application analysis of components for:
- Swift/Objective-C CocoaPods
- Conda
Version 1.87.0-02 (Mar 2020)
- Identify components based on SHA-1 value (content hash)
- Application analysis of components for:
- C/C++ Conan
- PHP Composer
- RubyGems
- CycloneDX application analysis extended to support submitting component vulnerabilities