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.
With regard to integrating the Nexus IQ CLI with CI servers, you should also have a familiarity with the way your particular CI utilizes build steps to launch a simple script.
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.
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.
Note: Currently, the pki option is not available via the docker image.
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.
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).
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.
-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.
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.
-X, --debug
This switch enables debug logging to help troubleshooting.
The resulting debug log may contain sensitive information. Use this option with care.
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.
Lifecycle XC is supported in IQ Server versions 1.35 and newer.
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.
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.