Alerts API

Overview

This resource represents alerts. The WhiteSource application uses alerts to notify users of security vulnerabilities, licensing and compatibility issues, or policy violations, in their open-source code. Alerts can apply in a whole organization, a specific product, or a specific project.

Alerts can have one of three statuses:

  • Active - Alerts that are in active state appear in the dashboards and reports. This is the default status.

  • Ignored - Alerts marked as ignored will not appear in dashboards and reports. You can reactivate ignored alerts, whereby they will revert to active state and be restored in the application and re-appear in dashboards and reports.

  • Resolved - Alerts that are no longer relevant will have the resolved status.

 Alerts can be of the following types:

Alert Type

Description

Alert Type

Description

SECURITY_VULNERABILITY

A security vulnerability was detected for a library in the inventory.

REJECTED_LIBRARY_IN_USE

A library is being used even though it was rejected.

POLICY_VIOLATION

A library that violates a policy is being used.

NEW_VERSION

A new version has been released for a library in the inventory.
NOTE: For New Version alert types, you can choose to display all version updates or only major version updates.

MULTIPLE_LIBRARY_VERSIONS

Multiple versions of the same library are being used.

MULTIPLE_LICENSES

More than one license was identified for a library.

This topic showcases the API requests and responses for:

  • getting security alerts by vulnerability report

  • getting security alerts by library report

  • getting all alerts for an organization, product or project

  • getting all alerts of a certain type for an organization, product or project

  • getting alerts by project tag (key & value) for an organization, product or project

  • getting ignored alerts for an organization, product or project

  • ignoring alerts for an organization, product or project

  • setting the of alerts for an organization, product or project

Vulnerability-Based Alerting

When Vulnerability-based Alerting is enabled (see Security Alerts: View By Vulnerability):

  1. The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

  2. A new parameter sourceFiles is added to the API response when there is a relationship between a CVE and a source file.

  3. Some additional fields are included in the responses for all scopes: Modified Date, Alert and Comment. These fields are not included when Library-based Alerting mode is enabled.

Get Security Alerts by Vulnerability Report

NOTE: The following APIs are only available for an organization in which vulnerability-based alerting mode is enabled. 

Generates security alerts report detailed by vulnerability, in the scope of the organization, a specific product or a specific project. 

The parameter allows filtering of specific alerts statuses ("Active", "Ignored", "Resolved") and by default is set to all statuses. 

For details of the structure of the security vulnerability alert object, see Security Vulnerability Object.

Organization

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a report of all the security alerts by vulnerability in an organization.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

orgToken

API key which is a unique identifier of the organization.

string

Yes

status

Current status of the alert(s): Active or Ignored.

string

Yes

format

Requested format of the report. Options are: xlsx (default), xml, or json.

string

Yes

Request Example

1 2 3 4 5 6 7 { "requestType" : "getOrganizationSecurityAlertsByVulnerabilityReport", "userKey": "user_key", "orgToken" : "organization_api_key", "status" : "active", "format" : "xlsx" }

Product

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a report of all the security alerts by vulnerability for a specific product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

status

Current status of the alert(s): Active or Ignored.

string

Yes

format

Requested format of the report. Options are: xlsx (default), xml, or json.

string

Yes

Request Example

1 2 3 4 5 6 7 { "requestType" : "getProductSecurityAlertsByVulnerabilityReport", "userKey": "user_key", "productToken" : "product_token", "status" : "ignored", "format" : "xlsx" }

Project

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a report of all the security alerts by vulnerability for a specific project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

format

Requested format of the report. Options are: xlsx (default), xml, or json.

string

Yes

Request Example

1 2 3 4 5 6 { "requestType" : "getProjectSecurityAlertsByVulnerabilityReport", "userKey": "user_key", "projectToken" : "project_token", "format" : "xlsx" }

Response Format

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>-alerts-report.xlsx

Back to top

Security Vulnerability Object

Security alerts will also contain the Vulnerability object:

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 "vulnerability": { "name": "vulnerability_name", "type": "vulnerability_type", "severity": "vulnerability_severity", "score": cvss_2_vulnerability_score, "cvss3_severity": "cvss_3_score_severity", "cvss3_score": cvss_3_vulnerability_score, "publishDate": "vulnerability_publish_date" "scoreMetadataVector": "cvss_3_metadata_vector", "url": "URL_of_vulnerability" "description": "vulnerability_description", "topFix": { "vulnerability": "vulnerability_fix_name", "type": "vulnerability_fix_type", "origin": "origin_of_fix", "url": "URL_of_fix", "fixResolution": "fix_resolution", "date": "date_of_fix", "message": "summary_of_fix", "extraData": "additional_data_on_fix" }, "allFixes": [{ "vulnerability": "vulnerability_fix_name", "type": "vulnerability_fix_type", "origin": "origin_of_fix", "url": "URL_of_fix", "fixResolution": "fix_resolution", "date": "date_of_fix", "message": "details_on_fix", "extraData": "additional_data" }] }

topFix & allFixes objects:

These objects are displayed only when a fix is available for the specific vulnerability.

The Vulnerability object has the following parameters:

Parameter

Value

Parameter

Value

name

ID in the vulnerability DB (CVE or WS)

type

CVE or WS

severity

Severity of the CVSS 2 vulnerability (low, medium, high)

score

CVSS 2 base score [0.0 - 10.0]

cvss3_severity

CVSS 3 score severity: 

  • 0-3.9 = Low 

  • 4-6.9 = Medium 

  • 7-10 = High

cvss3_score

CVSS 3 base score [0.0 - 10.0]

scoreMetadataVector

See specification link

publishDate

Original release date

url

URL of the CVE

description

Short description of the security vulnerability

topFix

Top recommended fix (when available)

allFixes

List of all fixes (when available)

fixResolutionText

The actual resolution text to display for the given fix

Get Security Alerts by Library Report

NOTE: The following APIs are only available for an organization in which vulnerability-based alerting mode is enabled. 

Generates security alerts report detailed by library, in the scope of the organization, a specific product or a specific project. 

The "status" parameter allows filtering of specific alerts statuses ("Active", "Ignored") and by default is set to all statuses. A library that is marked as "active" has at least 1 active alert. A library that is marked as "ignored" has at least 1 ignored alert. 

Organization

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a report of all the security alerts by library in an organization.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

orgToken

API key which is a unique identifier of the organization.

string

Yes

status

Current status of the alert(s): Active or Ignored.

string

Yes

format

Requested format of the report. Options are: xlsx (default), xml, or json.

string

Yes

Request Example

1 2 3 4 5 6 7 { "requestType" : "getOrganizationSecurityAlertsByLibraryReport", "userKey": "user_key", "orgToken" : "organization_api_key", "status" : "active", "format" : "xlsx" }

Product

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a report of all the security alerts by library for a specific product in an organization.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

status

Current status of the alert(s): Active or Ignored.

string

Yes

format

Requested format of the report. Options are: xlsx (default), xml, or json.

string

Yes

Request Example

1 2 3 4 5 6 7 { "requestType" : "getProductSecurityAlertsByLibraryReport", "userKey": "user_key", "productToken" : "product_token", "status" : "ignored", "format" : "xlsx" }

Project

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns a report of all the security alerts by library for a specific project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

format

Requested format of the report. Options are: xlsx (default), xml, or json.

string

Yes

Request Example

1 2 3 4 5 6 { "requestType" : "getProjectSecurityAlertsByLibraryReport", "userKey": "user_key", "projectToken" : "project_token", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>-alerts-report.xlsx

Back to top

Get Alerts

Organization

Get all alerts for a specific organization.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns all the alerts in an organization.

string

Yes

userKey

The ID of the user’s profile, 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 {     "requestType" : "getOrganizationAlerts",      "userKey": "user_key",     "orgToken" : "organization_api_key" }

Response Example

The response is a JSON collection of all the alerts in the organization with their details. For 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 { "alerts": [ { "type": "REJECTED_BY_POLICY_RESOURCE", "level": "MAJOR", "library": { "keyUuid": "3c0f701b-1315-43ed-b94b-a14447f46a4a", "keyId": 36637701, "filename": "ini-1.3.5.tgz", "type": "javascript/Node.js", "languages": "javascript/Node.js", "description": "An ini encoder/decoder for node", "references": { "url": "https://registry.npmjs.org/ini/-/ini-1.3.5.tgz", "homePage": "https://github.com/isaacs/ini#readme", "genericPackageIndex": "https://www.npmjs.org/package/ini" }, "sha1": "eee25f56db1c9ec6085e0c22778083f596abf927", "name": "ini", "artifactId": "ini-1.3.5.tgz", "version": "1.3.5", "groupId": "ini", "licenses": [ { "name": "ISC", "spdxName": "ISC", "url": "http://www.opensource.org/licenses/ISC", "profileInfo": { "copyrightRiskScore": "THREE", "patentRiskScore": "THREE", "copyleft": "NO", "linking": "NON_VIRAL", "royaltyFree": "NO" }, ...........

Back to top

Product

Get all alerts for a specific product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns all the alerts for a product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

Request Example

1 2 3 4 5 {     "requestType" : "getProductAlerts",     "userKey": "user_key",     "productToken" : "product_token" }

Response Example

The response is a JSON collection of all the alerts in the product with their details. For 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 { "alerts": [ { "type": "REJECTED_BY_POLICY_RESOURCE", "level": "MAJOR", "library": { "keyUuid": "c147bc0a-41f9-4867-b056-b4fc8a7dbac4", "keyId": 66142625, "filename": "Pillow-5.2.0.tar.gz", "type": "Python", "languages": "Python", "description": "Python Imaging Library (Fork)", "references": { "url": "https://files.pythonhosted.org/packages/d3/c4/b45b9c0d549f482dd072055e2d3ced88f3b977f7b87c7a990228b20e7da1/Pillow-5.2.0.tar.gz", "homePage": "https://python-pillow.org", "genericPackageIndex": "https://pypi.python.org/pypi/Pillow/5.2.0" }, "sha1": "7d0f97e23425418f2e4c9ee51fc3bcb9ee71ec60", "name": "Pillow", "artifactId": "Pillow-5.2.0.tar.gz", "version": "5.2.0", "groupId": "Pillow", "licenses": [ { "name": "PIL Software License", "url": "http://www.pythonware.com/products/pil/license.htm", "references": [ { "referenceType": "Project home page", "reference": "https://github.com/python-pillow/Pillow/blob/master/LICENSE" } ] } ] ...........

Back to top

Project

Get all alerts for a specific project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns all the alerts for a project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

Request Example

1 2 3 4 5 {     "requestType" : "getProjectAlerts",     "userKey": "user_key",     "projectToken" : "project_token" }

Response Example

The response is a JSON collection of all the alerts in the project with their details. For 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 { "alerts": [ { "type": "REJECTED_BY_POLICY_RESOURCE", "level": "MAJOR", "library": { "keyUuid": "5f612fe4-4735-4334-bba2-f68da42714c5", "keyId": 86429547, "filename": "lodash-4.17.15.tgz", "type": "javascript/Node.js", "languages": "javascript/Node.js", "description": "Lodash modular utilities.", "references": { "url": "https://registry.npmjs.org/lodash/-/lodash-4.17.15.tgz", "homePage": "https://lodash.com/", "genericPackageIndex": "https://www.npmjs.org/package/lodash" }, "sha1": "b447f6670a0455bbfeedd11392eff330ea097548", "name": "lodash", "artifactId": "lodash-4.17.15.tgz", "version": "4.17.15", "groupId": "lodash", "licenses": [ { "name": "MIT", "spdxName": "MIT", "url": "http://www.opensource.org/licenses/MIT", "profileInfo": { "copyrightRiskScore": "THREE", "patentRiskScore": "ONE", "copyleft": "NO", "royaltyFree": "YES" }, { "referenceType": "NPM (details available in Node Package Manager)", "reference": "https://github.com/lodash/lodash/blob/4.17.15/package.json" } ] } ] "type": "SECURITY_VULNERABILITY", "level": "MAJOR", "library": { "keyUuid": "811031a9-bfee-44c0-bd1f-1aec280d4bed", "keyId": 100088875, "filename": "axios-0.19.2.tgz", "type": "javascript/Node.js", "languages": "javascript/Node.js", "description": "Promise based HTTP client for the browser and node.js", "references": { "url": "https://registry.npmjs.org/axios/-/axios-0.19.2.tgz", "homePage": "https://github.com/axios/axios", "genericPackageIndex": "https://www.npmjs.org/package/axios" ] } ] }, ...........

Back to top

Get Alerts by Project Tag

Project tags are key value pairs that provide additional metadata for projects, enabling users to label and search for their products or projects according to predefined categories (such as, development, production).

This API request allows you to get alerts in your project that have a specific tag or label.

Important Notes about this API

When Vulnerability-based Alerting is enabled (see Security Alerts: View By Vulnerability):

  1. The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

  2. A new parameter sourceFiles is added to the API response when there is a relationship between a CVE and a source file.

  3. Some additional fields are included in the responses for all scopes: Modified Date, Alert and Comment. These fields are not included when Library-based Alerting mode is enabled.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns all alerts in the organization that have a specific project tag.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

orgToken

API key which is a unique identifier of the organization.

string

Yes

tagKey

Label that describes the tag.

string

Yes

tagValue

Value assigned to the tag.

string

Yes

Request Example

1 2 3 4 5 6 7 {     "requestType": "getAlertsByProjectTag",     "orgToken": "organization_api_key",     "userKey": "user_key",     "tagKey": "status",     "tagValue": "production"    }

Response Example

The response is a JSON collection of all the alerts in the organization with the specified project tag. For 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 {     "apiAlertInfo": [         {             "vulnerability": {                 "name": "CVE-2020-10673",                 "type": "CVE",                 "severity": "medium",                 "score": 6.8,                 "cvss3_severity": "high",                 "cvss3_score": 8.8,                 "scoreMetadataVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H",                 "publishDate": "2020-03-18",                 "url": "https://vuln.whitesourcesoftware.com/vulnerability/CVE-2020-10673",                 "description": "FasterXML jackson-databind 2.x before 2.9.10.4 mishandles the interaction between serialization gadgets and typing, related to com.caucho.config.types.ResourceRef (aka caucho-quercus).",                 "topFix": {                     "vulnerability": "CVE-2020-10673",                     "type": "UPGRADE_VERSION",                     "origin": "WHITESOURCE_EXPERT",                     "url": "https://github.com/FasterXML/jackson-databind/issues/2660",                     "fixResolution": "com.fasterxml.jackson.core:jackson-databind:2.9.10.4",                     "date": "2020-03-18",                     "message": "Upgrade to version"                 },                 "allFixes": [                     {                         "vulnerability": "CVE-2020-10673",                         "type": "UPGRADE_VERSION",                         "origin": "WHITESOURCE_EXPERT",                         "url": "https://github.com/FasterXML/jackson-databind/issues/2660",                         "fixResolution": "com.fasterxml.jackson.core:jackson-databind:2.9.10.4",                         "date": "2020-03-18",                         "message": "Upgrade to version"                     },                                                      ]             ........      

Back to top

Get Ignored Alerts

Get a list of ignored alerts per scope (organization, product, or project).

Important Notes about this API

When Vulnerability-based Alerting is enabled (see Security Alerts: View By Vulnerability):

  1. The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

  2. A new parameter sourceFiles is added to the API response when there is a relationship between a CVE and a source file.

  3. Some additional fields are included in the responses for all scopes: Modified Date, Alert and Comment. These fields are not included when Library-based Alerting mode is enabled.

Organization

Get all ignored alerts for a specific organization.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns all the ignored alerts in an organization.

string

Yes

userKey

The ID of the user’s profile, 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 {     "requestType" : "getOrganizationIgnoredAlerts",     "userKey":"user_key",     "orgToken":"organization_api_key"  }

Response Example

The response is a JSON collection of the ignored alerts in the organization with their details. For 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 {     "alerts": [         {             "vulnerability": {                 "name": "WS-2019-0379",                 "type": "WS",                 "severity": "medium",                 "score": 6.5,                 "cvss3_severity": "medium",                 "cvss3_score": 6.5,                 "scoreMetadataVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N",                 "publishDate": "2019-05-20",                 "url": "https://github.com/apache/commons-codec/commit/48b615756d1d770091ea3322eefc08011ee8b113",                 "description": "Apache commons-codec before version “commons-codec-1.13-RC1” is vulnerable to information disclosure due to Improper Input validation.",                 "topFix": {                     "vulnerability": "WS-2019-0379",                     "type": "UPGRADE_VERSION",                     "origin": "WHITESOURCE_EXPERT",                     "url": "https://github.com/apache/commons-codec/commit/48b615756d1d770091ea3322eefc08011ee8b113",                     "fixResolution": "1.13-RC1",                     "date": "2019-05-12",                     "message": "Upgrade to version"                 },                 "allFixes": [],                 "fixResolutionText": "Upgrade to version 1.13-RC1",                 "references": []             },              ...........                              

Back to top

Product

Get all ignored alerts for a specific product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns all the ignored alerts for a product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

Request Example

1 2 3 4 5 {     "requestType" : "getProductIgnoredAlerts",     "userKey": "user_key",     "productToken" : "product_token" }

Response Example

The response is a JSON collection of the ignored alerts in the product with their details. For 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 {     "alerts": [         {             "vulnerability": {                 "name": "CVE-2018-10237",                 "type": "CVE",                 "severity": "medium",                 "score": 4.3,                 "cvss3_severity": "medium",                 "cvss3_score": 5.9,                 "scoreMetadataVector": "CVSS:3.0/AV:N/AC:H/PR:N/UI:N/S:U/C:N/I:N/A:H",                 "publishDate": "2018-04-26",                 "url": "https://vuln.whitesourcesoftware.com/vulnerability/CVE-2018-10237",                 "description": "Unbounded memory allocation in Google Guava 11.0 through 24.x before 24.1.1 allows remote attackers to conduct denial of service attacks against servers that depend on this library and deserialize attacker-provided data, because the AtomicDoubleArray class (when serialized with Java serialization) and the CompoundOrdering class (when serialized with GWT serialization) perform eager allocation without appropriate checks on what a client has sent and whether the data size is reasonable.",                 "topFix": {                     "vulnerability": "CVE-2018-10237",                     "type": "UPGRADE_VERSION",                     "origin": "WHITESOURCE_EXPERT",                     "url": "https://nvd.nist.gov/vuln/detail/CVE-2018-10237",                     "fixResolution": "24.1.1-jre, 24.1.1-android",                     "date": "2018-04-26",                     "message": "Upgrade to version"                 },                 "allFixes": [                     {                         "vulnerability": "CVE-2018-10237",                         "type": "UPGRADE_VERSION",                         "origin": "WHITESOURCE_EXPERT",                         "url": "https://nvd.nist.gov/vuln/detail/CVE-2018-10237",                         "fixResolution": "24.1.1-jre, 24.1.1-android",                         "date": "2018-04-26",                         "message": "Upgrade to version"                     },                     {                         "vulnerability": "CVE-2018-10237",                         "type": "UPGRADE_VERSION",                         "origin": "SECURITY_TRACKER",                         "url": "http://www.securitytracker.com/id/1041707",                         "fixResolution": "Red Hat has issued a fix.\n\nThe Red Hat advisory is available at:\n\nhttps://access.redhat.com/errata/RHSA-2018:2740\nhttps://access.redhat.com/errata/RHSA-2018:2741\nhttps://access.redhat.com/errata/RHSA-2018:2742\nhttps://access.redhat.com/errata/RHSA-2018:2743",                         "message": "Red Hat JBoss EAP Component Errors Let Remote Users Deny Service and Remote Authenticated Users Gain Potentially Sensitive Information",                         "extraData": "key=1041707"                     },                     ...........                                       

Back to top

Project

Get all ignored alerts for a specific project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that returns all the ignored alerts for a project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

Request Example

1 2 3 4 5 {     "requestType" : "getProjectIgnoredAlerts",     "userKey": "user_key",     "projectToken" : "project_token" }

Response Example

The response is a JSON collection of the ignored alerts in the project with their details. For 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 {     "alerts": [         {             "vulnerability": {                 "name": "WS-2019-0379",                 "type": "WS",                 "severity": "medium",                 "score": 6.5,                 "cvss3_severity": "medium",                 "cvss3_score": 6.5,                 "scoreMetadataVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N",                 "publishDate": "2019-05-20",                 "url": "https://github.com/apache/commons-codec/commit/48b615756d1d770091ea3322eefc08011ee8b113",                 "description": "Apache commons-codec before version “commons-codec-1.13-RC1” is vulnerable to information disclosure due to Improper Input validation.",                 "topFix": {                     "vulnerability": "WS-2019-0379",                     "type": "UPGRADE_VERSION",                     "origin": "WHITESOURCE_EXPERT",                     "url": "https://github.com/apache/commons-codec/commit/48b615756d1d770091ea3322eefc08011ee8b113",                     "fixResolution": "1.13-RC1",                     "date": "2019-05-12",                     "message": "Upgrade to version"                 },                 "allFixes": [],                 "fixResolutionText": "Upgrade to version 1.13-RC1",                 "references": []             },             "type": "SECURITY_VULNERABILITY",             "level": "MAJOR",             "library": {                 "keyUuid": "83cf3655-de66-411b-ba19-fdf2d3cc2067",                 "keyId": 111269430,                 "filename": "commons-codec-1.9.jar",                 "type": "Java",                 "description": "The Apache Commons Codec package contains simple encoder and decoders for\n     various formats such as Base64 and Hexadecimal.  In addition to these\n     widely used encoders and decoders, the codec package also maintains a\n     collection of phonetic encoding utilities.",                 "references": {                     "pomUrl": "https://repo.maven.apache.org/maven2/commons-codec/commons-codec/1.9/commons-codec-1.9.pom"                 },                 ...........

Back to top

Get Alerts by Type

Get all alerts of a certain type for a given organization, a specific product, or specific project, according to your role permissions.

Important Notes about this API

When Vulnerability-based Alerting is enabled (see Security Alerts: View By Vulnerability):

  1. The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

  2. A new parameter sourceFiles is added to the API response when there is a relationship between a CVE and a source file.

  3. Some additional fields are included in the responses for all scopes: Modified Date, Alert and Comment. These fields are not included when Library-based Alerting mode is enabled.

Organization

Get alerts of a certain type for a given organization.

QUERY PARAMETERS

Parameter

Description

Type

Required

Default/Values

Parameter

Description

Type

Required

Default/Values

requestType

API request type that returns all the alerts in an organization according to the specified alert type.

string

Yes

 

orgToken

API key which is a unique identifier of the organization.

string

Yes

 

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

 

alertType

The type of alerts.

For a detailed description of alert types, see Alert Types.

string

Yes

Permitted values:

  • SECURITY_VULNERABILITY

  • REJECTED_LIBRARY_IN_USE

  • POLICY_VIOLATION

  • NEW_VERSION

  • MULTIPLE_LIBRARY_VERSIONS

  • MULTIPLE_LICENSES

fromDate

The first date in the time period during which the alerts were created or modified. When fromDate is not specified, the beginning of time will be assumed.

string

No

Time is GMT. Format is:
YYYY-MM-DD or YYYY-MM-DD HH-MM-SS (if time is also specified).

toDate

The last date in the time period during which the alerts were created or modified. When toDate is not specified, the current date and time will be assumed.

 

string

No

Time is GMT. Format is:
YYYY-MM-DD or YYYY-MM-DD HH-MM-SS (if time is also specified).

Request Example

1 2 3 4 5 6 7 {     "requestType": "getOrganizationAlertsByType",     "userKey": "user_key",     "alertType": "alert_type",     "orgToken": "organization_api_key",     "fromDate": "2020-09-01" }

Response Example

A JSON collection listing the alerts of the specified type that were generated in the specified scope (organization, product, or project) and within the specified date range:

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 {     "alerts": [         {             "vulnerability": {                 "name": "CVE-2020-28168",                 "type": "CVE",                 "severity": "medium",                 "score": 4.3,                 "cvss3_severity": "medium",                 "cvss3_score": 5.9,                 "scoreMetadataVector": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:N/A:N",                 "publishDate": "2020-11-06",                 "url": "https://vuln.whitesourcesoftware.com/vulnerability/CVE-2020-28168",                 "description": "Axios NPM package 0.21.0 contains a Server-Side Request Forgery (SSRF) vulnerability where an attacker is able to bypass a proxy by providing a URL that responds with a redirect to a restricted host or IP address.",                 "allFixes": [],                 "references": []             },             "type": "SECURITY_VULNERABILITY",             "level": "MAJOR",             "library": {                 "keyUuid": "811031a9-bfee-44c0-bd1f-1aec280d4bed",                 "keyId": 100088875,                 "filename": "axios-0.19.2.tgz",                 "type": "javascript/Node.js",                 "languages": "javascript/Node.js",                 "description": "Promise based HTTP client for the browser and node.js",                 "references": {                     "url": "https://registry.npmjs.org/axios/-/axios-0.19.2.tgz",                     "homePage": "https://github.com/axios/axios",                     "genericPackageIndex": "https://www.npmjs.org/package/axios"                 },                 "sha1": "3ea36c5d8818d0d5f8a8a97a6d36b86cdc00cb27",                 "name": "axios",                 "artifactId": "axios-0.19.2.tgz",                 "version": "0.19.2",                 "groupId": "axios",                 "licenses": [                     {                         "name": "MIT",                         "spdxName": "MIT",                         "url": "http://www.opensource.org/licenses/MIT",                         "profileInfo": {                             "copyrightRiskScore": "THREE",                             "patentRiskScore": "ONE",                             "copyleft": "NO",                             "royaltyFree": "YES"                         },           

Back to top

Product

Get alerts of a certain type for a given product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Default/Values

Parameter

Description

Type

Required

Default/Values

requestType

API request type that returns all the alerts generated for a product according to the specified alert type.

string

Yes

 

productToken

API key which is a unique identifier of the product.

string

Yes

 

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

 

alertType

The type of alert. For a detailed description, see Alert Types.

string

Yes

Permitted values:

  • SECURITY_VULNERABILITY

  • REJECTED_LIBRARY_IN_USE

  • POLICY_VIOLATION

  • NEW_VERSION

  • MULTIPLE_LIBRARY_VERSIONS

  • MULTIPLE_LICENSES

fromDate

The first date in the time period during which the alerts were created or modified. When fromDate is not specified, the beginning of time will be assumed.

string

No

Time is GMT. Format is:
YYYY-MM-DD or YYYY-MM-DD HH-MM-SS (if time is also specified).

toDate

The last date in the time period during which the alerts were created or modified. When toDate is not specified, the current date and time will be assumed.

string

No

Time is GMT. Format is:
YYYY-MM-DD or YYYY-MM-DD HH-MM-SS (if time is also specified).

Request Example

1 2 3 4 5 6 7 8 {     "requestType": "getProductAlertsByType",     "userKey": "user_key",     "alertType": "alert_type",     "productToken": "product_token",     "fromDate": "2020-09-01", "toDate": "2020-12-31" }

See Response Example for an example of a JSON response to the specified details in the above request example.

Back to top

Project

Get alerts of a certain type for a given project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Default/Values

Parameter

Description

Type

Required

Default/Values

requestType

API request type that returns all the alerts generated for a project according to the specified alert type.

string

Yes

 

projectToken

API key which is a unique identifier of the project.

string

Yes

 

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

 

alertType

The type of alert. For a detailed description, see Alert Types.

string

Yes

Permitted values:

  • SECURITY_VULNERABILITY

  • REJECTED_LIBRARY_IN_USE

  • POLICY_VIOLATION

  • NEW_VERSION

  • MULTIPLE_LIBRARY_VERSIONS

  • MULTIPLE_LICENSES

fromDate

The first date in the time period during which the alerts were created or modified. When fromDate is not specified, the beginning of time will be assumed.

string

No

Time is GMT. Format is:
YYYY-MM-DD or YYYY-MM-DD HH-MM-SS (if time is also specified).

toDate

The last date in the time period during which the alerts were created or modified. When toDate is not specified, the current date and time will be assumed.

string

No

Time is GMT. Format is:
YYYY-MM-DD or YYYY-MM-DD HH-MM-SS (if time is also specified).

Request Example

1 2 3 4 5 6 7 8 {     "requestType": "getProjectAlertsByType",     "userKey": "user_key",     "alertType": "alert_type",     "projectToken": "project_token",     "fromDate": "2020-09-01", "toDate": "2020-12-31" }

See Response Example for an example of a JSON response to the specified details in the above request example.

Back to top

Ignore Alerts

By default, alerts are in active state - meaning they will appear in dashboards and reports. If they are no longer relevant, you can change their to ignored and they will no longer be displayed.

This API request enables users with the Org Admin role permissions to ignore alerts according to their unique identifier. You can use any alert-related API to get the unique identifier (alertUuid) of a particular alert. 

Organization

Change alerts statuses from active to ignored for an organization.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that ignores alerts in an organization.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

orgToken

API key which is a unique identifier of the organization.

string

Yes

alertUuids

Unique IDs of the alerts to be ignored.

NOTE: The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

array

Yes

comments

Text comment describing why the alerts should be ignored.

string

Yes

Request Example

1 2 3 4 5 6 7 {   "requestType":"ignoreAlerts",   "orgToken": "organization_api_key",   "userKey": "user_key",   "alertUuids": ["22f72c74-c2ea-4ed9-b37f-75d77bc52045","22f72c74-c2ea-4ed9-b37f-75d77bc52046"],   "comments": "alerts not relevant to service" }

Response Example

1 2 3 {     "message": "Successfully ignored alerts" }

Product

Change alerts es from active to ignored for a product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that ignores alerts in a product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

alertUuids

Unique IDs of the alerts to be ignored.

NOTE: The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

array

Yes

comments

Text comment describing why the alerts should be ignored.

string

Yes

Request Example

1 2 3 4 5 6 7 {   "requestType":"ignoreAlerts",   "productToken": "product_key",   "userKey": "user_key",   "alertUuids": ["22f72c74-c2ea-4ed9-b37f-75d77bc52045","22f72c74-c2ea-4ed9-b37f-75d77bc52046"],   "comments": "alerts not relevant to service" }

Response Example

1 2 3 {     "message": "Successfully ignored alerts" }

Project

Change alerts statuses from active to ignored for a project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that ignores alerts in a project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

alertUuids

Unique IDs of the alerts to be ignored.

NOTE: The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

array

Yes

comments

Text comment describing why the alerts should be ignored.

string

Yes

Request Example

1 2 3 4 5 6 7 {   "requestType":"ignoreAlerts",   "projectToken": "project_key",   "userKey": "user_key",   "alertUuids": ["22f72c74-c2ea-4ed9-b37f-75d77bc52045","22f72c74-c2ea-4ed9-b37f-75d77bc52046"],   "comments": "alerts not relevant to service" }

Response Example

1 2 3 {     "message": "Successfully ignored alerts" }

Back to top

Set Alert

Alerts can be in Active or Ignored .

This API request enables users with the Org Admin role to set the of alert(s) according to their unique identifier.  This API can also be used to change the alert's comments. 

Organization

Change alerts statuses from active to ignored for an organization.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that sets the alerts in an organization.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

orgToken

API key which is a unique identifier of the organization.

string

Yes

alertUuids

Unique IDs of the alerts for which you want to change their .

NOTE: The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

array

Yes

comments

Free text comment describing why the alerts should be changed.

string

No

status

Current status of the alert(s): Active or Ignored.

string

Yes

Request Example

1 2 3 4 5 6 7 8 {     "requestType":"setAlertsStatus",     "orgToken":"organization_api_key",     "userKey": "user_key",     "alertUuids": ["alert1_UUID", "alert2_UUID"],     "comments": "Enter your comment here",     "status": "Active" }

Response Example

1 2 3 {     "message": "Successfully set the alert's status" }

Product

Change alerts statuses from active to ignored for a product.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that sets the alerts status in a product.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

productToken

API key which is a unique identifier of the product.

string

Yes

alertUuids

Unique IDs of the alerts for which you want to change their status.

NOTE: The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

array

Yes

comments

Free text comment describing why the alerts status should be changed.

string

No

status

Current status of the alert(s): Active or Ignored.

string

Yes

Request Example

1 2 3 4 5 6 7 8 {     "requestType":"setAlertsStatus",     "productToken":"product_key",     "userKey": "user_key",     "alertUuids": ["alert1_UUID", "alert2_UUID"],     "comments": "Enter your comment here",     "status": "Active" }

Response Example

1 2 3 {     "message": "Successfully set the alert's status" }

Project

Change alerts statuses from active to ignored for a project.

QUERY PARAMETERS

Parameter

Description

Type

Required

Parameter

Description

Type

Required

requestType

API request type that sets the alerts status in a project.

string

Yes

userKey

The ID of the user’s profile, which uniquely identifies the user in WhiteSource.

string

Yes

projectToken

API key which is a unique identifier of the project.

string

Yes

alertUuids

Unique IDs of the alerts for which you want to change their .

NOTE: The alert UUID is unique per CVE and therefore different for all the vulnerabilities related to the same library.

array

Yes

comments

Free text comment describing why the alerts should be changed.

string

No

status

Current status of the alert(s): Active or Ignored.

string

Yes

Request Example

1 2 3 4 5 6 7 8 {     "requestType":"setAlertsStatus",     "projectToken":"project_key",     "userKey": "user_key",     "alertUuids": ["alert1_UUID", "alert2_UUID"],     "comments": "Enter your comment here",     "status": "Active" }

Response Example

1 2 3 {     "message": "Successfully set the alert's status" }

Back to top