WhiteSource Bolt for Azure Documentation

Last Updated on 15/12/2018

Introduction

WhiteSource Bolt is a lightweight open source security and management solution, integrated within Microsoft’s Azure DevOps Services & Team Foundation Server (TFS) products. It enables you to do the following:

  1. Detect and remedy vulnerable open source components.
  2. Generate comprehensive open source inventory reports per project or build.
  3. Enforce open source license compliance, including dependencies’ licenses.
  4. Identify outdated open source libraries with recommendations to update.

 

Installation

The WhiteSource Bolt extension can be downloaded from the Microsoft Visual Studio Marketplace.

Click on “Get it free”, and sign in to your Microsoft account:

If you are already signed in then this step can be skipped.

The following screen is displayed:

At this stage, select the type of installation:

  • Option 1: If you have an Azure DevOps organization, select your organization and click ‘Install’.
  • Option 2: If you want to install the extension on your TFS instance, click ‘Download’ to retrieve the WhiteSource Bolt extension.

 

Option 1: Install the extension in your Azure DevOps organization

Select an Azure DevOps organization and click ‘Install’:

The ‘You are all set!’ message is displayed. Click on the ‘Proceed to organization’ button:

Go to the section Build Configuration for Azure DevOps.

 

Option 2: Download the Extension for TFS

Click on the ‘Download’ button:

The ‘whitesource.ws-bolt-<version number>.vsix’ is downloaded. Install this extension within your TFS environment. Proceed to Build Configuration for TFS.

 

Build Configuration for Azure DevOps

Create Project

Create a new project, provide a name for it, and an optional description.

The ‘Welcome to the project!’ message is displayed:

From the main menu select ‘Pipelines’→ ‘WhiteSource Bolt’.

Fill in the registration form:

 

Disabling the YAML Pipeline Creation

Disable the New YAML pipeline creation experience by doing the following:

Click on your name initials icon and select ‘Preview Features’:

Verify that the New YAML pipeline creation experience is off:

 

Setting Up the Job

Go to ‘Pipelines’ → ‘Builds’ → Click ‘+New Build’

Select the type of repository:

Select an Empty job:

Enter a name for the job and select an Agent pool:

Add a task to the Agent Job

Add the relevant prestep and WhiteSource Bolt as the last step.

Click on ‘Save and Queue’.

Click on the build number.

The ‘Monitored Build Definitions’ table is displayed while the report is loading:

The Bolt scan report is displayed:

You have the option to export the report by clicking the ‘Export Report’ button.

 

Build Configuration for TFS

TFS Users

If you are using a proxy server, make sure to add “whitesourcesoftware.com” domain name and its subdomains to your proxy whitelist. In case your proxy configuration requires authentication, then make sure your TFS build agent is properly configured> For further information, see Deploy an agent on Windows

Follow these steps:

  1. Go to your activated project page.
  2. Navigate to the Build & Release tab and click Builds.
  3. Select the build definition you wish to analyze or create a new build definition by clicking ‘+New’.
  4. Click Edit in the top right corner of your screen.
  5. Choose Add build step and the task catalog will open up in a pop-up window.
  6. Choose the Utility category
  7. Scroll down to WhiteSource Bolt and click Add, then Close.
  8. Place the WhiteSource Bolt build step after any other packaging steps such as ‘npm install’ or ‘NuGet restore’. This ensures that WhiteSource Bolt has access to all of your open source components.
  9. Optional: After adding WhiteSource Bolt to the build, click on the WhiteSource build step. On the right side you can view its configuration display:The default configuration analyzes the entire project work directory. If you prefer, you can take the following steps to create a custom configuration, specifying folders for WhiteSource Bolt to scan or exclude:
    1. Click the three-dot select path button to the right of the Work directory field.
    2. Select a path.
    3. To exclude folders, check the box next to Advanced settings, and enter a folder into the Exclude list field that pops up below.

When you’ve finished with your configurations, click Save on the left side of the screen, followed by clicking OK.

 

Using WhiteSource Bolt on TFS

Follow these steps to start a new build:

  1. Click Queue new build on the top right of your screen,followed by clicking OK.
  2. As soon as the build process completes, you’ll see a new tab in the Build Summary page called WhiteSource Bolt Build Report:If you receive an error message rather than the above build confirmation, then contact support@whitesourcesoftware.com.
  3. Click on the WhiteSource Bolt Build Report tab to view the WhiteSource Bolt analysis.

WhiteSource Bolt only displays results for each build execution that postdates WhiteSourceBolt’s installation. If you try to access a build that predates WhiteSource Bolt’s installation, then no results will be displayed.

From now on, WhiteSource generates a report each time that you execute a build.

 

Understanding the Reports

You can view WhiteSource Bolt reports at a build or project level (aggregated report of all your builds). WhiteSource Bolt does not offer an account-level report.

Reports are comprised of five sections: Security Analysis, Security Vulnerabilities, License Risks and Compliance, Outdated Libraries and Inventory.

 

Section 1: Security Analysis

A summary of detected open source vulnerabilities and the libraries that contain them.

Vulnerability Score can be Secure (green), Low (yellow), Medium (orange) or High (red). The score is determined based on the single highest severity level of any vulnerability detected. Secure indicates no vulnerable components are present at all. Low, Medium and High severities are given according to a vulnerability’s severity ranking in the National Vulnerability Database (NVD).

Vulnerable Libraries displays the total number of libraries present. The left panel displays the number of secure libraries, and the right panel displays the number of vulnerable libraries. The number of outdated libraries is parenthesized in red font.

Severity Distribution provides a breakdown of the vulnerable libraries according to their severity level.

Aging Vulnerable Libraries displays the length of time elapsed since detected vulnerabilities were first identified in the open source community.

 

Section 2: Security Vulnerabilities

A table listing all security vulnerabilities.

The Vulnerability column lists a vulnerability’s severity score, a link to its CVE or WhiteSource profile (if the vulnerability is unregistered in the CVE/NVD), and its publishing date. The column is ordered according to severity, with the most severe vulnerabilities appearing first.

The Library column lists the name of the library containing the vulnerability. Note that if a vulnerability impacts more than one source file, all impacted source files will be displayed, parenthesized and separated by commas. Binary component do not contain source files (e.g. jar, dll, tgz, etc.).

The Description column provides a description of the vulnerability as written in the CVE database. If the vulnerability is unregistered (WS), a link is provided to its description in an alternative open source vulnerability resource.

The Top Fix column lists the top-rated solution 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.

 

Section 3: License Risks and Compliance

A summary of open source components’ license types.

The License Distribution table lists the license types associated with detected open source components and provides links to the licenses’ official descriptions. A risk level is given for each license type, as well as the license type’s total number of occurrences.

The License Risk Distribution histogram breaks down the number of licenses by their risk level. Unknown risk level only means the license risk was not analyzed by WhiteSource legal experts.

 

Section 4: Outdated Libraries

A table listing libraries that have not been updated to their newest available versions.

The Library column lists the name of the outdated library.

The Versions column lists the version number and release date of the outdated library, the library’s most up-to-date version number and release date, and the number of versions that have been released in between.

The Recommendations column lists the course of action recommended by WhiteSource and a link to the library’s homepage.

 

Section 5: Inventory

An inventory of all open source components detected.

The Library column shows the name of the open source library and a link to its homepage or direct download.

The Licenses column lists licenses detected for each library, and links to their official license descriptions. The reference site that identifies the library’s license type is also linked to or described.

 

Upgrading to the Full WhiteSource Platform

We hope you enjoy using WhiteSource Bolt, a lightweight product integrated with Azure DevOps Services/TFS. For even greater control over your open source components, consider upgrading to our full WhiteSource platform.

Feel free to reach out to us to learn more about the platform’s expanded functionality and our simple upgrade process.