Overview
Major improvements to the Azure DevOps integration will be introduced in July 2021. The underlying scanning mechanism will be modified to allow a direct WhiteSource scan from within the Azure DevOps pipeline. As part of this change, the following updates will be introduced:
The extension activation procedure will be moved to the Organization settings section by navigating to Organization settings > Extensions > WhiteSource page.
The WhiteSource tab under Project > Pipelines will be deprecated.
The WhiteSource Open Source Risk Report will be available at the Azure DevOps build level only, deprecating the project level aggregated report.
The direct WhiteSource scan from within the Azure DevOps pipeline will be the only scanning option.
This integration is not currently supported for customers on a WhiteSource Dedicated Instance or WhiteSource On-Premises instance.
This integration does not support Azure DevOps Server (TFS) installations.
The Azure DevOps Services native integration is enabled via the WhiteSource for Azure DevOps Services extension. It enables you to do the following:
Detect and remediate vulnerable open source components
Generate a comprehensive open-source inventory report per project or build
Enforce open source license compliance, including dependencies’ licenses
Identify outdated open-source libraries with recommendations to update
NOTES:
The extension maps an Azure DevOps Project (and all of its pipelines which are integrated with WhiteSource) to a defined WhiteSource Product. The WhiteSource Product is generated by the extension as part of the integration.
To map between an Azure DevOps pipeline build and a WhiteSource Product, it is recommended to use the Unified Agent integration.
Support for Languages and Package Managers
The Azure DevOps Services integration supports languages and package managers that are supported today by the Unified Agent.
Note the following current limitations:
Docker image scanning is not supported.
Effective Usage Analysis capabilities are not supported
The ability to fail a pipeline build due to a WhiteSource Policy violation is not currently supported.
Prerequisites
Ensure the following:
Your Azure DevOps organization is connected to an Azure AD via Organization Settings > Azure Active Directory.
An activation key for this Azure DevOps integration, available via the WhiteSource application's Integrate tab.
The New Version alerts setting is enabled via Admin > Alert Settings. When disabled, no information is displayed in the Outdated Libraries tab of the Open source risk report.
If you are using a self-hosted build agent, note that running it behind a web proxy is not currently supported.
Python support: The default Python version supported is 2.7. If you have a python project with version 3 or above, you will need to perform the following procedure:
In the WhiteSource task, locate the WhiteSource Configuration field.
Add the following parameter to it: python.path=python3.
Installing the Extension
To install the extension, do as follows:
Click here. The WhiteSource for Azure DevOps Services extension page is displayed.
Click Get and follow the installation procedure.
Activating the Extension
To activate the extension, do as follows:
To re-activate the extension using a different WhiteSource account (activation key), uninstall the extension and then follow the instructions below.
Inside your Azure DevOps organization, open any of your projects. If you do not have any projects, create one before proceeding.
In the project page, from the sidebar, click Pipelines. The Pipelines page is displayed.
From the sidebar, click WhiteSource.
In the WhiteSource page, an activation form enabling you to connect to your WhiteSource account is displayed.
Enter the following details:
First name
Last name
Work email
Company name
Country
Activation key - Go to the WhiteSource application, and from Integrate > Azure DevOps Integration, click the Generate Activation Key link, and then copy the activation key. NOTE: If you are not a WhiteSource administrator, get the activation key from the administrator.
Click Connect Account. Your extension is now connected to your WhiteSource account.
Configuring Organizational Settings
You can define whether data from the latest build on each of your organization’s pipelines will overwrite previous build data (default). This way, WhiteSource will only store and generate a report for the latest build data of a particular pipeline definition.
Alternatively, you can have WhiteSource store data and generate a report for all builds instead of only the latest. Do as follows:
Ensure that you followed the procedures in Activating the Extension.
Inside your Azure DevOps organization, go to Organization Settings > Extensions > WhiteSource.
Clear the Overwrite projects with latest build data checkbox, and click Save.
Ensure that you follow the procedures in Adding a WhiteSource Build Task to Your Pipeline.
Configuring Project Settings
The default WhiteSource product name, that will be associated with your specific Azure DevOps project, is AZDO_<PROJECT_NAME>. You can customize the product name as needed.
There are two options to specify the WhiteSource product:
Existing WhiteSource scans that were triggered before changing the WhiteSource product name will remain under the previously-set WhiteSource product.
Define a new WhiteSource product to create and associate your Azure DevOps project to
Select a product from a list of existing WhiteSource products
Defining a New WhiteSource Product
To define a new WhiteSource product to create and to associate your Azure DevOps project to, do as follows:
Ensure that you followed the procedures in Activating the Extension.
Inside your Azure DevOps organization, go to a specific project.
Inside your Azure DevOps project, go to Project Settings > Extensions > WhiteSource.
In Product name, enter the desired WhiteSource product name. As you enter the name, it will simultaneously appear under the input field; click that name below.
In the Add a new Product dialog box, click Add.
Under the Product name field click Save.
The new product will be created in the WhiteSource application. Any build that will run in the specific Azure DevOps project will have results appear in the WhiteSource Application under the provided product name.Ensure that you follow the procedures in Adding a WhiteSource Build Task to Your Pipeline.
Selecting a Product From a List of Existing WhiteSource Products
To select a product from a list of existing WhiteSource products, do as follows:
Ensure that you followed the procedures in Activating the Extension.
Inside your Azure DevOps organization, go to a specific project.
Inside your Azure DevOps project, go to Project Settings > Extensions > WhiteSource.
In Product name, click the input field, and a list of existing WhiteSource product names will be displayed.
Select a suitable name. Once selected, it should be displayed in the input field. Click Save.
Any build that will run in the specific Azure DevOps project will have results appear in the WhiteSource Application under the provided existing WhiteSource product.Ensure that you follow the procedures in Adding a WhiteSource Build Task to Your Pipeline.
Adding a WhiteSource Build Task to Your Pipeline
To add a WhiteSource build task to your existing pipeline, do as follows:
Go to the relevant Azure DevOps project for which you want WhiteSource to run.
Inside your Azure DevOps project, from the sidebar, click Pipelines. The Pipelines page is displayed.
Click the relevant pipeline. The specific pipeline page is displayed.
Click Edit. Do one of the following procedures:
This activates the WhiteSource integration on your build pipeline.
NOTE: Adding a pre-step build task is not necessary in order for WhiteSource to successfully scan the build repository. WhiteSource by default runs a pre-step command as part of the WhiteSource task.
Adding a Build Task to a YAML Pipeline
In the pipeline edit page, from the right side, click Show assistant. The Tasks sidebar is displayed.
In the search bar, enter whitesource. The WhiteSource task is displayed.
Click the WhiteSource task.
From the bottom right corner, click Add. The WhiteSource task is added to the pipeline.
- task: whitesource.WhiteSource-azure-devops-services.bolt.wss.WhiteSource@21
(Optional) To specify the name of the WhiteSource project to be created, add the following to the WhiteSource task. In the following example, replace
New_Project_Name
with the name you want to give your WhiteSource project:
NOTE: When the Overwrite projects with latest build data checkbox from the Organization Settings > Extensions >WhiteSource is selected, you will be unable to change the project name after the first build run.- task: whitesource.WhiteSource-azure-devops-services.bolt.wss.WhiteSource@21 inputs: cwd: '$(System.DefaultWorkingDirectory)' projectName: 'New_Project_Name'
(Optional) To specify custom Unified Agent Configuration parameters, add all parameters in the WhiteSource Configuration field (ensure each parameter along with its value are provided on a separate line). In the following example, under
configuration
, provide all relevant parameters.
NOTE: The parameters used here overwrite the default configuration parameters. Configuration parameters that were not provided will use the default values as described here.- task: whitesource.WhiteSource-azure-devops-services.bolt.wss.WhiteSource@21 inputs: cwd: '$(System.DefaultWorkingDirectory)' configuration: | npm.resolveDependencies=true maven.resolveDependencies=true
Click Save & queue.
NOTE: The WhiteSource task can be moved to other locations within the steps section, depending on your preferences.
Adding a Build Task to a Classic Pipeline
To add a task to the Agent Job, click the plus (“+”) sign next to the agent job section. The Add Tasks section is displayed.
In the search bar, enter whitesource. The WhiteSource task is displayed.
Click the WhiteSource tab, and then click Add. The WhiteSource task is added to the pipeline.
(Optional) To specify the name of the WhiteSource project to be created, enter the name in the Project name field.
NOTE: When the Overwrite projects with latest build data checkbox from Organization Settings > Extensions > WhiteSource is selected, you will be unable to change the project name after the first build run.(Optional) To specify custom Unified Agent Configuration parameters, add all parameters in the WhiteSource Configuration field (ensure each parameter name along with its value are provided on a separate line).
NOTE: The parameters used here overwrite the default configuration parameters. Configuration parameters that were not provided will use the default values as described here.Click Save & queue.
NOTE: The WhiteSource task can be moved to other locations within the steps section, depending on your preferences.
Viewing the WhiteSource Report
The WhiteSource report comprises four tabs: Inventory, Outdated Libraries, Security Vulnerabilities, and License Risks. You can view the WhiteSource report at a build or project level (aggregated report of all your builds).
Viewing the Report at a Build Level
To view the report at a build level, do as follows:
Ensure that you followed the procedures in Activating the Extension and Adding a WhiteSource Build Task to Your Pipeline.
Go to the specific build’s results page for your project, and click the WhiteSource tab. The WhiteSource open-source Risk Report is displayed.
Viewing the Report at a Project level
NOTE: Data in this report relates to all projects that were created in WhiteSource as part of the specific Azure DevOps project pipeline runs.
To view the report at a project level, do as follows:
Ensure that you followed the procedures in Activating the Extension and Adding a WhiteSource Build Task to Your Pipeline.
Open a specific project and from the sidebar, click Pipelines. The Pipelines page is displayed.
Click the WhiteSource tab. The WhiteSource open-source Risk Report is displayed.
Understanding the Report
Security Summary
A summary of detected open source vulnerabilities and the libraries that contain them.
Name | Description |
---|---|
Vulnerability Risk | The overall risk level for your inventory. Can be High, Medium, Low, No Risk. |
Vulnerable Libraries | Displays the total number of vulnerable libraries. |
Severity Distribution | Provides a breakdown of the vulnerabilities according to their severity level. |
Inventory Tab
An inventory of all open source libraries detected.
Name | Description |
---|---|
Library | The name of the open-source library linking to the Library Details page in the WhiteSource application. |
Licenses | Lists licenses detected for each library, and links to their license descriptions. |
Outdated Libraries
Libraries that have not been updated to their newest available versions.
Name | Description |
---|---|
Library | The name of the outdated library, linking to the Library Details page in the WhiteSource application. |
Your version | The version number of the outdated library. |
Newest stable version | The library’s most up-to-date version number. |
Security Vulnerabilities
A table listing all security vulnerabilities.
Name | Description |
---|---|
Severity | The severity of the vulnerability. Consists of:
|
Vulnerability | The vulnerability identifier linking to the WhiteSource vulnerability lab, containing more information. |
Date | The vulnerability publish date. |
Library | The name of the open-source library containing the vulnerability, linking to the Library Details page in the WhiteSource application. |
Top Fix | The top-rated remediation advice that WhiteSource recommends for each vulnerability. A condensed description of the recommended course of action is given, followed by a link to a broader description. |
License Risks
The License Risk Table displays a summary of open-source components’ license types and their associated risk including the number of occurrences.
Name | Description |
---|---|
License | The license detected as part of the inventory linking to its license description. |
Risk | The risk associated with the license. Values are H (high), M (medium), L (low). In case of unknown risk, no risk is displayed. |
Occurrences | In how many libraries this license occurs. |
Additionally, the following charts are displayed:
The License Distribution chart displays the distribution of licenses across the inventory.
The License Risk Distribution chart breaks down the number of licenses by their risk level. Unknown risk level means the license risk was not analyzed by WhiteSource.