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 the NexusIqPipelineTask, 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:

    126655767.png

  5. Click on the found Sonatype for Azure DevOps task extension to view a configuration screen:

    171672037.png

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

    1. Sonatype IQ service connection (configured previously)

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

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

    4. Stage: Stage in IQ for the evaluation

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

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

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

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

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

    10. Enable Callflow: Perform a call flow analysis in Java or JVM language binaries to determine the method signatures that trigger a security vulnerability.

    11. Callflow namespaces: Limit the call flow 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

    12. 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/**

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