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

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.

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.

Regarding version numbers, if there are 3 or more version parts, (for example, 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.

NOTE: The previous WhiteSource API version is currently still supported, and is documented in the HTTP API v1.2 page.

Note the following about API calls:

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.
Date format in all responses is "yyyy-MM-dd".
None of the API results are sorted in any order.

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

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 parameter is mandatory for all requests.

Parameter	Description
requestType	For details, see Supported Requests.
orgToken	Your organization API key
productToken	A unique identifier for your product
projectToken	A unique identifier for your project

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 Requests

WhiteSource HTTP API v1.3 supports the following requests:

        "addGlobalOrganizationPolicy",
        "addOrganizationPolicy",
        "addProductPolicy",
        "addProjectPolicy",
        "addUsersToGroups",
        "changeOriginLibrary",
        "clearOrganizationSourceFileMatchingResults",
        "clearProductSourceFileMatchingResults",
        "clearProjectSourceFileMatchingResults",
        "createGlobalOrg",
        "createGroup",
        "createProduct",
        "createProject",
        "createServiceUser",
        "createUser",
        "deleteProduct",
        "deleteProject",
        "fetchProjectPolicyIssues",
        "getAggregatedFix",
        "getAggregatedLibraryDetails",
        "getAlertsByProjectTag",
        "getAllGroups",
        "getAllOrganizations",
        "getAllProducts",
        "getAllProjects",
        "getAllUsers",
        "getChangeLogHistoryReport",
        "getChangesReport",
        "getClusterVulnerabilityReportRequest",
        "getCopyrightsTextFile",
        "getDirectDependencyVersion",
        "getGlobalLicenses",
        "getGlobalOrganizationPolicies",
        "getIntegrationActivationToken",
        "getIntegrationWorkflowRules",
        "getLibraryInfo",
        "getLibraryLicenses",
        "getLibrarySourceFiles",
        "getLibraryVulnerabilities",
        "getLicensesByPackageCoordinates",
        "getLicensesTextZip",
        "getNoticesTextFile",
        "getOrganizationAlerts",
        "getOrganizationAlertsByType",
        "getOrganizationAlertsReport",
        "getOrganizationAssignments",
        "getOrganizationAttributesReport",
        "getOrganizationBugsReport",
        "getOrganizationCapabilities",
        "getOrganizationContainerVulnerabilityReportRequest",
        "getOrganizationCustomAttributeValues",
        "getOrganizationDetails",
        "getOrganizationDueDiligenceReport",
        "getOrganizationEarlyWarningAlertReport",
        "getOrganizationEarlyWarningReport",
        "getOrganizationEffectiveLicensesReport",
        "getOrganizationEffectiveUsageAnalysis",
        "getOrganizationFileClustersReport",
        "getOrganizationIgnoredAlerts",
        "getOrganizationIgnoredAlertsReport",
        "getOrganizationInHouseLibraries",
        "getOrganizationInHouseReport",
        "getOrganizationInventoryReport",
        "getOrganizationLastModifiedProjects",
        "getOrganizationLibraryLocationReport",
        "getOrganizationLicenseAndComplianceAlertReport",
        "getOrganizationLicenseHistogram",
        "getOrganizationLicenses",
        "getOrganizationMembersReport",
        "getOrganizationPolicies",
        "getOrganizationProductTags",
        "getOrganizationProductVitals",
        "getOrganizationProjectTags",
        "getOrganizationProjectVitals",
        "getOrganizationRequestHistoryReport",
        "getOrganizationResolvedAlertsReport",
        "getOrganizationRiskReport",
        "getOrganizationSecurityAlertsByLibraryReport",
        "getOrganizationSecurityAlertsByVulnerabilityReport",
        "getOrganizationServiceUsers",
        "getOrganizationSourceFileInventoryReport",
        "getOrganizationVulnerabilityReport",
        "getPluginRequestHistoryReport",
        "getPolicyMatchesConfiguration",
        "getPolicyViolationHistoryReport",
        "getProductAlerts",
        "getProductAlertsByType",
        "getProductAlertsReport",
        "getProductAssignments",
        "getProductAttributesReport",
        "getProductAttributionReport",
        "getProductBugsReport",
        "getProductComparisonReport",
        "getProductCustomAttributeValues",
        "getProductDueDiligenceReport",
        "getProductEarlyWarningAlertReport",
        "getProductEarlyWarningReport",
        "getProductEffectiveLicensesReport",
        "getProductFileClustersReport",
        "getProductIgnoredAlerts",
        "getProductIgnoredAlertsReport",
        "getProductInHouseLibraries",
        "getProductInHouseReport",
        "getProductInventoryReport",
        "getProductLibraryLocationReport",
        "getProductLibraryLocations",
        "getProductLicenseAndComplianceAlertReport",
        "getProductLicenseCompatibilityReport",
        "getProductLicenseHistogram",
        "getProductLicenses",
        "getProductMembersReport",
        "getProductPolicies",
        "getProductProjectTags",
        "getProductProjectVitals",
        "getProductRequestHistoryReport",
        "getProductResolvedAlertsReport",
        "getProductRiskReport",
        "getProductSecurityAlertsByLibraryReport",
        "getProductSecurityAlertsByVulnerabilityReport",
        "getProductServiceUsers",
        "getProductSourceFileInventoryReport",
        "getProductTags",
        "getProductVulnerabilityReport",
        "getProjectAlerts",
        "getProjectAlertsByType",
        "getProjectAlertsReport",
        "getProjectAttributionReport",
        "getProjectBugsReport",
        "getProjectComparisonReport",
        "getProjectCopyrightsTextFile",
        "getProjectCustomAttributeValues",
        "getProjectDirectDependencies",
        "getProjectDueDiligenceReport",
        "getProjectEarlyWarningAlertReport",
        "getProjectEarlyWarningReport",
        "getProjectHierarchy",
        "getProjectIgnoredAlerts",
        "getProjectIgnoredAlertsReport",
        "getProjectInHouseLibraries",
        "getProjectInHouseReport",
        "getProjectInventory",
        "getProjectInventoryReport",
        "getProjectLibrariesInfo",
        "getProjectLibraryDependencies",
        "getProjectLibraryLocations",
        "getProjectLicenseAndComplianceAlertReport",
        "getProjectLicenseCompatibilityReport",
        "getProjectLicenseHistogram",
        "getProjectLicenses",
        "getProjectLicensesTextZip",
        "getProjectMembersReport",
        "getProjectPolicies",
        "getProjectRequestHistoryReport",
        "getProjectResolvedAlertsReport",
        "getProjectRiskReport",
        "getProjectSecurityAlertsByLibraryReport",
        "getProjectSecurityAlertsByVulnerabilityReport",
        "getProjectSourceFileInventoryReport",
        "getProjectState",
        "getProjectTags",
        "getProjectVitals",
        "getProjectVulnerabilityReport",
        "getRequestSchema",
        "getRequestState",
        "getServerCapabilities",
        "getSupportedRequests",
        "getVulnerabilitiesByFilename",
        "getVulnerabilitiesByHashes",
        "getVulnerabilitiesByPackageCoordinates",
        "getVulnerabilityProfiles",
        "hasBlockPolicy",
        "ignoreAlerts",
        "inviteUserToWebAdvisor",
        "inviteUsers",
        "librarySearch",
        "reassignPendingTasksAndConditions",
        "regenerateUserKey",
        "removeGlobalOrganizationPolicies",
        "removeOrganizationPolicies",
        "removeProductPolicies",
        "removeProductTag",
        "removeProjectPolicies",
        "removeProjectTag",
        "removeUserFromGroup",
        "removeUserFromOrganization",
        "renameProduct",
        "reorderGlobalOrganizationPolicyPriorities",
        "reorderOrganizationPolicyPriorities",
        "reorderProductPolicyPriorities",
        "reorderProjectPolicyPriorities",
        "saveProductTag",
        "saveProjectTag",
        "setAlertsStatus",
        "setGlobalOrganizationPolicyStates",
        "setLibraryNotice",
        "setOrganizationAssignments",
        "setOrganizationPolicyStates",
        "setProductAssignments",
        "setProductPolicyStates",
        "setProjectPolicyStates",
        "setProjectSetupNotificationConfig",
        "unmarkManualInHouseLibrary",
        "updateExternalIntegrationIssues",
        "updateGlobalOrganizationPolicy",
        "updateGlobalSamlIntegration",
        "updateMavenDependencyResolutionSettings",
        "updateOrganizationPolicy",
        "updateOrganizationSamlIntegration",
        "updateProductPolicy",
        "updateProjectPolicy"

For documentation of API requests that relate to:

Policies, see Policies API
Alerts, see Alerts API
Groups and Users, see Groups and Users API
Reports, see Reports API
Licenses and Libraries, see Licenses and Library API
Global Orgs/Organizations/Products/Projects, see Global Org/Organization/Product/Project API
Products and Projects, see Product and Project-Level API

Vulnerability-Based Alerts

The following APIs are only available in an 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

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 the following:
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

HTTP API v1.3 (update in progress)