Overview
This document describes the application public API calls that allow users to implement integrations with external issue tracking systems.
NOTE: All of these are API v1.3.
This set of APIs provides the following functionality:
Defining a policy of type “Issue” that is meant for integrating with an issue tracking system.
Fetching the items that were matched with this policy, along with all the relevant data.
Identifying relevant changes in the system that might require updating the issues opened in the issue tracking system.
Updating the application when issues are created in the issue tracking system by the plugin, or changed (“listening” to the changes is done by the plugin, and each plugin defines when it updates the application).
NOTE: Setting the status of an alert in WhiteSource - This is not really part of the basic integration, but some customers want the plugins to change the status of an alert in WhiteSource according to the Issue’s status (for example, if a Jira ticket is moved to “DONE”, to automatically ignore the alert). The recommended behavior for them is to rescan their projects, and then the alert will automatically be resolved, but for customers who don’t scan too often, doing this by the plugin might be valuable. For API details on setting the status of an alert in WhiteSource, see here.
API Specification
addPolicy
This set of API calls allows defining new policies in the scopes of global organization, organization, product and project.
To define policies which are relevant to the issue tracker integration, the policy action type should be CREATE_ISSUE.
You can find the full description of the AddPolicy calls here https://whitesource.atlassian.net/wiki/spaces/WD/pages/1522630711/Policies+API#Add-Policies
fetchProjectPolicyIssues
Description
This API returns the details regarding libraries that were matched with an ISSUE type policy that is configured with the new Issue tracker settings, and so issues should be created for them by the plugins.
The response of the API includes details on the relevant scope that was queried (org, product and project), and the list of issues that the application identified should be opened by the plugins (“potential issues”). For each of these issue the response will include details on the library, the policy, and the match or matches between them.
Query Parameters
Parameter | Description | Type | Required |
requestType | The name of the API request that returns details on a project’s matches between libraries and “Issue” type policies: fetchProjectPolicyIssues | String | Yes |
projectToken | API Key which is a unique identifier of the project. | String | Yes |
policyActionType | The type of the “action” parameter of the policy. For example: CREATE_ISSUE | String | No Currently only “Create Issue” is supported. |
page | A number indicating the page within the list to be returned. | Integer | No |
pageSize | A number indicating the max number of results returned from a request. | Integer | No |
userKey | The ID which uniquely identifies the user in WhiteSource. | String | Yes |
Request Example
{
"requestType": "fetchProjectPolicyIssues",
"projectToken": "put_you_project_token_here",
"policyActionType": "CREATE_ISSUE",
"page": 1,
"pageSize": 100,
"userKey": "put_your_user_key_here"
}
Response Example
{
"organization": {
"domainName": "To Vul Based 1",
"orgToken": "org_token"
},
"product": {
"productName": "WST_468",
"productToken": "prod_token"
},
"project": {
"projectName": "WST_468",
"projectToken": "proj_token"
},
"issues": [
{
"policy": {
"policyMatch": {
"type": "LICENSE",
"value": "Apache 2.0, Apache 2.0 with Commons Clause"
},
"Url": "https://tware.com/Wss/WSS.html#!p;project=1461100;policy=03",
"id": 11203,
"name": "LicensePolicy",
"owner": {
"id": 14341,
"email": "talia.sela@whitesourcesoftware.com",
"name": "talia.sela"
},
"creationTime": "2021-01-26",
"priority": 1,
"filter": {
"type": "LICENSE",
"licenses": [
{
"id": 9,
"name": "Apache 2.0"
},
{
"id": 1604,
"name": "Apache 2.0 with Commons Clause"
}
],
"scoreFrom": 0.0,
"scoreTo": 0.0
},
"inclusive": false,
"action": {
"type": "CREATE_ISSUE",
"failPolicyCheck": false
},
"productLevel": false,
"enabled": true,
"policyContext": "PRODUCT"
},
"library": {
"keyUuid": "9fc3c814-f194-4c32-9949-417f33a05527",
"keyId": 11713443,
"filename": "spock-core-0.7-groovy-1.8.jar",
"type": "MAVEN_ARTIFACT",
"url": "https://stagi.w.com/Wss/WSS.html#!l;project=1461100;uuid=97",
"coordinates": "org.spockframework:spock-core:0.7-groovy-1.8",
"localPaths": [
"C:\\Users\\1\\2\\a\\so.-1.8.jar"
],
"sha1": "3a677d19e8d3acf3bd296c4023356256d55da5a3",
"name": "Spock Framework - Core Module",
"artifactId": "spock-core",
"version": "0.7-groovy-1.8",
"groupId": "org.spockframework",
"architecture": "",
"languageVersion": ""
},
"policyViolations": [
{
"issueUuid": "d9367135-7d7c-496f-ba32-a85b8d2df71a",
"status": "OPEN",
"violationType": "LICENSE",
"created": "2021-01-26",
"lastModified": "2021-01-26",
"license": {
"name": "Apache 2.0",
"spdxName": "Apache-2.0",
"url": "http://www.opensource.org/licenses/Apache-2.0",
"references": []
}
}
]
},
]
}
getOrganizationLastModifiedProjects
Description
This API provides an indication on which projects a modification was made in a given time range. The modification can be in different aspects: the project’s inventory, policies, metadata and more. You can query multiple modification aspects in one call.
After using this API, you can check for each of the modified projects the exact changes that were made, and update the issues that were opened if needed (for example, if the library or policy that their match triggered the creation of the issue are no longer relevant). If no changes were made at all, this API will save you querying each project for the specific details.
Query Parameters
Parameter | Description | Type | Required |
requestType | The name of the API request that returns the list of an organization’s projects that have been modified in the provided time range: getOrganizationLastModifiedProjects | string | Yes |
orgToken | API Key which is a unique identifier of the organization. | string | Yes |
userKey | The ID which uniquely identifies the user in WhiteSource. | string | Yes |
modificationTypes | The aspect in which you want to check if changes were made. | array of one or more of the following: "INVENTORY" "METADATA" "SCAN" "POLICY_MATCH" "SCAN_COMMENT" "SOURCE_FILE_MATCH" | No (if none is specified, all modification aspects will be queried). |
fromDateTime | Start of time range, in the format YYYY-MM-DD HH:mm:ss. | string | No |
toDateTime | End of time range, in the format YYYY-MM-DD HH:mm:ss. | string | No |
includeRequestToken | Whether or not to specify the token of this request in the response. By default, this value is false. | boolean | No |
Request Example
{
"requestType": "getOrganizationLastModifiedProjects",
"orgToken": "org_token",
"userKey": "user_key",
"modificationTypes": ["INVENTORY","POLICY_MATCH","METADATA""],
// Optional time rage fields:
"fromDateTime": "2020-07-23 00:49:27",
"toDateTime": "2020-08-23 00:49:27"
"includeRequestToken": "true"
}
Response Example
{
"lastModifiedProjects": [
{
"uuid": "uuid",
"apiToken": "proj1_token",
"modificationType": "INVENTORY",
"lastModified": "2021-03-14 13:08:27"
},
{
"uuid": "2d017b44-abec-452e-953b-1d4f90dcca0d",
"apiToken":"token",
"modificationType": "INVENTORY",
"lastModified": "2021-07-19 13:34:24"
}
],
"requestToken": "11111"
}
Note: For old projects without apiToken, the api will return the uuid string as the apiToken.
updateExternalIntegrationIssues
Description
This API allows the plugins (=”external integrations”) to update the WS application regarding the issues that were opened in the issue tracking system.
By using this API, the 2-way integration can be implemented - the application can present this info and provide the user indication in the UI/API regarding the issues that were opened.
Query Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
requestType | Name of the API request that allows external integrations to update the application in the details of the issue created in the issue trackers: updateExternalIntegrationIssues | String | Yes |
wsPolicyIssueItemUuid | A valid UUID of a policyMatch item. Can be retrieved from the fetchProjectPolicyIssues request, in the policyViolations items. | String | Yes |
projectToken | API Key which is a unique identifier of the project. | String | Yes |
userKey | The ID which uniquely identifies the user in WhiteSource. | String | Yes |
issueTrackerPluginType | The identifier of the Issue Tracker Type. | String (free text) | Currently only “JIRA“ is supported, and the field is not required. |
externalIssues | An array of objects, containing relevant information regarding the issues that were opened. Each issue is represented with an “item” object in the array, which can include the following fields:
| Objects Array
| Yes, The “identifier” field is required for each of the item objects, the rest of the fields are optional. |
includeRequestToken | Whether or not to specify the token of this request in the response. By default, this value is false. | boolean | No |
Request parameters validations
Every request field will be verified as required in the request comments below:
Valid string field is 255 chars length limit
Valid URL field is 2000 chars length limit
Special chars are: <>%&
date time can include timezone data +02:00
Request Example
{
"requestType": "updateExternalIntegrationIssues",
"projectToken": "proj_token",
"userKey": "user_key",
"wsPolicyIssueItemUuid": "123345",
"externalIssues":
[
{
"identifier": "WPM-1", //required, no special chars
"url": "org.jira.com/issues/wsa-1", // optional, no special chars
"status": "OPEN", // optional, no special chars
"created": "2020-12-23T10:00:00+02:00", // optional, valid datetime format
"lastModified": "2020-12-23T10:00:00+02:00", // optional, valid datetime format
"extraData": // optional, map of strings
{
"issuePriority": "MEDIUM", // valid length and no special chars
"issueLabel": "vulnerability", // valid length and no special chars
"policyId" : "14241"
}
},
{
"identifier": "WPM-2",
"url": "org.jira.com/issues/wsa-2"
},
{
"identifier": "WPM-3",
"url": "org.jira.com/issues/wsa-3"
},
{
"identifier": "WPM-4",
"url": "org.jira.com/issues/wsa-4",
"status": "DONE",
"created": "2020-12-23T10:00:00+02:00",
"lastModified": "2020-12-23T10:51:21+02:00",
"extraData":
{
"issuePriority": "MEDIUM",
"issueLabel": "vulnerability"
}
}
]
}
Response Example
{
"createdIssues": 3,
"updatedIssues": 0,
"unaffectedIssues": 1
}
getIntegrationActivationToken
Description
The API allows the plugins to create a token with which they can integrate with the WS application. During the token generation, a dedicated service user is created and the API queries that the plugin will perform with the token will be identified with this service user.
Query Parameters
Parameter | Description | Type | Required |
requestType | Name of the API request that generates an activation token to allow integrations to communicate with the organizations and perform API calls against it: getIntegrationActivationToken | String | Yes |
orgToken | API Key which is a unique identifier of the organization. | String | Yes |
userKey | The ID which uniquely identifies the user in WhiteSource. | String | Yes |
integrationType | Possible values: issueTrackerIntegration, azureDevOps | String | Yes |
Request Example
{
"requestType": "getIntegrationActivationToken",
"orgToken": "org_token",
"userKey": "user_key",
"integrationType": "issueTrackerIntegration"
}
Response Example
{
"activationToken": "AAAAAAAAA........."
}
getPolicyMatchesConfiguration
Description
Use this API to get all the supported matches for policy (“policy conditions”) if you want to support different configurations in your plugins according to specific policy matches. For example, in the Jira plugins, users can choose to open issues in different Jira projects, according to the match type (security issues in the security team’s Jira project, license issues in the legal team’s Jira project and so on). True, you can add this hard-coded to your plugin, but using this API will make sure you’re working with the one source of truth, so if the application adds more types or removed some, you’re always updated.
Query Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
requestType | The name of the API request that returns all the supported policy matches: getPolicyMatchesConfiguration | string | Yes |
userKey | The ID which uniquely identifies the user in WhiteSource. | string | Yes |
orgToken | API key which is a unique identifier of the organization. | string | Yes |
Request Example
{
"requestType": "getPolicyMatchesConfiguration",
"orgToken": "org_token", // existing organization only
"userKey": "user_key" // member in the org
}
|
Response Example
{
"matches": [
{
"type": "RESOURCE_NAME_REGEX",
"name": "Resource Name RegEx",
"description": "Match By Glob Pattern on Resource Name"
},
{
"type": "LIBRARY_REQUEST_HISTORY",
"name": "Library Request History",
"description": "Match By Library Request History"
},
{
"type": "PRIMARY_ATTRIBUTE_VALUE",
"name": "Primary Attribute Value",
"description": "Match By Primary Attribute Value"
},
{
"type": "EFFECTIVENESS",
"name": "Vulnerability Effectiveness",
"description": "Match By Vulnerability Effectiveness"
},
{
"type": "VULNERABILITY_SEVERITY",
"name": "Vulnerability Severity",
"description": "Match By Security Vulnerability Severity"
},
{
"type": "PRODUCT",
"name": "Product",
"description": "Match If Exists in Product's Inventory"
},
{
"type": "LICENSE",
"name": "License Group",
"description": "Match By License Group"
},
{
"type": "VULNERABILITY_SCORE",
"name": "Vulnerability Score",
"description": "Match By Security Vulnerability Score (CVSS 3)"
},
{
"type": "LIBRARY_STALENESS",
"name": "Library Age",
"description": "Match By Library Age"
},
{
"type": "GAV_REGEX",
"name": "GAV RegEx",
"description": "Match By Glob Pattern on GAV Custom Attributes"
}
]
}
|