Creating Your Own Issue Tracker Plugin

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:

  1. Defining a policy of type “Issue” that is meant for integrating with an issue tracking system.

  2. Fetching the items that were matched with this policy, along with all the relevant data.

  3. Identifying relevant changes in the system that might require updating the issues opened in the issue tracking system. 

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

  1. This set of API calls allows defining new policies in the scopes of global organization, organization, product and project. 

  2. To define policies which are relevant to the issue tracker integration, the policy action type should be CREATE_ISSUE. 

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

1 2 3 4 5 6 7 8 { "requestType": "fetchProjectPolicyIssues", "projectToken": "put_you_project_token_here", "policyActionType": "CREATE_ISSUE", "page": 1, "pageSize": 100, "userKey": "put_your_user_key_here" }

Response Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 { "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

1 2 3 4 5 6 7 8 9 10 11 { "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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "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

  1. This API allows the plugins (=”external integrations”) to update the WS application regarding the issues that were opened in the issue tracking system. 

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

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: 

  • identifier - The unique identifier of the issue in the issue tracking system. The WhiteSource application interfaces can expose this parameter to indicate to the users that the issue was opened.

  • url - The url which allows the users to access the issue. The WhiteSource application interfaces can expose this parameter to allow users to access the issue from WhiteSource.

  • status - The status of the issue in the Issue Tracker. The WhiteSource application interfaces can expose this parameter to indicate the current issue state to the users, and to follow up on changes to it.

  • created - The date and time in which the issue was created, in the format: YYYY-MM-DD HH:mm:ss

  • lastModified - The date and time in which the the issue was changed in the issue tracker (for example, its status was changed), in the format: YYYY-MM-DD HH:mm:ss

  • extraData - An optional array of strings that allows providing more data. Currently supports Jira dedicated fields, but can be used for other issue parameters as well.

    • issuePriority - A string to indicate the priority of the issue.

    • issueLabel - A string which acts as a label of the issue.

    • policyId - A string which is being used internally by the plugin to identify and communicate regarding future changes in the policy that triggered the issue’s creation.

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

  1. Every request field will be verified as required in the request comments below:

    1. Valid string field is 255 chars length limit

    2. Valid URL field is 2000 chars length limit

    3. Special chars are: <>%&

    4. date time can include timezone data +02:00

Request Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 { "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

1 2 3 4 5 { "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

1 2 3 4 5 6 {    "requestType": "getIntegrationActivationToken",    "orgToken": "org_token",    "userKey": "user_key",    "integrationType": "issueTrackerIntegration"  }

Response Example

1 2 3 {     "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

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

1 2 3 4 5 6 { "requestType": "getPolicyMatchesConfiguration", "orgToken": "org_token", // existing organization only "userKey": "user_key" // member in the org }

Response Example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 { "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" } ] }