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 from IQ Download and Compatibility and place the file in its own directory.

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.  

Locating Your Application ID

Before you start an evaluation, you need to have your Application ID. To get this…

1. Log into your IQ Server with a user account with at least a developer role for the application you plan on evaluating.
2. Click the Organization & Policies icon .
3. 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:
   
   

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

Evaluating an Archive or Directory

java -jar [nexus-iq-cli jar] -i [application id] -s [server URL] -a [username:password] [target]

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

--pki-authentication

Delegate to the JVM for authentication.

-xc, --expanded-coverage

Use the -xc switch to enable Expanded Coverage analysis (available in IQ Server versions 1.35 and newer). 

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

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.

-X, --debug

This switch enables debug logging to help troubleshooting.

Scan Targets

You can specify multiple scan targets, separated by spaces:

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

Scan targets on the command line use standard glob expansion, as definied by the shell the CLI is running on.

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

Example XC Evaluation

To run an XC scan, download the latest CLI jar as well as the application you want to examine to a specific directory e.g. ~/nexus-iq-server-test. For this example, the application’s filename is sample-application.zip.

To evaluate this application with XC, use the -xc switch, identify the application ID and supply it with the -i switch, add the URL of your IQ Server with -s, and use -a to authentiate with your username and password.

The following example shows command line for an XC evaluation with 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 -xc -i Test123 -s http://localhost:8070 -a username:password sample-application.zip

Go ahead and try an XC evaluation yourself. The Nexus IQ CLI accepts 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] The expanded coverage report can be viewed online at 
http://localhost:8070/ui/links/application/Test123/report/24f4d0769c3f47d18ef0f154e364209d

Copy the URL and paste into a Web browser to view the results:

For more information, see Lifecycle XC.

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.