Installation and Configuration - Sonatype for Azure DevOps

Installation and Configuration - Sonatype for Azure DevOps

Installation

  1. Sign in to your Azure DevOps account at https://dev.azure.com.

  2. Click the "Organization Settings" button at the bottom left corner:

  3. From the left-hand side menu, select "Extensions":
  1. Click the "Browse Marketplace" button in the top right corner of the page. You will be redirected to the Azure DevOps Extensions marketplace.

  1. Enter "Sonatype IQ" in the search box to find Sonatype for Azure DevOps.

  2. Click on the "Sonatype for Azure DevOps" tile to access the extension's home page.

  3. Click on the "Get it free" button to start the installation process.

  4. Follow the on-screen steps to complete the installation.

The Sonatype for Azure DevOps icon will now be visible on the Organization Settings page as below:

Java Runtime Requirements

Note

The Sonatype for Azure DevOps extension requires a Java runtime to be installed on the Azure DevOps agents.

For extension versions up to 1.7.21 (included), Java 8 is the minimum required runtime version. Azure DevOps agents usually include either Java 8 or 11 by default, so no additional configuration is needed for the extension.

Starting with version 2.0.0 of the extension, Java 17 is the minimum required runtime version. If your Azure DevOps agents are set up to use Java 17 by default, no additional configuration is needed for the extension. Otherwise, you'll need to configure your pipeline to use Java 17. There are a couple of ways to do this:

  1. Modify your pipeline's YAML file:
     - task: JavaToolInstaller@0
       inputs:
         versionSpec: '17'
         jdkArchitectureOption: 'x64'
         jdkSourceOption: 'PreInstalled'
     ```

- This will ensure the pipeline uses Java 17 for all subsequent tasks.

2. Configure through the Azure Pipelines UI:

- Click on the "Java tool installer" task in your pipeline.

|     |
   | --- |
   |  |
   
   - Set the JDK version field to 17 and the other options as shown below:

|     |
   | --- |
   |  |

After running the task, you can reset the Java version to your preferred version for subsequent tasks in your pipeline using the same method described above.

## Updating to a newer version of Sonatype for Azure DevOps

By default, if a new version of the extension has been released in the Azure DevOps Marketplace, it is updated in your pipeline automatically.

In some cases, when there is a change in access permissions for the extension, manual user approval will be required to install the update. Follow the steps below:

1. Go to "Organization settings" → "Extensions" (the same menu as the "Installation" section) → "Installed" extension tab

2. An "Action required" message appears.

3. Click on "Sonatype for Azure DevOps".

4. Click the "Review" button.

5. A menu with scope changes appears.

6. Click the "Authorize" button.

_Sonatype for Azure DevOps_ is now updated to the new version.

## Configuration

### Sonatype IQ Service Configuration

1. Open your project in Azure DevOps.

2. Go to "Project Settings" in the bottom left corner.

3. Select "Service Connections" from the menu:

4. Click the "New Service Connection" button and select "Sonatype IQ" from the list of connections:

5. Enter the URL and credentials for your Sonatype IQ server in the pop-up window and click the "OK" button:

### YAML Pipeline Configuration

1. Select **Pipelines** → **Builds** from the left-hand side menu:

|     |
   | --- |
   |  |

2. If you don't have a pipeline already setup, click on **New** and select **New build pipeline**:

The following message will appear:

Select a repository where you host your project from the list above and follow the steps to create the pipeline.

3. To edit an existing build pipeline, click on **Edit**:

An `azure-pipelines.yml` file will be opened.

4. Search for "Sonatype" in the search box on the right-hand side of the page:

5. Click on one of the tasks, **Sonatype Evaluate** or **Sonatype for Azure DevOps**, to access the configuration screen as below:

|     |     |
   | --- | --- |
   |  |  |

6. Configure the Sonatype IQ task on the configuration page, as below:

- _IQ CLI Version_: Sonatype CLI version to be used. It could be `latest`, a full version (e.g. `2.1.0-01`), or a short version (e.g. `2.1.0`, which is expanded to `2.1.0-01`). IQ CLI Version and IQ CLI Download URL are both optional, but only one should be specified, not both. If neither is provided, the latest CLI version will be downloaded and used automatically. _Exclusive to the Sonatype Evaluate task._
   - _IQ CLI Download URL_: URL from where the Sonatype CLI JAR file will be downloaded. IQ CLI Version and IQ CLI Download URL are both optional, but only one should be specified, not both. _Exclusive to the Sonatype Evaluate task._

**Note**

These parameters are exclusive to **Sonatype Evaluate** because the **Sonatype for Azure DevOps** task (`NexusIqPipelineTask`) always downloads the latest IQ CLI automatically and does not expose version or URL controls. If you need to pin a specific CLI version, use Sonatype Evaluate instead.

The URL must meet the following requirements:

- Must use HTTPS protocol for security
     - Must end with the filename format: `nexus-iq-cli-{version}.jar`
     - The `{version}` must follow this pattern:` major.minor.patch-build` (`e.g. 2.7.0-01`)

**Example:**
     
     ```
     https://download.sonatype.com/clm/scanner/nexus-iq-cli-2.7.0-01.jar
     ```

**Note**

For security, the action validates the downloaded file using checksums. Only unmodified official releases of the CLI will work.
   - _IQ CLI Download URL Authentication_: Credentials for accessing the IQ CLI download URL. Format: `username:password`. If provided, the value will be used for basic authentication.
   - _Sonatype IQ Service Connection_ (configured previously).
   - _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 Sonatype 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. `**/*.jar, **/*.json`
   - _Use ${Pipeline.Workspace} as the base folder for scanning_: If checked, the above scan targets are evaluated against the ${Pipeline.Workspace} folder and its descendants (more details below).
   - _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.
   - _Ignore IQ Server's Scanning errors_: Controls the pipeline outcome when there are scanning errors such as malformed files. Scanning errors result in a `FAILURE` of the pipeline if they are not ignored. Ignoring scanning errors will lead to pipeline finishing in a `WARNING` state instead of a `FAILURE`.
   - _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.
   - _Result File_ (optional): The name of the file produced by the evaluation task. Leave blank to accept the default `evaluationResult.json` or supply your own filename (e.g., `policy-evaluation-result.json`)
   - _Sarif File_ (optional): Generate a SARIF file named as you specify, containing all identified vulnerabilities. The file must have a `.sarif` extension and can then be uploaded as a pipeline artifact.
   - _Java System Properties_ (Advanced): Command line arguments to alter the behavior of the JVM, for example:
     
     `-Djava.net.useSystemProxies=false`

For **Reachability Analysis** configuration, see [Reachability Analysis with Sonatype for Azure DevOps](https://help.sonatype.com/en/reachability-analysis-with-sonatype-for-azure-devops.html "Reachability Analysis with Sonatype for Azure DevOps").

7. Click the "Add" button to update the YAML file with the above inputs.

8. Save your build by clicking the "Save" button in the right top corner of the page:

9. Configuration of Sonatype for Azure DevOps is now complete and ready to run policy evaluations on your builds.

### Scan Targets

The _Scan Targets_ field allows for a fine-grained selection of the files on 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](https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/file-matching-patterns?view=azure-devops) section of the Azure DevOps documentation.

The provided glob patterns are evaluated as follows:

- If _Use ${Pipeline.Workspace} as the base folder for scanning_ is checked, they are evaluated against the files located in the pipeline workspace directory (and its descendants)

- Otherwise, they are evaluated against the files located in two directories:

- ${System.DefaultWorkingDirectory} - the system default working directory - the local path on the agent where your source code files are downloaded. For example: `c:\agent_work\1\s`
  - ${Build.ArtifactStagingDirectory} - 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: `c:\agent_work\1\a`

The union of all the files that match the provided glob patterns is used as target for the policy evaluation.

For example, the following scan target will consider for evaluation all the JAR and POM files found anywhere under the two directories mentioned above: `**/*.jar, **/pom.xml`

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 '`.git`' directory: `**, !**/.git/**`

#### Usage Example - Sonatype Evaluate Task

```yaml
- task: SonatypeEvaluate@0
  inputs:
    cliVersion: '2.3.0'
    nexusIqService: 'local_iq'
    applicationId: 'sandbox-application'
    organizationId: 'sandbox-organization'
    stage: 'Build'
    scanPipelineWorkspace: true
    ignoreSystemError: true
    ignoreScanningError: true
    javaSystemProperties: '-Daaaaa=bbbbb'
    scanTargets: '**/*.jar, **/*.war, **/*.ear, **/*.zip, **/*.tar.gz'
    enableDebugLogging: true
    enableReachability: true
    reachabilityNamespaces: 'test-reachability-namespace'

Usage Example - Sonatype for Azure DevOps Task

- task: NexusIqPipelineTask@0
  inputs:
    nexusIqService: 'local_iq'
    applicationId: 'sandbox-application'
    organizationId: 'sandbox-organization'
    stage: 'Build'
    scanPipelineWorkspace: true
    ignoreSystemError: true
    ignoreScanningError: true
    javaSystemProperties: '-Daaaaa=bbbbb'
    scanTargets: '**/*.jar, **/*.war, **/*.ear, **/*.zip, **/*.tar.gz'
    enableDebugLogging: true
    enableReachability: true
    reachabilityNamespaces: 'test-reachability-namespace'

NexusIqPipelineTask no longer includes an embedded IQ CLI

The embedded IQ CLI JAR has been removed from the NexusIqPipelineTask extension package. The task now downloads the latest IQ CLI automatically at runtime. Existing pipelines continue to work without any configuration changes.

The downloaded CLI version is always the latest available. If you need to control which CLI version is used, switch to the Sonatype Evaluate (SonatypeEvaluate) task, which provides that flexibility.

Optional: Using the classic editor to create a pipeline without YAML

  1. Select "Pipelines" → "Builds" from the left-hand side menu.

  2. Click the "Use the classic editor to create a pipeline without YAML" link at the bottom.

  3. After creating a pipeline in the classic editor, add a Sonatype IQ pipeline task by clicking the "+" icon on the "Agent job" tile:

  4. Configure the Sonatype IQ task.

  5. Enable the "Allow scripts to access the OAuth token" checkbox under the "Agent job" tile to enable widgets correctly with settings as below:

Publishing the Result File as an Artifact

The Sonatype Evaluate and Sonatype for Azure DevOps tasks can export the scan results as a JSON file so you can keep or share them after the pipeline run. The steps below show how to publish that file either in the UI or in YAML with Azure DevOps’ built-in Publish Pipeline Artifact task.

  1. Go to the Evaluate task settings and edit the following:
  1. Add a Publish Pipeline Artifact task

When the run finishes, open the Artifacts panel and click the artifact name (e.g., sonatype-evaluation-result) to download the JSON file.

Usage Example - YAML Pipeline

# ── 1. Evaluate policies ────────────────────────────────────────────────────────
- task: NexusIqPipelineTask@2
  displayName: 'Sonatype IQ policy evaluation'
  name: sonatypePolicyEvaluation          # ← choose any alias
  inputs:
    nexusIqService: 'sonatype-iq-server'
    applicationId: 'azure-app-01'
    scanTargets: '**/pom.xml'
    resultFile: policy-evaluation-result.json    # optional; default is evaluationResult.json

# ── 2. Publish the JSON result as an artifact ───────────────────────────────────
- task: PublishPipelineArtifact@1
  displayName: 'Publish Policy-Evaluation Result'
  inputs:
    targetPath: '$(sonatypePolicyEvaluation.resultFile)'   # output variable
    artifact: sonatype-evaluation-result                   # archive name (your choice)
    condition: succeededOrFailed()

Variable notes:

Fetch SBOM Task

Use this task after an IQ policy evaluation has run. Beforehand, configure the settings for the Sonatype Evaluate, Sonatype Fetch SBOM, and Publish Pipeline Artifact tasks.

  1. Go to the Evaluate task settings. Under the Output Variables section, specify a custom value in the Reference name field, for example, "sonatype_eval". Azure DevOps generates a variable by appending .scanID, producing sonatype_eval.scanID to be used by the Fetch SBOM task.

  2. Go to the Fetch SBOM task and complete the required fields.

  1. Go to the Publish Pipeline Artifact task.

After the pipeline completes, the run logs confirm that an artifact was produced.

Open the Artifacts panel and click the artifact name (e.g., sbom.zip) to download the SBOM file.