Skip to main content

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:

    126655777.png

  3. From the left-hand side menu, select "Extensions":

    126655776.png

  4. Click the "Browse Marketplace" button in the top right corner of the page. You will be redirected to the Azure DevOps Extensions marketplace.

    126655775.png

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

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

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

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

    126655774.png

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:

    • Add the following task to install the correct Java version:

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

      Azure_-_Java_tool_installer.png

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

      Azure_-_Java_17.png

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:

    126655773.png

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

    126655772.png

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

    126655759.png

YAML Pipeline Configuration

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

    126655770.png

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

    126655769.png

    The following message will appear:

    126655780.png

    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":

    126655768.png

    An azure-pipelines.yml file will be opened.

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

    AzDO_tasks.png

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

    AzDO_Sonatype_Evaluate_task.png

    171672037.png

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

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

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

    3. Sonatype IQ Service Connection (configured previously).

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

    5. Application ID: ID of the application to evaluate against as configured in Sonatype IQ

    6. Stage: Stage in IQ for the evaluation

    7. Scan Targets : Targets to perform policy evaluation are listed as comma-separated glob patterns (more details below). E.g. **/*.jar, **/*.json

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

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

    10. 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 in case of scanning errors.

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

    12. Enable Reachability: Perform a Reachability Analysis in Java or JVM language binaries to determine the method signatures that trigger a security vulnerability.

    13. Reachability namespaces: Limit the Reachability Analysis to a specific namespace for faster, more precise results. You can specify multiple namespaces by separating them with a space, for example:

      com.package1 org.package2

    14. Java System Properties (Advanced): Command line arguments to alter the behavior of the JVM, for example:

      -Djava.net.useSystemProxies=false

  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:

    126655765.png

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

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

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.

    137203913.png

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

    126655779.png

  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:

    126655778.png

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:

    • Result File: leave blank to accept the default evaluationResult.json or supply your own filename (e.g., policy-evaluation-result.json)

    • Reference name: enter any alias (e.g., sonatypeEvaluate).

    • After you save, Azure DevOps generates an output variable by appending .resultFile to the reference name you provided, (e.g., sonatypeEvaluate.resultFile).

  2. Add a Publish Pipeline Artifact task

    • File or directory path: set it to the variable Azure DevOps produced in the previous step (e.g. $(sonatypeEvaluate.resultFile)

    • Artifact name: enter any alias (e.g., sonatype-evaluation-result).

    • Control Options: select Even if a previous task has failed, unless the build was canceled from the Run This Task drop-down list.

      ADO_-_Publish_Pipeline_Artifact.png

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

ADO_-_Artifacts_-_Evaluation_Results_JSON.png

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:

  • artifact: The name that appears in the Artifacts panel after the run. You can enter any identifier; the JSON file inside the artifact (e.g., the default evaluationResult.json or the custom name you supplied in targetPath) keeps its original filename.

  • $(<reference_name>.resultFile): The path to the JSON file produced by the Sonatype Evaluate task. The resultFile suffix is fixed, only the <reference_name> part changes to match the task’s name (sonatypePolicyEvaluation in the example).

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.

    ADO-reference-name.png

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

    • Scan ID: use the automatically-generated variable created by Azure DevOps from the Reference name set in the policy-evaluation task. For example, $(sonatype_eval.scanId).

    • Control Options: select Even if a previous task has failed, unless the build was canceled from the Run This Task drop-down list.

    • Reference name: enter any value, for example, fetch_sbom. Azure DevOps then exposes the variable as: fetch_sbom.sbom_file_name that can be used to reference the downloaded SBOM file in later pipeline steps.

      ADO_-_Fetch_SBOM.png

  3. Go to the Publish Pipeline Artifact task.

    • File or directory path: set it to the variable Azure DevOps produced in the previous step; e.g., $(fetch_sbom.sbom_file_name)

    • Artifact Name: allows you to specify the name of the SBOM file that will be published in the pipeline; e.g., sbom.zip.

    • Control Options: select Even if a previous task has failed, unless the build was canceled from the Run This Task drop-down list.

      ADO_-_Publish_Pipeline.png

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

ADO_-_Produced_artifact.png

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

ADO_-_Artifact_download.png

Usage Example - YAML Pipeline

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: JavaToolInstaller@1
  displayName: 'Use Java 17'
  inputs:
    versionSpec: 17
    jdkArchitectureOption: x64
    jdkSourceOption: PreInstalled

# ── 1. Evaluate policies ────────────────────────────────────────────────────────
- task: NexusIqPipelineTask@2
  displayName: 'Sonatype IQ policy evaluation'
  name: sonatypePolicyEvaluation
  inputs:
    nexusIqService: 'sonatype-iq-server'
    applicationId: 'azure-app-01'
    scanTargets: '**/pom.xml'

# ── 2. Fetch the SBOM produced by that scan ─────────────────────────────────────
- task: SonatypeFetchSbom@2
  displayName: 'Sonatype IQ Fetch SBOM'
  name: sonatypeFetchSbomTask
  inputs:
    nexusIqService: 'sonatype-iq-server'
    applicationId: 'azure-app-01'
    scanId: '$(sonatypePolicyEvaluation.scanId)'
    sbomStandard: cycloneDx
    sbomVersion: 1.6
    sbomFormat: xml
  condition: succeededOrFailed()

# ── 3. Publish the SBOM as a pipeline artifact ─────────────────────────────────
- task: PublishPipelineArtifact@1
  displayName: 'Publish Pipeline Artifact'
  inputs:
    targetPath: '$(sonatypeFetchSbomTask.sbom_file_name)'
    artifact: sbom.zip
  condition: succeededOrFailed()
Variable notes:

  • name: (in each task): Creates a reference name for that task’s output variables. You can enter any identifier.

  • $(<reference_name>.scanId): References the scan ID emitted by the Evaluation task. Must match the reference name you chose.

  • $(<reference_name>.sbom_file_name): References the SBOM filename emitted by the Fetch SBOM task. Again, use the reference name you assigned.