Nexus IQ for Azure DevOps
Table of Contents
- Update to a New Version
- Policy Evaluation
- HTTP Proxy Configuration
- Tips and Tricks
- Sign in to your Azure DevOps account at https://dev.azure.com
- At the bottom left corner, you should see an "Organization settings" button:
- From the left-hand side menu choose "Extensions":
- Click "Browse Marketplace" button in the top right corner of the page:
- You're going to be redirected to the Azure DevOps Extensions marketplace
- Enter "Nexus IQ" in the search box and you should find the Nexus IQ extension
- After clicking on found Nexus IQ extension, you'll be redirected to the extension's page
- Click on the green "Get" button, after that the installation process will be initiated
- Follow the installation steps and when it is done you should see that the Nexus IQ extension is presented on the "Organization Settings" page:
Update to a New Version
Usually, if a new version of the extension has appeared on the Azure Marketplace, it is updated automatically,
but there are some cases, when there is a change in access permissions for the extension in Azure DevOps and a user should approve that manually.
This process is easy, just go to the "Organization settings" → "Extensions" (the same menu from the "Installation" section) and in the "Installed" extension tab
you should see an "Action required" message. Click on the Nexus IQ extension and then on the "Review" button. After the last action, a menu with scope changes should appear.
Click the "Authorize" button and your extension will be updated to a new version.
- Proceed to your project in Azure DevOps
- The first thing we need to configure is a connection to IQ Server
- Go to the "Project Settings" in the bottom left corner
- Choose "Service Connections" from the menu which appeared:
- Click "New Service Connection" button and choose "Nexus IQ" from the list of connections:
- Enter the URL and credentials for your Nexus IQ server in the pop-up window and click "OK" button:
YAML Pipeline Configuration
- Now choose "Pipelines" → "Builds" from the left-hand side menu:
- If you don't have it already, create a "New build pipeline":
- You should see the following screen now:
- Choose a repository where you host your project from the list above and follow the steps until the pipeline is created
- Now let's "Edit" a build pipeline:
- The last action should open an azure-pipelines.yml file
- Search for "Nexus IQ" in the search box on the right-hand side of the page:
- Click on found Nexus IQ task extension, you should see a configuration screen:
- Fill out all the fields in the configuration page from the above screenshot:
- Nexus IQ service connection (configured previously)
- NEW IN VERSION 1.5 Organization ID (optional): ID of the organization under which the application will be created if the automatic application creation is enabled and the application does not exist.
- Application ID: ID of the application to evaluate against as configured in Nexus IQ
- Stage: Stage in IQ for the evaluation
- Scan Targets: Targets to perform policy evaluation are listed as comma-separated glob patterns (more details below). E.g.
- Ignore IQ Server's system errors: Controls the pipeline outcome when the scan or evaluation fails to produce results for some (possibly intermittent) connection problem. Usually such a failure would result in a FAILURE of the pipeline, but ignoring system errors allows it to show as a WARNING on the pipeline. DNS and network connection failures can be ignored, but misconfiguration of Stages or Application IDs cannot be ignored.
- NEW IN VERSION 1.4 Enable Debug Logging: Enables debug logging for IQ policy evaluation. This should be used only to troubleshoot any problem you may have when scanning a repository.
- Java System Properties (Advanced): Command line arguments to alter the behavior of the JVM. e.g.
- Hit the "Add" button, and you should see all inputs will be reflected in the YAML file
- Save your build by clicking the "Save" button in the right top corner of the page:
- The configuration of the Nexus IQ extension is finished on this, and you can run your builds with policy evaluation in place
The Scan Targets field allows for a fine-grained selection of the files against which the policy evaluation is performed. Scan targets are listed as comma-separated glob patterns. The supported glob patterns are described in the file matching patterns reference section of the Azure DevOps documentation.
The provided glob patterns are evaluated against the files located in two directories:
the system default working directory - the local path on the agent where your source code files are downloaded. For example:
the build artifact staging directory - the local path on the agent where any artifacts are copied to before being pushed to their destination. For example:
The union of the two file sets that match the provided glob patterns is used as target of the policy evaluation.
For instance, the following scan target will consider for evaluation all the JAR and POM files found anywhere under the two directories mentioned above:
The Azure DevOps glob patterns also support exclude patterns (all above examples are include patterns). The exclude patterns start with a '
!' character and must be specified after all other include patterns. For example, the following scan target will consider for evaluation all files except those under the '
Classic Pipeline Configuration
There is a possibility to use an older (classic) editor during the creation of a new pipeline in Pipelines → Build
Following the 1st step from the YAML Configuration of this guide, you can choose "Using the classic editor to create a pipeline without YAML":
Provided you followed the next steps and created a pipeline in classic mode, you can add the Nexus IQ pipeline task by clicking on the plus icon in the "Agent job" tile:
The following configuration of the Nexus IQ task is the same as in the 11-14 steps of the previous section.
To enable the widgets correctly: Enable the "Allow scripts to access the OAuth token" checkbox. It is located under the "Agent job" tile:
Now that you have configured the Nexus IQ extension, you can start running policy evaluation as a part of your build.
Try to run a build and observe that among other tasks you also have a "NexusIqPipelineTask":
Now, if you open NexusIqPipelineTask you'll see a console output with the results of the evaluation:
You can find a summary of the policy evaluation as well as the link to the detailed report at the IQ Server side.
Select the Nexus IQ Build Report tab on the build for a detailed report with all the components and their correspondent violations:
NEW IN VERSION 1.4: Select the Nexus IQ Summary Report tab on the build to see a summary report for the policy evaluation for the scanned components:
Let's take a look at one more feature of Azure DevOps UI, which is called "Dashboards" (go to the "Overview" → "Dashboards").
In this section, you can add various UI widgets to your project. Of course, such a widget also exists for "Nexus IQ".
- Click the "Edit" button, this should switch you to the edit mode
- At the right-hand side search for the "Nexus IQ" widget:
- Select it and hit the "Add" button at the bottom right corner of the page
- Click the "Done editing" button, which will switch you back from the editing mode
- You should see the "Nexus IQ Policy Summary" widget up and running
The widget always shows the latest build summary results:
There is another widget available for you which shows a history of Nexus IQ Policy evaluation of the last 5 builds: "Trends for Nexus IQ Policy Evaluation"
Just follow the same steps as in the case with the "Latest Nexus IQ Policy Evaluation" widget and you should see a similar picture as below:
HTTP Proxy Configuration
If you use an HTTP proxy within your infrastructure and use Azure self-host build agents, then the Azure DevOps agent options for a proxy can be specified and then will be automatically used while connecting to IQ.
So in the Azure provided sample command:
./config.sh --proxyurl http://127.0.0.1:8888 --proxyusername "myuser" --proxypassword "mypass"
This would then appear in the scan output as it is passed through to the IQ scan client:
... -p 127.0.0.1:8888 -U myuser:*** ...
Tips and Tricks
- The Azure DevOps extension uses the Nexus IQ CLI to perform the scan. Part of the IQ CLI scan process involves using git to determine the repository URL and commit hash. If native git is available on the agent then that is used, otherwise, jgit (java-git) is used. If jgit is used it tries to create some config files in the
$HOMEdirectory of the current user. If it does not have sufficient permissions to do that you may see logs on 'ERROR' level. These are not critical errors to the scan and can be ignored. To address the error, ensure native git is available or for jgit set the
XDG_CONFIG_HOMEenvironment variable to a directory that is writable by the build agent user.