Nexus IQ CLI

Overview

While tools offering full integration for evaluations are provided (e.g. Nexus Repository, Eclipse, and Hudson/Jenkins,) any application can be evaluated against your policies by using the Sonatype Lifecycle Command Line Interface (CLI).

Pre-requisites:

  • A general familiarity with the CLI 
  • Installed and setup instance of IQ Server. Ensure that your IQ Server version is the same or higher than the Nexus IQ CLI version.
  • Set up an organization (Org)
  • Created or imported a policy for your Org

Downloading the Nexus IQ CLI

Download the jar file or binary from IQ Download and Compatibility and save in a separate directory space (not shared with IQ Server.)

Nexus IQ CLI Docker Image

The Nexus IQ CLI and related documentation is also available as a docker image at https://hub.docker.com/r/sonatype/nexus-iq-cli. 

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

Using the Nexus IQ CLI

Select the application to evaluate from onboarded IQ server applications

  1. application-id is an input parameter used to specify the application to be evaluated using Nexus CLI.
  2. Login to your IQ Server with a user account with at least a developer role for the application you plan on evaluating.
  3. Click the Orgs & Policies icon .
  4. 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 application-id

  5. The text in parentheses (indicated by the arrow above) is the application-id. 

  6. If the application-id is too long, it will appear truncated. To obtain the complete application-id click on the Actions dropdown on the top right. Select App ID to Clipboard.

Automatic application creation for new applications

If automatic application creation is enabled, IQ Server will create a new application with the specified ID. This can be used for first time evaluation of new applications that have not been onboarded to IQ Server previously.

Locating the organization ID

The automatic application creation feature creates a new application under the organization that is configured.

NEW IN RELEASE 143To create an application under a different organization, you can specify the organization-id as an input parameter. 

To locate the organization-id:

  1. Login to your IQ Server with a user account that can access the organization hierarchy.
  2. Navigate to the organization under which you want the new application to be created.
  3. Click on the Actions menu and click on the Org ID to Clipboard menu entry. The organization-id is copied to the clipboard. 

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 or a directory containing archives.

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 user account you will be evaluating the application should at least have an "Application Evaluator" role for that application.

Using Call Flow Analysis (Experimental) NEW IN RELEASE 152

Nexus IQ CLI can scan your application code with call flow analysis. The analysis detects method signatures in the application code that contain components with potentially exploitable security vulnerabilities.  Such components are labeled as “Security-Reachable” and can be viewed on the component details page, accessible from the resulting application report.

How it works:

By including an additional parameter in the command to evaluate an application, call flow analysis is triggered to run on java (or any JVM language) binaries located in the scan target. The scan process analyzes all application binaries and the dependencies binaries in the scan target folder.

If the scan detects a vulnerable component and if the application code calls the specific method in the component that could potentially be exploitable, the component is labeled as security-reachable.

If the scan detects a vulnerable component, but the application code does not execute any calls to the specific vulnerable method, the component will not be labeled as security-reachable.

Call flow analysis runs normally even if the scan target contains components that have been matched as proprietary Components. 

Application scans with call flow analysis can detect vulnerable methods even if they are not called directly by the application code. Example: Consider methods "Library.a()" and "Library.b()", where  "Library.a()" is a vulnerable method and is called by "Library.b()" as part of its built-in functionality. The application code calls "Library.b()". Call flow analysis will detect this call as a call to a vulnerable method  "Library.a()" and label it as "Security-Reachable".

How to use:

  1. On the first execution of call flow, the “Security-Reachable” label is automatically created and attached to 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 and provide immediate visibility.

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]

Example of 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

NEW IN RELEASE 136You can use user token instead of username and password. Refer to User Tokens for details on creating user tokens in IQ Server.

java -jar [nexus-iq-cli jar] -i [application id] -s [server URL] -a [usercode:passcode] [scan targets]

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 username: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.

-O, --organization-id NEW IN RELEASE 143

Using the optional switch -O, enter the organization ID for your organization. If automatic application creation is enabled and the application does not exist, it will be created under the organization having the provided organization ID.

If both the application and the organization IDs are provided, and the application already exists under a different organization, the evaluation process stops with an error message. This mechanism is in place to prevent accidental configurations, which could unintentionally alter the evaluation history of existing applications. 

Consider removing the organization ID from the scan if you ever plan to move the application to another organization.

-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.

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.

-E, --ignore-scanning-errors

Using the switch -E, allows you to ignore any scanning errors (e.g. invalid files, inaccesible files, etc.). This is most helpful when your code base contains invalid files for testing purposes, as scanning those files 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]>. If not specified, the CLI uses the default HTTP proxy for the JVM used to launch our CLI.

If the system property java.net.useSystemProxies is set to true, then the CLI will try to use these settings. That propertly can be changed on the command line invoking the CLI. It can also be changed in the JRE installation file lib/net.properties, to avoid having to change it repeatedly.

-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 troubleshoot.

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.

  -c, --call-flow-analysis NEW IN RELEASE 152

Using this switch, a call flow analysis will be performed in Java (or any JVM language) binaries found in the scan targets to find method signatures that trigger a security vulnerability.

-cn, --call-flow-analysis-namespaces NEW IN RELEASE 152

Using this switch, a call flow analysis will be performed in Java (or any JVM language) binaries found in the scan targets to find method signatures that trigger a security vulnerability, limiting the analysis to the code found under the given namespaces or packages for a faster and more precise result. Multiple packages can be set like this: -cn com.package1 -cn org.package2

The -D switch is a general Java parameter for setting system parameters. For example, to pass includeSha256, you first need to define that with -D includeSha256=true. This switch may necessary for your usage of the Nexus IQ CLI.

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. 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.
  • File globbing is not supported inside parameter files.
  • 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 authenticate 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

Evaluation results

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)

To retrieve the evaluation results in a file, specify the --result-file parameter with the name of the file. 

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
		"legacyViolationCount" : 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 a summary of the evaluation:
alerts  - contains information about components that caused a policy violation
affectedComponentCount  - number of components that 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 (depracated)  - number of policies that were violated, but moved to grandfathered
legacyPolicyViolationCount  - number of legacy policy violations

Embrace Inclusion

NEW IN RELEASE 168 As part of our inclusive language initiatives stemming from one of Sonatype's core values "Embrace Inclusion", the response field grandfatheredPolicyViolationCount has been deprecated. We recommend using legacyViolationCount.

Refer to Managing Legacy Violations for more information.

Error messages

The resulting file contains a log of errors that occurred during the policy evaluation in the following format:

{
    "errorMessage" : "<some error message>",
    "isSystemError" : <true or false>
}

errorMessage  - a test of the error message that happened during the CLI run
isSystemError  - an indicator of whether it is a system or configuration error

Error examples:

1. User has provided the 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

In your continuous integration (CI) server, identify the location for adding a build step that includes processing a simple shell script during the build stage.

Execute a script call to the Nexus IQ CLI using the following syntax, from that location:

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

When your application is built, the build step you have added will call the Nexus IQ CLI, evaluate your application, and upload the 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 recommend using a separate application identifier for each of your applications. Using the same application identifier will result in report results being overwritten each time an application is built. 

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 distributions supporting deb  or rpm  packages:

Debian/Ubuntu

  1. (One-time setup) Download the public GPG signing key and add the key to your apt sources keyring:

    wget -qO- https://repo.sonatype.com/repository/sonatype-hosted/pki/deb-gpg/GPG-KEY-sonatype-apt-hosted.asc | \
   gpg --dearmor | \
   sudo tee /usr/share/keyrings/sonatype-apt-hosted.gpg >/dev/null

  2. (One-time setup) Add the repository to your sources.

    • Manually create  /etc/apt/sources.list.d/sonatype-hosted.list

      deb [signed-by=/usr/share/keyrings/sonatype-apt-hosted.gpg arch=amd64] https://repo.sonatype.com/repository/sonatype-apt-hosted/ stable main

    • Or automatically:

      sudo wget -P /etc/apt/sources.list.d/ https://repo.sonatype.com/repository/sonatype-hosted/deb/sonatype-hosted.list

  3. Install the application via apt-get.

    sudo apt-get update && sudo apt-get install nexus-iq-cli

Red Hat/CentOS

  1. (One-time setup) Add the repository to your sources.

    • Manually create /etc/yum.repos.d/sonatype-hosted.repo

      [sonatype-hosted]
name=Sonatype Hosted
baseurl=https://repo.sonatype.com/repository/sonatype-yum-hosted/
enabled=1
gpgcheck=1
gpgkey=https://repo.sonatype.com/repository/sonatype-hosted/pki/rpm-gpg/RPM-GPG-KEY-Sonatype-yum.asc
priority=1

    • Or automatically:

      sudo wget -P /etc/yum.repos.d/ https://repo.sonatype.com/repository/sonatype-hosted/rpm/sonatype-hosted.repo

  2. Install the application via yum (or dnf). The first time you install the package you will be prompted to install the GPG signing key.

    sudo​ yum install nexus-iq-cli

Mac/Homebrew

The Mac CLI can be installed via the Homebrew package manager like so:

brew tap sonatype/nexus-iq-cli
brew install --cask nexus-iq-cli

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 JVM property)