NOTES:

API capability requires an additional WhiteSource license. Contact your CSM for more details.
For customers who have enabled vulnerability-based alerting, there are several changes to API version 1.3 - refer here for details.
This page covers APIs for version 1.3. All version 1.3 APIs must include:
- A valid ‘userKey’. See User Level Access Control in Integrations and APIs. The "Enforce user level access" settings is not required for API calls.

Overview

The WhiteSource HTTP API is available for WhiteSource customers who are licensed to use it. The APIs can be accessed by the organization's administrator(s).

This document describes the WhiteSource HTTP API v1.3. The API URL can be obtained by copying the 'WhiteSource Server URL', which can be retrieved from your 'Profile' page on the 'Server URLs' panel. Then, add the path '/api/v1.3' to it. For example: https://saas.whitesourcesoftware.com/api/v1.3.

The API is simply an HTTP endpoint implementing a JSON speaking web service and handling POST requests. Like the service itself, communication is secured with SSL.

The old WhiteSource API is currently still supported, and is documented in the HTTP API page.

Note that when performing API calls, the time recorded for the action is in GMT time zone, therefore, this is the time displayed in the relevant reports.

API Execution Scope

Generally, each level of the administrator (Organization, Product) can get/set the API attributes in the API calls that refer to their scope and/or under their scope. For example, Product administrators can execute API calls related to their Projects/Products that are defined in WhiteSource, but they cannot execute Organization-related API calls which are outside their scope. However, there are two API calls that are exceptions to this rule:

getProjectVitals – Product administrators can use the Organization level call and get the product/project vitals related to their products/projects.
getRequestState – Although an Organization token is required in the call, a product administrator can also execute it.

API URL

The base URL for all API endpoints can be obtained from the Integrate tab (calls to HTTP cannot be redirected to HTTPS).

Only POST requests are accepted.

Request payload should have: Content-Type = application/json

Character Sets

WhiteSource HTTP API v1.x supports Accept-Charset header.

If the value of the header is a supported character set (see supported values below) the response would be in that character set.
Otherwise, if the value is not supported or if the header isn't sent, the default response character set will be UTF-8.

Supported character sets are:

utf-8
utf-16
iso-8859-1
iso-8859-2
iso-8859-4
iso-8859-5
iso-8859-7
iso-8859-9
us-ascii

Special Characters

The following characters are NOT supported as API input: <, >, % and &

Supported Methods

WhiteSource HTTP API supports the following methods:

Alerts

Get All Organization Alerts
Get All Product Alerts
Get All Project Alerts
Get Alerts by Project tag

Alerts by Type

Get Organization Alerts by Type
Get Product Alerts by Type
Get Project Alerts by Type

Change Log

Get Change Log

Licenses

Get All Organization Licenses
Get All Product Licenses
Get All Project Licenses

License Histogram

Get Organization License Histogram
Get Product License Histogram
Get Project License Histogram

Organization Vitals

Get All Organizations
Get Organization Details

Project / Product Vitals

Get All Products
Get All Projects
Get Organization Project Vitals (vitals of all projects within an organization)
Get Product Project Vitals (vitals of all projects within a product)
Get Project Vitals
Get Organization Product Vitals (vitals of all products within an organization)

Project Tags

Get Organization Project Tags
Get Product Project Tags
Get Project Tags
Save Project Tag

Misc.

Get Product Licenses Text Zip file
Update project with JNinka result file (jninka.xml)

Reports

See Reports API

Library Locations

Get Product Library Locations
Get Project Library Locations

Policies

See Policies API.

Groups and Users

See Groups and Users APIs

Project Create / Delete

Create Project
Delete Project

Product Create / Delete

Create Product
Delete Product

Project API Requests

Get Project Hierarchy
Get Project Inventory
Get Project State
Get Library Source Files

WhiteSource Advise for Chrome

Invite user to WhiteSource Advise for Chrome

API Format

All requests require a token available via the API Integration page in your WhiteSource account, according to the request's context (organization / product / project).

The requestType field is mandatory for all requests.

Fields

Field name	Value
requestType	One of the following: getOrganizationAlerts getOrganizationIgnoredAlerts getProductAlerts getProjectAlerts getAlertsByProjectTag getOrganizationAlertsByType getProductAlertsByType getProjectAlertsByType getOrganizationLicenses getProductLicenses getProjectLicenses getOrganizationEffectiveUsageAnalysis getOrganizationLicenseHistogram getProductLicenseHistogram getProjectLicenseHistogram getLicensesTextZip saveProjectTag getProductLibraryLocations getProjectLibraryLocations getOrganizationRiskReport getProductRiskReport getOrganizationInventoryReport getProductInventoryReport getProjectInventoryReport getOrganizationVulnerabilityReport getOrganizationContainerVulnerabilityReport getClusterVulnerabilityReport getProductVulnerabilityReport getProjectVulnerabilityReport getOrganizationSourceFileInventoryReport getProductSourceFileInventoryReport getProjectSourceFileInventoryReport getOrganizationAlertsReport getProductAlertsReport getProjectAlertsReport getOrganizationAttributesReport getProductAttributesReport getOrganizationCustomAttributeValues getProductCustomAttributeValues getProjectCustomAttributeValues getOrganizationLibraryLocationReport getProductLibraryLocationReport getOrganizationDueDiligenceReport getProductDueDiligenceReport getProjectDueDiligenceReport getOrganizationEffectiveLicensesReport getProductEffectiveLicensesReport getOrganizationBugsReport getProductBugsReport getProjectBugsReport getOrganizationIgnoredAlertsReport getProductIgnoredAlertsReport getProjectIgnoredAlertsReport getOrganizationResolvedAlertsReport getProductResolvedAlertsReport getProjectResolvedAlertsReport getOrganizationRequestHistoryReport getProductRequestHistoryReport getProjectRequestHistoryReport getPluginRequestHistoryReport getOrganizationMembersReport getProductMembersReport getProjectMembersReport getProductComparisonReport getProjectComparisonReport getOrganizationInHouseReport getProductInHouseReport getProjectInHouseReport getOrganizationPolicies getChangesReport getProductAttributionReport getProjectAttributionReport getProductPolicies addOrganizationPolicy addProductPolicy updateOrganizationPolicy updateProductPolicy removeOrganizationPolicies removeProductPolicies reorderOrganizationPolicyPriorities reorderProductPolicyPriorities getLicenses createUser inviteUsers createGroup getAllGroups getAllUsers getOrganizationAssignments getProductAssignments setOrganizationAssignments setProductAssignments addUsersToGroups removeUserFromGroup removeUserFromOrganization createProject deleteProject createProduct deleteProduct getProjectHierarchy getProjectInventory getProjectState getLibrarySourceFiles inviteUserToWebAdvisor createServiceUser changeOriginLibrary
orgToken	Your organization API key
productToken	A unique identifier for your product
projectToken	A unique identifier for your project
alertType	One of the following: SECURITY_VULNERABILITY NEW_MAJOR_VERSION NEW_MINOR_VERSION MULTIPLE_LIBRARY_VERSIONS REJECTED_BY_POLICY_RESOURCE

Alert Types

Name	Description
SECURITY_VULNERABILITY	A security vulnerability has been detected for a library in the inventory
NEW_MAJOR_VERSION	A new major version has been released for a library in the inventory (only if major version updates is enabled)
NEW_MINOR_VERSION	A new minor version has been released for a library in the inventory (only if minor version updates is enabled)
MULTIPLE_LIBRARY_VERSIONS	Multiple versions of the same library are being used
REJECTED_BY_POLICY_RESOURCE	A library violating one of your policies is being used

Notice: For version numbers, if there are 3 or more version parts, (E.g. x.y.z or x.y.z.w) both x and y are considered a major version (x.y).
If there are 2 major parts (x.y), then x is considered a major version.

Date format in all responses is "yyyy-MM-dd".

None of the results are sorted in any order.

Get Alerts

See Alerts API for documentation.

Security Vulnerability

Alerts will also contain the following object:

"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 fields:

Field name	Value
name	The id in the vulnerability DB (CVE or WS)
type	Either CVE or WS
severity	Severity of the CVSS 2 vulnerability (low, medium, high)
score	The CVSS 2 base score [0.0 - 10.0]
cvss3_severity	The score severity, if CVSS 3 score is between 0-3.9 - Low, if CVSS 3 score is between 4-6.9 - Medium, if CVSS 3 score is between 7-10 - High
cvss3_score	The CVSS 3 base score [0.0 - 10.0]
scoreMetadataVector	See specification link
publishDate	Original release date
url	URL of the CVE
description	A 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 Change Log Report

Get organization level Change Log Report in various formats.

Request

{
      "userKey": "user_key", 
      "orgToken": "organization_api_key",
      "requestType": "getChangesReport",
	  "startDateTime": "2019-08-21 08:08:08" 	
}

Optional Parameters

startDateTime: Date and time for the reported change. Default value: The last seven days including today's date. For example, if today is March 15, then the filtering is for the dates 9-15 of March.
Valid options (strings in uppercase):
- Any past valid date and time in the following format: 'yyyy-mm-dd hh:mm:ss'.

Response

{
    "changes": [
        {
            "startDateTime": "2018-07-04 09:07:21",
            "category": "METADATA",
            "type": "SOURCE_MATCHING",
            "changeType": "CHANGED",
            "scope": "SOURCE_FILE",
            "scopeName": "activation_mode.h",
            "scopeId": 2922950,
            "beforeChange": [
                "tensorflow-v1.4.0-rc0"
            ],
            "afterChange": [
                "tensorflow-v1.4.0-rc0"
            ],
            "operator": "USER",
            "userEmail": "john@doe.com",
            "productId": 69491,
            "productName": "tensorflow",
            "projectId": 338568,
            "projectName": "tensor",
            "comment": "changed lib of source file"
        }
    ]
}

Get Licenses

Get all libraries and their licenses for a given organization/product/project.

Organization

{
	"requestType" : "getOrganizationLicenses",
     "userKey": "user_key", 
	"orgToken" : "organization_api_key",
    "excludeProjectOccurrences" : true/false
}

Product

{
	"requestType" : "getProductLicenses",
    "userKey": "user_key", 
	"productToken" : "product_token",
 	"excludeProjectOccurrences" : true/false
}

Project

{
	"requestType" : "getProjectLicenses",
    "userKey": "user_key", 
	"projectToken" : "project_token",
 	"excludeProjectOccurrences" : true/false
}

Response Format

"libraries" : [
	{
        "licenses" : [
            "license_name_1",
            "license_name_2", 
            "spdxName":"license_spdx_name"
        ],
        "copyrightReferences": [
            {
            "copyright": "library_copyright_text",
            "startYear": "library_copyright_start_year"
            }
        ],
        "keyUuid": "library_key_uuid",
        "keyId": "library_key_id",
        "filename": "library_file_name",
        "name" : "libarary_name",
        "groupId" : "library_group_id",
        "artifactId" : "library_artifact_id",
        "version" : "library_version",
        "sha1" : "library_sha1",
        "languages": "library_language",
        "references" : {"url":"library_url",
                        "downloadLink":"library_download_link"
                        }
    }
]

Get License Histogram

Get the license histogram (license name : occurrence) for a given organization/product/project.

Organization

{
	"requestType" : "getOrganizationLicenseHistogram",
    "userKey": "user_key", 
	"orgToken" : "organization_api_key"
}

Product

{
	"requestType" : "getProductLicenseHistogram",
	"productToken" : "product_token"
}

Project

{
	"requestType" : "getProjectLicenseHistogram",
    "userKey": "user_key", 
	"projectToken" : "project_token"
}

Response Example

{
	"licenseHistogram" : {
		"Apache 2.0" : 2,
		"BSD 3" : 2,
		"GPL 3.0" : 1,
	}
}

Get Organization Details

Returns the Organization name, creation date, number of Products, number of Projects, number of groups, and number of users

Request

{
"requestType":"getOrganizationDetails",
"orgToken":"org_token",
“userKey”:”user_key”
}

Response (Example)

{
"orgName": "Org A",
"orgToken": "Org_a_token"
"creationDate": "2016-01-01 12:00:00"
"numberOfProducts": "15"
"numberOfProjects": "105"
"numberOfGroups": "2"
"numberOfUsers": "3"
}

Get All Products

Receives an orgToken and returns all products in the organization; name and token of each.

Request

{
  "requestType":"getAllProducts",
  "userKey": "user_key", 
  "orgToken":"org_token"
}

Response

{
    "products": [
        {
            "productName": "Product A",
            "productToken": "product_a_token"
        },
        {
            "productName": "Product B",
            "productToken": "product_b_token"
        }
    ],
    "message": "Success"
}

Get All Projects

Receives a productToken and returns all projects in the product; name and token of each.

Request

{
  "requestType":"getAllProjects",
  "userKey": "user_key", 
  "productToken":"product_token"
}

Response

{
    "projects": [
        {
            "projectName": "project_a",
            "projectToken": "project_a_token"
        },
        {
            "projectName": "project_b",
            "projectToken": "project_b_token"
        }
    ],
    "message": "Success"
}

Get In-House Libraries

Get information regarding all in-house libraries on an organization, product, and project level.

Request

Organization Level

{
    "requestType" : "getOrganizationInHouseLibraries",
    "orgToken" : "organization_api_key",
    "userKey": "user_key"
}

Product Level

{
    "requestType" : "getProductInHouseLibraries",
    "productToken" : "product_token",
    "userKey": "user_key"
}

Project Level

{
    "requestType" : "getProjectInHouseLibraries",
    "projectToken" : "project_token",
    "userKey": "user_key"
}

Response

"libraries" : [
    {
        "matchType" : "manual",
        "comment": "manually set to in-house",
        "keyUuid": "library_unique_id",
        "filename": "library_file_name",
        "groupId": "library_group_id",
        "artifactId": "library_artifact_id",
        "version": "library_version",
        "sha1": "library_sha1",
        "type": "library_type",
        "description": "library_description",
        "productName" : "product_name",
        "productToken" : "product_token",
        "projectName" : "project_name",
        "projectToken" : "project_token" 
    },
    {
        "matchType" : "automatic",
        "pattern" : "common-*",
        "keyUuid": "library_unique_id",
        "filename": "library_file_name",
        "groupId": "library_group_id",
        "artifactId": "library_artifact_id",
        "version": "library_version",
        "sha1": "library_sha1",
        "type": "library_type",
        "description": "library_description",
        "productName" : "product_name",
        "productToken" : "product_token",
        "projectName" : "project_name",
        "projectToken" : "project_token  
    }
]

Response Parameters

matchType parameter value can be either 'manual' (manually marked by user) or 'automatic' (automatically marked by in-house rule).
pattern parameter is not returned for a library if matchType value is 'manual'.
comment parameter is not returned for a library if matchType value is 'automatic'.

Unmark In-House Libraries

Unmark libraries that were manually assigned as in-house.

This request is only in organization level, and therefore requires an org token.

Request

Organization Level

{
    "requestType": "unmarkManualInHouseLibrary",
    "userKey": "user_key",
    "orgToken": "organization_api_key",
    "keyUuid" : "library_UUID"
}

Response

{
    "message": "Successfully unmarked in-house library"
}

Get Project Vitals

Get basic information regarding a project: name, token, creation date and last updated date.

Organization

{
	"requestType" : "getOrganizationProjectVitals",
     "userKey": "user_key", 
	"orgToken" : "organization_api_key"
}

Product

{
	"requestType" : "getProductProjectVitals",
    "userKey": "user_key", 
	"productToken" : "product_token"
}

Project

{
	"requestType" : "getProjectVitals",
     "userKey": "user_key", 
	"projectToken" : "project_token"
}

Response

{
	"projectVitals":[
    	{
			"pluginName":"fs-agent:18.2.2",
			"name": "My Project",
			"token": "project_token",
			"uploadedBy": "name_of_user_who_ran_scan", 
			"creationDate": "2016-01-01 12:00:00",
			"lastUpdatedDate": "2016-02-02 16:50:59"
		}
	]
}

Get Product Vitals

Get basic information regarding a product: name, token, creation date and last updated date.

Organization

{
	"requestType" : "getOrganizationProductVitals",
    "userKey": "user_key", 
	"orgToken" : "organization_api_key"
}

Response

{
	"productVitals":[
    	{
			"name": "My Product",
			"token": "product_token",
			"creationDate": "2016-01-01 12:00:00",
			"lastUpdatedDate": "2016-02-02 16:50:59"
		}
	]
}

Global Organization

According to permissions, users can create global organizations, assign them to organizations, or remove them from the organizations.

Create Global Organization

{
   "requestType": "createGlobalOrg",
   "userKey": "user_key",
   "name": "global_org_name",
   "accountAdminEmail": "enter_account_admin_email@here.com"
}

Response

{
   "globalOrgToken": "global_org_token"
}

Assign Global Organization to an Organization

{
   "requestType": "assignGlobalOrgToOrg",
   "userKey": "user_key",
   "orgToken": "org_token",
   "globalOrgToken": "global_org_token"
}

Remove Global Organization from an Organization

{
   "requestType": "removeGlobalOrgFromOrg",
   "userKey": "user_key",
   "orgToken": "org_token",
   "globalOrgToken": "global_org_token"
}

Get All Organizations

Returns data on all organizations within the Global Organization.

Request

{
  "requestType":"getAllOrganizations",
  "userKey": "user_key", 
  "globalOrgToken":"global_organization_token"
}

Response

{
    "organizations": [
        {
            "orgName": "Org A",
            "orgToken": "Org_a_token"
        },
        {
            "orgName": "Org B",
            "orgToken": "Org_b_token"
        }
    ],
    "message": "Success"
}

Product Tags

Get Product Tags

Get product tags: key, value.

Request

{
	"requestType": "getProductTags",
    "userKey": "user_key", 
	"productToken": productToken
}

Response

{
	"productTags":[
    	{
			"name": "My Product A",
			"token": "product_token",
			"tags": {
                "newKey": [
                    "newValue",
                    "newValue2"
                ],
                "tagKeyA": [
                    "tagValueA"
                ]
            }
        }
    ]

Products without tags are returned as well.

Save a Product Tag

Save a product tag: key, value.

Request

{
"requestType": "saveProductTag",
"userKey": "user_key", 
"productToken": "productToken",
"tagKey": "newKey",
"tagValue": "newValue"
}

Response

{
    "productTagsInfo": {
        "name": "productA",
        "token": {productToken},  
        "tags": {
            "newKey": "newValue"
        }
    }
}

Products without tags are also returned.

Get Organizational Product Tags

Get organizational product tags: key, value.

Request

{
"requestType": "getOrganizationProductTags",
"userKey": "user_key", 
"orgToken": "orgToken"
}

Response

{
    "productTags": [
        {
            "name": "productA",
            "token": " productAToken",
            "tags": {
                "newKey": [
                    "newValue",
                    "newValue2"
                ],
                "tagKeyA": [
                    "tagValueA"
                ]
            }
        },
        {
            "name": " productB",
            "token": " productBToken",
            "tags": {}
        }
    ]
}

Products without tags are also returned.

Remove a Product Tag

Remove a product tag: key, value.

Request

{
	"requestType" : "removeProductTag",
     "userKey": "user_key", 
	"productToken" : "product_token",
    "tagKey": "newKey",
    "tagValue": "newValue"
}

Response

{
    "message": "Successfully removed product tag"
}

Project Tags

Get Project Tags

Get project tags: key, value.

Organization

{
	"requestType" : "getOrganizationProjectTags",
    "userKey": "user_key", 
	"orgToken" : "organization_api_key"
}

Product

{
	"requestType" : "getProductProjectTags",
    "userKey": "user_key", 
	"productToken" : "product_token"
}

Project

{
	"requestType" : "getProjectTags",
    "userKey": "user_key", 
	"projectToken" : "project_token"
}

Response

{
	"projectTags":[
    	{
			"name": "My Project 1",
			"token": "project_token_1",
			"tags":{
				"Component": "Database",
				"Module": "Server"
			}
		},
		{
			"name": "My Project 2",
			"token": "project_token_2",
			"tags":{}
		}
	]
}

Projects without tags are also returned.

Save a Project Tag

Save a project tag by key, value.

Project

{
    "requestType" : "saveProjectTag",
     "userKey": "user_key", 
    "projectToken" : "project_token", 
    "tagKey":"key1",
    "tagValue":"value1"
}

Response

{
	"projectTags":
		{
			"name": "My Project 1",
			"token": "project_token_1",
			"tags":
				{
					"key1": "value1"
				}
		}
}

Licenses Text Zip

Get the licenses terms and conditions text files contained in a single zip file.

Product

{
	"requestType" : "getLicensesTextZip",
     "userKey": "user_key", 
	"productToken" : "product_token"
}

Project

{
    "requestType" : "getProjectLicensesTextZip",
     "userKey": "user_key",
    "projectToken" : "project_token"
}

Response

The response will have the following headers:

Content-Type = application/zip
Content-Disposition: attachment; filename=product_name-licenses.zip

The response is a zip file, not a json formatted message

Copyrights Text File

Get the copyrights' text files.

Product

{
	"requestType" : "getCopyrightsTextFile",
     "userKey": "user_key", 
	"productToken" : "product_token"
}

Project

{
    "requestType" : "getProjectCopyrightsTextFile",
     "userKey": "user_key",
    "projectToken" : "project_token"
}

Response

The response will have the following headers:

Content-Type = text/plain
Content-Disposition: attachment; filename=product_name-copyrights.zip

Set Library Notices

This API enables setting the value of the library’s notice.

Request

{  
  "requestType": "setLibraryNotice",  
  "orgToken" : "org_token", 
  "userKey": "user_key",  
  "libraryUUID": "library_UUID", 
  "text": "Notices are fun!", 
  "reference": "And references are too"
}

NOTE: The reference field is optional.

Response

{
    "message": "Successfully set notice"
}

Get Notices Text File

Get the notices text files.

This request is available only for products

Product

{
	"requestType" : "getNoticesTextFile",
     "userKey": "user_key", 
	"productToken" : "product_token"
}

Response

The response will have the following headers:

Content-Type = text/plain
Content-Disposition: attachment; filename=product_name-notices.zip

Get Policies

See Policies API for documentation.

Get Groups and Users

See Groups and Users APIs for documentation.

Get Products and Projects

See Product and Project-Level APIs for documentation.

{
    "requestType" : "createProject",
     "userKey": "user_key", 
    "productToken": "product_token",
    "projectName": "my new project",
    "projectDescription" : "optional field. Not mandatory"
}

The "projectDescription" field is an optional field.

Response Format

{
  "projectToken": "new project token here",
  "message": "Successfully created project my new project"
}

Delete Project

{
"requestType" : "deleteProject",
 "userKey": "user_key", 
"productToken" : "parent product token",
"projectToken": "token of the project to be deleted"
}

Response Format

{
"message": "Successfully deleted project <project name>"
}

Create Product

{
"requestType" : "createProduct",
 "userKey": "user_key", 
"productName" : "new product name",
"orgToken" : "organization token"
}

Response Format

{
"productToken": "new product token",
"message": "Successfully created product <new product name>"
}

Delete Product

{
"requestType" : "deleteProduct",
 "userKey": "user_key", 
"orgToken" : "organization token",
"productToken" :"product token"
}

Response Format

{
"message": "Successfully deleted product <product name>"
}

Get Project Hierarchy

'includeInHouseData' is an optional parameter. When set to ‘false’, in-house libraries data is not returned in the API response (default is ‘true’).

{
"requestType" : "getProjectHierarchy",
 "userKey": "user_key", 
"projectToken" : "project token",
"includeInHouseData" : true
}

Response Format

{
  "libraries": [
    {
      "keyUuid": "1f9ee6ec-eded-45d3-8fdb-2d0d735e5b14",
      "keyId": 43,
      "filename": "log4j-1.2.17.jar",
      "name": "log4j",
      "groupId": "log4j",
      "artifactId": "log4j",
      "version": "1.2.17",
      "sha1": "5af35056b4d257e4b64b9e8069c0746e8b08629f",
      "type": "UNKNOWN_ARTIFACT",
      "coordinates": "log4j:log4j:1.2.17"
    },
    {
      "keyUuid": "f362c53f-ce25-4d0c-b53b-ee2768b32d1a",
      "keyId": 45,
      "filename": "akka-actor_2.11-2.5.2.jar",
      "name": "akka-actor",
      "groupId": "com.typesafe.akka",
      "artifactId": "akka-actor_2.11",
      "version": "2.5.2",
      "sha1": "183ccaed9002bfa10628a5df48e7bac6f1c03f7b",
      "type": "MAVEN_ARTIFACT",
      "coordinates": "com.typesafe.akka:akka-actor_2.11:2.5.2",
      "dependencies": [
        {
          "keyUuid": "49c6840d-bf96-470f-8892-6c2a536c91eb",
          "keyId": 44,
          "filename": "scala-library-2.11.11.jar",
          "name": "Scala Library",
          "groupId": "org.scala-lang",
          "artifactId": "scala-library",
          "version": "2.11.11",
          "sha1": "e283d2b7fde6504f6a86458b1f6af465353907cc",
          "type": "MAVEN_ARTIFACT",
          "coordinates": "org.scala-lang:scala-library:2.11.11"
        },
        {
          "keyUuid": "e5e730d1-8b41-4d2d-a8c5-610a374b6501",
          "keyId": 46,
          "filename": "scala-java8-compat_2.11-0.7.0.jar",inve
          "name": "scala-java8-compat_2.11",
          "groupId": "org.scala-lang.modules",
          "artifactId": "scala-java8-compat_2.11",
          "version": "0.7.0",
          "sha1": "a31b1b36bcf0d53657733b5d40c78d5f090a5dea",
          "type": "UNKNOWN_ARTIFACT",
          "coordinates": "org.scala-lang.modules:scala-java8-compat_2.11:0.7.0"
        },
        {
          "keyUuid": "426c0056-f180-4cac-a9dd-c266a76b32c9",
          "keyId": 47,
          "filename": "config-1.3.1.jar",
          "name": "config",
          "groupId": "com.typesafe",
          "artifactId": "config",
          "version": "1.3.1",
          "sha1": "2cf7a6cc79732e3bdf1647d7404279900ca63eb0",
          "type": "UNKNOWN_ARTIFACT",
          "coordinates": "com.typesafe:config:1.3.1"
        }
      ]
    },
    {
      "keyUuid": "25a8ceaa-4548-4fe4-9819-8658b8cbe9aa",
      "keyId": 48,
      "filename": "kafka-clients-0.10.2.1.jar",
      "name": "Apache Kafka",
      "groupId": "org.apache.kafka",
      "artifactId": "kafka-clients",
      "version": "0.10.2.1",
      "sha1": "3dd2aa4c9f87ac54175d017bcb63b4bb5dca63dd",
      "type": "MAVEN_ARTIFACT",
      "coordinates": "org.apache.kafka:kafka-clients:0.10.2.1",
      "dependencies": [
        {
          "keyUuid": "71065ffb-e509-4e2d-88bc-9184bc50888d",
          "keyId": 49,
          "filename": "lz4-1.3.0.jar",
          "name": "LZ4 and xxHash",
          "groupId": "net.jpountz.lz4",
          "artifactId": "lz4",
          "version": "1.3.0",
          "sha1": "c708bb2590c0652a642236ef45d9f99ff842a2ce",
          "type": "MAVEN_ARTIFACT",
          "coordinates": "net.jpountz.lz4:lz4:1.3.0"
        },
        {
          "keyUuid": "e44ab569-de95-4562-8efa-a2ebfe808471",
          "keyId": 50,
          "filename": "slf4j-api-1.7.21.jar",
          "name": "SLF4J API Module",
          "groupId": "org.slf4j",
          "artifactId": "slf4j-api",
          "version": "1.7.21",
          "sha1": "139535a69a4239db087de9bab0bee568bf8e0b70",
          "type": "MAVEN_ARTIFACT",
          "coordinates": "org.slf4j:slf4j-api:1.7.21"
        },
        {
          "keyUuid": "72ecad5e-9f35-466c-9ed8-0974e7ce4e29",
          "keyId": 51,
          "filename": "snappy-java-1.1.2.6.jar",
          "name": "snappy-java",
          "groupId": "org.xerial.snappy",
          "artifactId": "snappy-java",
          "version": "1.1.2.6",
          "sha1": "48d92871ca286a47f230feb375f0bbffa83b85f6",
          "type": "UNKNOWN_ARTIFACT",
          "coordinates": "org.xerial.snappy:snappy-java:1.1.2.6"
        }
      ]
    }
  ]
}

Get Project Inventory

'includeInHouseData' is an optional parameter. When set to ‘false’, in-house libraries data is not returned in the API response (default is ‘true’).

{
"requestType" : "getProjectInventory",
 "userKey": "user_key", 
"projectToken" : "project_token",
"includeInHouseData" : true
}

Response Format

{"projectVitals":{
"productName": "fsa",
"name": "fsa",
"token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"creationDate": "2017-06-17 07:12:29",
"lastUpdatedDate": "2017-06-17 07:34:31"
},
"libraries":[
{
"keyUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"keyId": 24559109,
"name": "comm-2.0.3.jar",
"artifactId": "comm-2.0.3.jar",
"type": "MAVEN_ARTIFACT",
"licenses":[],
"vulnerabilities":[],
"outdated": false,
"matchType": "FILENAME"
}]}

Get Project State

{
    "requestType":"getProjectState",
     "userKey": "user_key", 
  	"projectToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response Format

{
	"projectState":{
	"lastProcess":"UPDATE",
	"inProgress":false,
	"date":"2017-06-17"}
}

Get Library Source Files

{
    "requestType":"getLibrarySourceFiles",
     "userKey": "user_key", 
  	"projectToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "keyUuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response Format

{"sourceFiles":[{
	"sha1":"6bf3b8ddfecac64a916ba69de50e9faac70992ba",
	"name":"x509_obj.c",
	"path":"C:\\Users\\Work1\\Documents\\FSA\\GITHUB-downloads\\openssl_openssl_OpenSSL_0_9_4_openssl_openssl_OpenSSL_0_9_4_crypto_x509_x509_obj.c"}]
}

Get Project Library Dependencies

{
  "requestType":"getProjectLibraryDependencies",
  "userKey": "user_key", 
  "projectToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "keyUuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response Format

{
   "dependencies":[
     [
      {
         "keyUuid":"0b6a3818-ed95-4190-b40d-0d0d9ca51166",
         "name":"CDI APIs",
         "groupId":"javax.enterprise",
         "artifactId":"cdi-api",
         "version":"1.0",
         "classifier":"",
         "scope":"COMPILE",
         "extension":"jar",
         "sha1":"44c453f60909dfc223552ace63e05c694215156b",
         "dependencies":[
            {
               "keyUuid":"e8d725f6-081c-4e7d-b09c-3fadcb861a35",
               "name":"JSR-250 Common Annotations for the JavaTM Platform",
               "groupId":"javax.annotation",
               "artifactId":"jsr250-api",
               "version":"1.0",
               "classifier":"",
               "scope":"COMPILE",
               "extension":"jar",
               "sha1":"5025422767732a1ab45d93abfea846513d742dcf",
               "dependencies":[
               ],
               "licenses":[
                  {
                     "name":"CDDL 1.0",
                     "url":"http://www.opensource.org/licenses/CDDL-1.0"
                  }
               ]
            }
         ],
         "licenses":[
            {
               "name":"Apache 2.0",
               "url":"http://www.opensource.org/licenses/Apache-2.0"
            }
         ]
      },
      {
         "keyUuid":"b4264d26-09ca-4266-97ba-0bec7318d984",
         "name":"org.eclipse.sisu.inject",
         "groupId":"org.eclipse.sisu",
         "artifactId":"org.eclipse.sisu.inject",
         "version":"0.3.2",
         "classifier":"",
         "scope":"COMPILE",
         "extension":"jar",
         "sha1":"59044b92ec27cc6fda7a2d24b2cd6cec23f31d5b",
         "dependencies":[
         ],
         "licenses":[
            {
               "name":"Eclipse 1.0",
               "url":"http://www.opensource.org/licenses/EPL-1.0"
            }
         ]
      }
    ]
  ]
}

WhiteSource Advise for Chrome

Invite User to WhiteSource Advise for Chrome

{
  "requestType" : "inviteUserToWebAdvisor",
   "userKey": "user_key", 
  "orgToken" : "Organization Token",
  "userEmail": "User email address"
}

Response

{ "message": "Successfully invited external user" }

Service User

Create a Service User

{
  "requestType": "createServiceUser",
  "orgToken": "organization_api_key",
  "userKey": "user_key",
  "addedUser":{
    "name":"new_user_name"
    }
}

Response

{
    "user" : {
        "userKey":  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
}

Regenerate User Key for a Service User

{
  "requestType": "regenerateUserKey",
  "orgToken": "organization_api_key",
   "userKey": "user_key",
   "serviceUserKey": "service_user_key"
}

Response

{
    "user" : {
        "userKey":  232gkey45gt34
}

Get Organization Service User

{
  "requestType":"getOrganizationServiceUsers",
  "userKey":"user_key",
  "orgToken":"org_token"
}

Response

{
    "serviceUsers": [
        {
            "serviceUserName": "user_a",
            "serviceUserToken": "user_a_token"
        },
        {
            "serviceUserName": "user_b",
            "serviceUserToken": "user_b_token"
        }
    ]
}

Get Product Service User

{
  "requestType":"getProductServiceUsers",
  "userKey":"user_key",
  "productToken":"product_token"
}

Response

{
    "serviceUsers": [
        {
            "serviceUserName": "user_a",
            "serviceUserToken": "user_a_token"
        }
    ]
}

Change Origin Library

Changes the origin library of source files.

{
    "requestType" : "changeOriginLibrary",
    "userKey": "userKey",
    "orgToken" : "orgToken",
    "targetKeyUuid": "key-uuid-of-the-source-library-to-change-files",
    "sourceFiles": ["sha1_1", "sha1_2"],
    "userComments": "user-comments"
}

Response Format

{
    "message": "Successfully changed origin library"
}

Set Project Setup Notification Configuration

This request enables you to define rules for email notifications.

{ 
  "requestType" : "setProjectSetupNotificationConfig", 
  "orgToken" : "organization_api_key", 
  "userKey" : "user_api_key", 
  "action": "notification_ENABLED|DISABLED|CUSTOM", 
  "projectTagKeyRegex" : "project_tag_key_pattern", 
  "projectTagValueRegex" : "project_tag_value_pattern" 
}

Response Format

{ 
"message": "Successfully changed project setup completion notification configuration" 
}

'action' values are: CUSTOM, ENABLED, DISABLED
'projectTagKeyRegex' and 'projectTagValueRegex' are mandatory only in case the action is CUSTOM. Both of their values must be formatted regex valid strings. In such cases, the notifications are sent when both projectTagKeyRegex and projectTagValueRegex are in accordance with the defined project tags.

CUSTOM Action Sample

{ 
  "requestType" : "setProjectSetupNotificationConfig", 
  "orgToken" : "5dc3e478a8f6500e5b525f3", 
  "userKey" : "7e3694ac0a50ebb", 
  "action": "CUSTOM", 
  "projectTagKeyRegex" : "^[0-9]*$", 
  "projectTagValueRegex" : "^(ProjectTagValue)"
}

Get Plugin Request State

Get Request State

{
    "requestType" : "getRequestState",
    "userKey": "user_key", 
    "orgToken" : "organization token",
    "requestToken" : "support token"
}

Response Format

{
    "requestState": "FINISHED",
    "timestamp": "2018-02-28T17:48:19Z"
}

Possible requestState values:

UNKNOWN - either orgToken or requestToken are invalid
IN_PROGRESS - update is in progress
UPDATED - inventory has been modified yet alerts have not been calculated yet
FINISHED - alerts have been calculated successfully
FAILED - an error has occurred during the update process
SKIPPED - when a scan for a project is requested while a scan for the same project is being executed simultaneously, the new scan is skipped

The timestamp field is GMT time.

The requestToken (also displayed as "Support Token" when printing results to the console from the plugins) can be found in the data of the response returned form the server).

Note: Available since version 18.2.1

Vulnerability-Based Alerts

The following APIs are only available in organization set to vulnerability based alerting mode.

Get Security Alerts by Vulnerability Report

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

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

Organization

{
	"requestType" : "getOrganizationSecurityAlertsByVulnerabilityReport",
    "userKey": "user_key", 
	"orgToken" : "organization_api_key",
    "status" : "active",
    "format" : "xlsx"
}

Product

{
	"requestType" : "getProductSecurityAlertsByVulnerabilityReport",
    "userKey": "user_key", 
	"productToken" : "product_token",
	"status" : "ignored",
    "format" : "xlsx"
}

Project

{
	"requestType" : "getProjectSecurityAlertsByVulnerabilityReport",
    "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

Get Security Alerts by Library Report

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 list 1 active alert. A library that is marked as "ignored" has at list 1 ignored alert.

Organization

{
	"requestType" : "getOrganizationSecurityAlertsByLibraryReport",
    "userKey": "user_key", 
	"orgToken" : "organization_api_key",
    "status" : "active",
    "format" : "xlsx"
}

Product

{
	"requestType" : "getProductSecurityAlertsByLibraryReport",
    "userKey": "user_key", 
	"productToken" : "product_token",
	"status" : "ignored",
    "format" : "xlsx"
}

Project

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

Get License and Compliance Alerts Report

Generates license and Compliance alerts report in the scope of the organization, a specific product or a specific project.

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

Organization

{
	"requestType" : "getOrganizationLicenseAndComplianceAlertReport",
    "userKey": "user_key", 
	"orgToken" : "organization_api_key",
    "status" : "active",
    "format" : "xlsx"
}

Product

{
	"requestType" : "getProductLicenseAndComplianceAlertReport",
    "userKey": "user_key", 
	"productToken" : "product_token",
	"status" : "ignored",
    "format" : "xlsx"
}

Project

{
	"requestType" : "getProjectLicenseAndComplianceAlertReport",
    "userKey": "user_key", 
	"projectToken" : "project_token",
    "format" : "json"
}

Response

The response will have the following headers:

Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename=<organization name>-license-and-compliance-alert-report.xlsx

Response Structure

Structure of the vulnerability in each security vulnerability alert object:

Vulnerability

Each vulnerability object has the following fields:

name - the name of the vulnerability (e.g. CVE-2008-0983).
severity - the CVSS severity (as taken from NVD), can be one of:
1. HIGH
2. MEDIUM
3. LOW
score - the CVSS score (as taken from NVD), values range from 0-10.
cvss3_score - the CVSS score 3 (as taken from NVD), values range from 0-10.
cvss3_severity - if cvss 3 score is between 0-3.9 - low, if cvss 3 score is between 4-6.9 - medium, if cvss 3 score is between 7-10 - high
scoreMetadataVector - a text representation of a set of CVSS metrics. See also related specification.
description - the vulnerability description.
publishDate - the publish date.
sourceFile - in case the vulnerability was matched to a source file, not the binary library, the sourceFile field will be populated (see details below).
Note: only libraries with type SOURCE_LIBRARY have source files.
vulnerabilityFix - the top fix of the vulnerability (see details below).
fixResolutionText - the actual resolution text to display for the given fix.

The 'vulnerabilityFix' and 'fixResolutionText' fields are populated only when there is an available fix.

Library Details Overview

type	groupId	artifactId	version	name	filename
ActionScript Alpine Arch Linux Debian Java Archive JavaScript javascript/Node.js Nuget Python RPM Ruby	Package name	Filename	Package version	Package name	Filename (taken from artifactId)
Java	Maven groupId	Maven artifactId	Maven version	Maven project name	artifactId + version + extension
javascript/Bower	Project owner	Package name	Package version	Package name	artifactId + version
.NET	Owner / Organization	.NET project name	Package version	.NET project name	artifactId + version + extension
Source Library	Project owner	SCM project name	Repository version / tag	artifactId + version	artifactId + version
Unknown Library	- If the artifact has owner, it will be displayed as groupId	filename + extension.	- Will be shown only in case the artifact has version when uploaded	filename + extension If the artifact has artifactId and version, the name will consist of them	Filename + extension

Source File

Each source file object has the following fields:

name - the name of the source file.
sha1 - the SHA-1 checksum.

Vulnerability Fix

Each vulnerability fix object has the following fields:

vulnerability - the name of the vulnerability (e.g. CVE-2008-0983).
type - the type of fix available, can be one of:
1. CHANGE_FILES
2. PATCH
3. UPGRADE_VERSION
vulnerabilityFixOrigin - the site, service or provider of the fix, can be one of:
1. GITHUB_COMMIT
2. JIRA
3. BUGZILLA
4. NODE_SECURITY_ADVISORY
5. PIVOTAL_VULNERABILITY_REPORT
6. FFMPEG_SECURITY
7. STRUTS_SECURITY_BULLETIN
8. XFORCE_VULNERABILITY_REPORT
9. SECURITY_TRACKER
10. WHITESOURCE_EXPERT - Used whenever a WhiteSource security researcher discovers that a vulnerability can be fixed by upgrading to a newer version, and there are no other sources for the vulnerability fix.
url - the URL of the fix.
fixResolution - the fix resolution. Depending on the origin the fixResolution field may vary:
1. GITHUB_COMMIT - comma separated file names to change.
2. JIRA - comma separated list of versions, e.g. “1.0.5,1.1.3”.
3. BUGZILLA - comma separated list of versions.
4. NODE_SECURITY_ADVISORY - text taken as-is from the origin, e.g. “>= 1.0.4” or “Upgrade to version 0.2.5 or greater.”
5. PIVOTAL_VULNERABILITY_REPORT - text taken as-is from the origin.
6. FFMPEG_SECURITY - comma separated list of versions.
7. STRUTS_SECURITY_BULLETIN - text taken as-is from the origin, e.g. “Developers should upgrade to Struts 2.0.12”.
8. XFORCE_VULNERABILITY_REPORT - text taken as-is from the origin, e.g. “Refer to ASA-2007-010 for patch, upgrade or suggested workaround information. See References.”.
9. SECURITY_TRACKER - text taken as-is from origin, e.g. “The vendor has issued a fix (2.3.17, 2.4.11).”.
date - publish date of the fix (not always available).
messsage - the title / description of the fix as taken from the origin.
extraData - extra data stored for each fix in key_1=value_1&key_2&value_2 pairs. Depending on the origin the extraData field may vary:
1. key - the short commit SHA-1.
2. committerName - the name of the committer.
3. committerUrl - a link to the committer’s page on GitHub.
4. committerAvatar - a link to the committer’s avatar.
5. key - the issue id.
6. assignee - the person assigned to the issue.
7. key - the issue id.
8. assignee - the person assigned to the issue.
9. key - the advisory id.
10. key - the report id, which is simply the CVE name.
11. key - the bulletin id.
12. key - the report id.
13. key - the alert id.
1. GITHUB_COMMIT
2. JIRA
3. BUGZILLA
4. NODE_SECURITY_ADVISORY
5. PIVOTAL_VULNERABILITY_REPORT
6. FFMPEG_SECURITY - no extra data available.
7. STRUTS_SECURITY_BULLETIN
8. XFORCE_VULNERABILITY_REPORT
9. SECURITY_TRACKER

Project State

SETUP - Initializing project.
DIFF - Calculating inventory changes.
UPDATE - Updating inventory.
CHANGE_EXCLUSIONS - Updating dependency exclusions.
CHANGE_LOCAL_PATHS - Updating library paths.
REMOVE - Removing libraries.
PARTNER_UPDATE - Updating inventory.
UPDATE_ALERTS - Updating alerts.
CREATE_ISSUES - Creating external tickets

Assignments

ADMIN
ALERTS_IGNORER
ALERT_EMAIL_RECEIVER
DEFAULT_APPROVER
LEGAL_ASSIGNER
USER
READ_ONLY