Overview
WhiteSource provides the ability to integrate with issue tracking systems, in order to automatically create issues in those systems when a policy match occurs. As a result, issues automatically open in the issue tracking system and are automatically filled with the relevant WhiteSource information required to mitigate the risks triggering the creation of the issue.
This integration is implemented as a generic platform, exposed by external/public APIs, whereupon WhiteSource provides a set of out-of-the-box plugins for specific common Issue tracking systems. The triggering for the issues' creation occurs when a policy of the type “Issue” is matched with a library. This occurs no matter which plugins you are using.
NOTE: If you have already defined a previous integration of WhiteSource with an issue tracking system, and created policies to trigger issues creation, it can continue working “side by side” with the new integration until the “old” one will be deprecated. Ensure you define new policies for the new integration. To view the documentation for the legacy issue tracker integration, click here.
A plugin can be created by any customer with access to the API. For details, see Creating Your Own Issue Tracker Plugin.
Jira Data Center and Server Plugin
Overview
The Jira Data Center and Server Plugin supports the integration with the Jira Server and Jira Data Center solutions.
Prerequisites
To configure the integration, ensure the following:
Jira Data Center or Server versions from 8.0 to 8.22
Admin permissions to Jira
Admin permissions to WhiteSource
How the Jira Data Center and Server Plugin Work
The Jira Data Center and Server Plugin integration works in the following way:
The Jira Data Center and Server Plugin periodically queries the WhiteSource application for “Issue” Policy matches. These matches represent Issues the plugin should create in Jira.
A corresponding WhiteSource Issue (of type WS_Issue) is created in Jira for each match with all the relevant information in dedicated fields that can be sorted and filtered. For details, see WhiteSource Issue Information.
The WhiteSource Issue will be created based on the default issue type schema defined for each mapped Jira project.The WhiteSource Issue is updated automatically following changes that occur on WhiteSource. If the policy no longer affects the relevant project or the library is no longer in the inventory of the project, a relevant comment is added to the WhiteSource Issue.
The WhiteSource application is updated following changes in the Issue statuses.
Installing and Configuring the Jira Data Center and Server Plugin
To install and configure the plugin, do as follows:
Log in to Jira with Admin permissions.
Navigate to Manage Apps in the JIRA ADMINISTRATION section.
Search for WhiteSource in the Atlassian Marketplace search box.
Find the WhiteSource Integration for Jira Server and click Install.
After the installation, you will be directed to the configuration page. (If not, in the User-Installed Apps list, navigate to the WhiteSource Jira Plugin and click Configure).
The Activate Your WhiteSource License screen is displayed. Enter the activation key (to generate an activation key, refer here) in the provided box, and click Next. In case you are using a proxy, press the Show Proxy Settings button to set it up.
NOTE: If the activation key cannot be verified, it might be expired or you might be experiencing connectivity issues. In either case, contact Support.The plugin mapping screen is displayed. Continue to Mapping the WhiteSource Projects to the Jira Projects.
Mapping the WhiteSource Projects to the Jira Projects
In the plugin mapping screen, you can define (or map) in which Jira projects the issues that will be created according to the relevant WhiteSource scope.
To map the WhiteSource projects to the Jira projects, do as follows:
Map the WhiteSource projects to the Jira projects in which the issues will be created, according to the WhiteSource scope and the match type.
In WS Product, select the product.
In WS Project, select one or more projects, or select Select All.
In WS Policy Match, create a mapping of all relevant policy matches for the project (for example, By License Group, Security Vulnerability Severity, etc.), or Select All.
In Jira Project, select the relevant Jira projects for your mapping.
Select a default Jira project in which Issues without a specific mapping will be created. This is a mandatory setting; if no other mapping is done, all Issues will be created in the default Jira ticket board.
Click Save.
Proceed to Creating a Policy to Trigger Issues in order to trigger Issue creation.
Jira Cloud Plugin
Overview
The Jira Cloud Plugin supports the integration with the Jira Cloud solution.
Prerequisites
To configure the integration, the following is required:
Admin permissions to Jira
Admin permissions to WhiteSource
How the Jira Cloud Plugin Works
The Jira Cloud Plugin integration works in the following way:
The Jira plugin periodically queries the WhiteSource application for “Issue” Policy matches. These matches represent Issues the plugin should create in Jira.
A corresponding WhiteSource Issue (of type WS Issue) is created in Jira for each match with all the relevant information in dedicated fields that can be sorted and filtered. For details, see WhiteSource Issue Information.
The WhiteSource Issue will be created based on the default issue type schema defined for each mapped Jira project.The WhiteSource Issue is updated automatically following changes that occur on WhiteSource. If the policy no longer affects the relevant project or the library is no longer in the inventory of the project, a relevant comment is added to the WhiteSource Issue.
The WhiteSource application is updated following changes in the Issue statuses.
Installing and Configuring the Jira Cloud Plugin
To install and configure the plugin, do as follows:
Log into Jira with Admin permissions.
Navigate to Find new apps in the Apps section.
Search for WhiteSource in the search box.
Find the WhiteSource Integration for Jira Cloud and click Install.
Navigate to the WhiteSource plugin in the Apps section, after the installation is completed.
6. The Activate Your WhiteSource License screen is displayed. Enter the activation key (to generate an activation key, refer here) in the provided box, and click Next.
NOTE: If the activation key cannot be verified, it might be expired or you might be experiencing connectivity issues, contact Support.
7. The plugin mapping screen is displayed. Continue to Mapping the WhiteSource Projects to the Jira Projects.
Mapping the WhiteSource Projects to the Jira Projects
Only Jira company-managed projects are supported by the plugin.
In the plugin mapping screen, you can define (or map) in which Jira projects the issues that will be created according to the relevant WhiteSource scope.
To map the WhiteSource projects to the Jira projects, do as follows:
Map the WhiteSource projects to the Jira projects in which the issues will be created, according to the WhiteSource scope and the match type.
In WS Product, select the product.
In WS Project, select one or more projects, or select All.
In WS Policy Match, create a mapping of all relevant policy matches for the project (for example, By License Group, Security Vulnerability Severity, etc.), or select All.
In Jira Project, select the relevant Jira projects for your mapping.
Select a default Jira project in which Issues without a specific mapping will be created. This is a mandatory setting; if no other mapping is done, all Issues will be created in the default Jira ticket board.
Click Save.
Proceed to Creating a Policy to Trigger Issues in order to trigger Issue creation.
WhiteSource Issue Information
The WhiteSource Issue (WS Issue type) tickets hold all the relevant information that is created by the plugin in dedicated fields.
In order to provide as much information as possible in the Jira issue regarding the library's risks and how to mitigate them, library aggregated data is also provided to help you to easily filter and sort the Jira issues, and create a prioritized backlog for mitigating the risks found by WhiteSource.
Following are the dedicated WhiteSource fields that are created by the Jira plugins:
WS-Library: Name and link of the library that was matched to the policy.
WS-LibraryHierarchy: The hierarchical level of the library which indicates whether the library is a direct or a transitive dependency.
WS-PolicyName: Name of the policy that is matched with the library.
WS-PolicyScope: Level of scope to which the policy applies - organization, product or project.
WS-PolicyMatchType: Name of the policy match type (for example, License Group).
WS-PolicyMatchValue: Value of the policy match type (if relevant).
WS-Project: Project to which the library belongs.
WS-Product: Product to which the library belongs.
WS-Organization: Organization to which the library belongs.
WS-NumOfHighSevVuls: Count of the vulnerabilities with high severity found for the library.
WS-NumOfMedSevVuls: Count of the vulnerabilities with medium severity found for the library.
WS-NumOfLowSevVuls: Count of the vulnerabilities with low severity found for the library.
WS-IsAffectedByVuls: A boolean value indicating whether at least one of the vulnerabilities found for the library is traced as effective by Prioritize.
WS-MaxVul_CVSS_Score: CVSS score of the vulnerability that has the highest score of all the vulnerabilities found for the library. Using CVSS score rather than severity will help you to estimate how risky is the library.
In addition to all the relevant data, the ticket description contains the following information:
Library Path: Path to the location of the library in the system.
Dependency Hierarchy: The library’s hierarchical path. Note that the library is limited to 3 hierarchical paths.
Security Vulnerabilities: Links to the security vulnerabilities with their corresponding Prioritize shields when relevant.
Creating a Policy to Trigger Issues
Create a policy to trigger issues by doing the following:
Open the Policies page.
You can create a policy on any level but it must correspond to the mapping.Click Add Policy.
Create the policy as required. In Action, select Issue.
In Issue Settings, in Tracker Type, select Issue Tracker Plugin.
Click Add to revert to the Policies page showing the Issue policy created in WhiteSource.
When a policy is matched with a library (as a result of a scan or when applying policy changes to existing inventory), an issue creation is triggered in the WhiteSource application. The plugins periodically (once an hour) fetch this information and create the corresponding issues in Jira.
Ignoring WhiteSource Alerts
The Jira Plugins support an option to ignore WhiteSource alerts following the completion of the corresponding WhiteSource issue. The status of the WhiteSource risk will be set to IGNORED when the Jira ticket is moved to a status category “DONE”/”COMPLETE”.
To enable this feature, do the following:
In the Plugin configuration page, click Show Advanced Settings.
Click Ignore alerts based on tickets completion.
If you don’t want to ignore alerts for issues that are closed:
Deselect Ignore alerts based on tickets completion.
Limitations
Each Jira Plugin can be connected to a single WhiteSource organization.
The Jira projects used by the integration should not include mandatory fields; if they do, the WhiteSource Issue should be set to exclude them. For instructions on how to exclude mandatory fields in a Jira Cloud configuration to enable the WhiteSource integration to open tickets, see Excluding Mandatory Fields for WhiteSource Integration .
It is not recommended to change the issue type of the WhiteSource Issue after its creation. In order to keep WhiteSource and Jira in sync, the following fields should be maintained:
WS-Project_Token,Library_UUID,Policy_Id.WhiteSource Issues created by Jira Plugins should not be deleted, as this will cause WhiteSource and Jira to go out of sync.
Appendix: Generating an Activation Key
To generate an activation key, do as follows:
This procedure enables you to create a token with which to validate the Jira integration.
In the WhiteSource application, click Admin. The Organization Administration screen is displayed.
In the Integration area, click Issue Tracker Settings. The Issue Tracker Settings screen is displayed.
In the Issue Tracker Plugin section, click Generate Activation Key. Copy the key for later use.