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/1.4.

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 Mend - This is not really part of the basic integration, but some customers want the plugins to change the status of an alert in Mend 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 mend, 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.

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.
fromDateTime	A string representing the beginning of the requested period of time, formatted as yyyy/mm/dd-hh:mm	String	Yes
toDateTime	A string representing the end of the requested period of time, formated as yyyy/mm/dd-hh:mm	String	Yes
userKey	The ID which uniquely identifies the user in Mend.	String	Yes

The query parameters fromDateTime and toDateTime must be used together to define a specific period of time. If not, the response may contain all issues created until the present time.

Request Example

CODE

{
    "requestType": "fetchProjectPolicyIssues",   
    "projectToken": "put_you_project_token_here",
    "policyActionType": "CREATE_ISSUE",
    "fromDateTime": "2022-01-15-00:00",
    "toDateTime": "2022-06-30-23:59",
    "userKey": "put_your_user_key_here"
}

Response Example

CODE

{
    "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 the exact changes that were made to each modified project, 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 Mend.	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" “ALERTS”	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

CODE

{  
   "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

CODE

{
    "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.

getProjectLibrariesInfo

Description

This API returns a list of libraries in a given project. It can be used in conjunction with fetchProjectPolicyIssues, which is further refined with getOrganizationLastModifiedProjects, to find the libraries in a recently modified project. The libraries are then passed in the API request, and if a library is no longer in the inventory or the policy issue no longer applies, then the library will not appear in the response. This provides an indication to resolve, archive or otherwise close the associated isse.

Query Parameters

Parameter	Description	Type	Required
requestType	The name of the API request: getProjectLibrariesInfo	string	Yes
projectToken	API Key which is a unique identifier of a project.	string	Yes
userKey	The ID which uniquely identifies the user in Mend.	string	Yes
keyUuids	An array of library UUIDs	string	Yes

Request Example

CODE

{
  "requestType": "getProjectLibrariesInfo",
  "projectToken": "8eb2b8225189411386e28adbcdf064cb3e02812f76174e1fb8a19b2febe9ccd9",
  "userKey": "ae3b9bff071f46b5a55c8571d54892b0099e767243684338b206f067bda2e231",
  "keyUuids": ["9fc3c814-f194-4c32-9949-417f33a05527", "keyUuid_2"]
}

Response Example

CODE

{
    "libraries": [
        {
            "keyUuid": "68aed19c-66e6-46d8-9245-23d85fae410e",
            "keyId": 35254325,
            "filename": "akka-stream_2.12-2.5.14.jar",
            "type": "MAVEN_ARTIFACT",
            "coordinates": "com.typesafe.akka:akka-stream_2.12:2.5.14",
            "sha1": "981f769626486d30a1153299982cde2bd2c6035d",
            "name": "akka-stream",
            "artifactId": "akka-stream_2.12",
            "version": "2.5.14",
            "groupId": "com.typesafe.akka",
            "architecture": "",
            "languageVersion": ""
        }
    ]
}

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 Mend.	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 Mend 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 Mend application interfaces can expose this parameter to allow users to access the issue from mend. `status` - The status of the issue in the Issue Tracker. The Mend 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

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

CODE

{
   "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

CODE

{
    "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 Mend.	String	Yes
integrationType	Possible values: issueTrackerIntegration, azureDevOps	String	Yes

Request Example

CODE

{
   "requestType": "getIntegrationActivationToken",
   "orgToken": "org_token",
   "userKey": "user_key",
   "integrationType": "issueTrackerIntegration" 
}

Response Example

CODE

{
    "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 Mend.	string	Yes
orgToken	API key which is a unique identifier of the organization.	string	Yes

Request Example

CODE

{
  "requestType": "getPolicyMatchesConfiguration",
  "orgToken": "org_token", // existing organization only
  "userKey": "user_key"    // member in the org
}

Response Example

CODE

{
    "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"
        }
    ]
}