HTTP API
Overview
To access the new and recommended version of the WhiteSource HTTP API, use HTTP API v1.1.
This document describes the old version of the WhiteSource HTTP API. 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 '/api' path to it. For example: https://saas.whitesourcesoftware.com/api.
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.
Currently, the 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
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
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
- Get Organization Risk Report
- Get Product Risk Report
- Get Change Log History Report
- Get Organization Inventory Report
- Get Product Inventory Report
- Get Project Inventory Report
- Get Organization Vulnerability Report
- Get Product Vulnerability Report
- Get Project Vulnerability Report
- Get Organization Container Vulnerability Report
- Get Cluster Vulnerability Report
- Get Organization Source File Inventory Report
- Get Product Source File Inventory Report
- Get Organization Alerts Report
- Get Product Alerts Report
- Get Project Alerts Report
- Get Organization Attributes Report
- Get Product Attributes Report
- Get Organization Library Location Report
- Get Product Library Location Report
- Get Organization Due Diligence Report
- Get Product Due Diligence Report
- Get Organization Effective Licenses Report
- Get Product Effective Licenses Report
- Get Organization Bugs Report
- Get Product Bugs Report
- Get Project Bugs Report
- Get Organization Ignored Alerts Report
- Get Product Ignored Alerts Report
- Get Project Ignored Alerts Report
- Get Organization Resolved Alerts Report
- Get Product Resolved Alerts Report
- Get Project Resolved Alerts Report
- Get Organization Request History Report
- Get Product Request History Report
- Get Project Request History Report
- Get Organization Members Report
- Get Product Members Report
- Get Project Members Report
- Get Plugin Request History Report
- Get Product Comparison Report
Library Locations
- Get Product Library Locations
- Get Project Library Locations
Policies
- Get Organization Policies
- Get Product Policies
- Add Organization Policy
- Add Product Policy
- Update Organization Policy
- Update Product Policy
- Remove Organization Policies
- Remove Product Policies
- Reorder Organization Policy Priorities
- Reorder Product Policy Priorities
- Get Licenses
Groups and Users
- Create Group
- Create User
- Invite User
- Get All Groups
- Get All users
- Get Organization Assignments
- Get Product Assignments
- Set Organization Assignments
- Set Product Assignments
- Add Users to Groups
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
Endpoint
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
- charset=UTF-8
API Format
All requests require a token available via the API Integration page in your White Source account, according to the request's context (organization / product / project).
Fields
Field name | Value |
---|---|
requestType | One of the following:
|
orgToken | Your organization API key |
userKey | Your user key (can be obtained from your Profile page) |
productToken | A unique identifier for your product |
projectToken | A unique identifier for your project |
alertType | One of the following:
|
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.
Alerts
Get all alerts for a given organization / product / project.
Organization
Product
Project
Get Alerts by Project Tags
Response Format when Direct Dependency
Response Format with Transitive Dependency
Security Vulnerability alerts will also contain the following object:
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 |
description | A short description of the security vulnerability |
score | The CVSS v2 base score [0.0 - 10.0] |
severity | One of { low, medium, high } |
publishDate | Original release date |
Alerts by Type
Get all alerts of a certain type for a given organization / product / project.
Organization
Product
Project
Response Format
Licenses
Get all libraries and their licenses for a given organization / product / project.
Organization
Product
Project
Response Format
License Histogram
Get the license histogram (license name : occurrence) for a given organization / product / project.
Organization
Product
Project
Response Example
Get All Products
Receives an orgToken and returns all products in the organization; name and token of each.
Request
Response
Get All Projects
Receives a productToken and returns all projects in the product; name and token of each.
Request
Response
Project / Product Vitals
Get basic information regarding a project: name, token, creation date and last updated date.
Project
Organization
Product
Project
Response
Product
Organization
Response
Project Tags
Get project tags: key, value.
Organization
Product
Project
Response
Save Project Tags
Save project tags by key, value.
Project
Response
Licenses Text Zip
Get the licenses terms and conditions text files contained in a single zip file.
Product
Response
The response will have the following headers:
- Content-Type = application/zip
- Content-Disposition: attachment; filename=product_name-licenses.zip
Copyrights Text File
Get the copyrights text files.
Product
Response
The response will have the following headers:
- Content-Type = text/plain
- Content-Disposition: attachment; filename=product_name-copyrights.zip
Notices Text File
Get the notices text files.
Product
Response
The response will have the following headers:
- Content-Type = text/plain
- Content-Disposition: attachment; filename=product_name-notices.zip
Risk Report
Get organization or product level risk reports in PDF format.
Organization
Response
The response will have the following headers:
- Content-Type = application/pdf
- Content-Disposition: attachment; filename=<organization name>.pdf
Product
Response
The response will have the following headers:
- Content-Type = application/pdf
- Content-Disposition: attachment; filename=<product name>.pdf
Project
Response
The response will have the following headers:
- Content-Type = application/pdf
- Content-Disposition: attachment; filename=<project name>.pdf
Inventory Report
Get organization, product or project level inventory reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Project
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<project name>.xslx
Change Log Report
Get organization level Change Log Report in various formats.
Request
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: 'mm/dd/yyyy hh:mm:ss'.
Response
Vulnerability Report
Get organization, product or project level vulnerability reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Project
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<project name>.xslx
Container Vulnerability Report
Get organization or cluster level container vulnerability reports in Excel or JSON format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Cluster
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<cluster name>.xslx
Source File Inventory Report
Get organization or product level source file inventory reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Alerts Report
Get organization, product or project level alerts reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Project
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<project name>.xslx
Attributes Report
Get organization or product level attributes reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Library Location Report
Get organization or product level library location reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Due Diligence Report
Get organization or product level due diligence reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Effective Licenses Report
Get organization or product level effective licenses reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Bugs Report
Get organization, product or project level bugs reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Project
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<project name>.xslx
Ignored Alerts Report
Get organization, product or project level ignored alerts reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Project
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<project name>.xslx
Resolved Alerts Report
Get organization, product or project level resolved alerts reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Project
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<project name>.xslx
Request History Report
Get organization, product or project level request history reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Project
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<project name>.xslx
Members Report
Get organization, product or project level members reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product name>.xslx
Project
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<project name>.xslx
Plugin Request History Report
Get organization level plugin request history reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<organization name>.xslx
Product Comparison Report
Get organization level product comparison reports in Excel format.
Organization
Response
The response will have the following headers:
- Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- Content-Disposition: attachment; filename=<product>-<product2>-product-comparison.xslx
Library Locations
Product
Response Format
Project
Response Format
Policies
See Policies API for documentation.
Groups and Users
Create Group
Response Format
Create user
Response Format
Invite Users
Response Format
Get All Groups
Response Format
Get All users
Response Format
Add Users to Groups
Response Format
Get Organization Assignments
Response Format
Get Product Assignments
Response Format
Set Organization Assignments
Response Format
Set Product Assignments
Response Format
Role Types
Organization Roles |
|
Product Roles |
|
Project Create / Delete
Create Project
Response Format
Delete Project
Response Format
Product Create / Delete
Create Product
Response Format
Delete Product
Response Format
Project Requests
Get Project Hierarchy
Response Format
Get Project Inventory
Response Format
Get Project State
Response Format
Get Library Source Files
Response Format
Get Project Library Dependencies
Response Format
Plugin Request State
Get Request State
Response Format
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
The timestamp field is in UTC format.
The requestToken (also displated 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
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:
HIGH
MEDIUM
LOW
score - the CVSS score (as taken from NVD), values range from 0-10.
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.
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:
CHANGE_FILES
PATCH
UPGRADE_VERSION
vulnerabilityFixOrigin - the site, service or provider of the fix, can be one of:
GITHUB_COMMIT
JIRA
BUGZILLA
NODE_SECURITY_ADVISORY
PIVOTAL_VULNERABILITY_REPORT
FFMPEG_SECURITY
STRUTS_SECURITY_BULLETIN
XFORCE_VULNERABILITY_REPORT
SECURITY_TRACKER
- 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:
GITHUB_COMMIT - comma separated file names to change.
JIRA - comma separated list of versions, e.g. “1.0.5,1.1.3”.
BUGZILLA - comma separated list of versions.
NODE_SECURITY_ADVISORY - text taken as-is from the origin, e.g. “>= 1.0.4” or “Upgrade to version 0.2.5 or greater.”
PIVOTAL_VULNERABILITY_REPORT - text taken as-is from the origin.
FFMPEG_SECURITY - comma separated list of versions.
STRUTS_SECURITY_BULLETIN - text taken as-is from the origin, e.g. “Developers should upgrade to Struts 2.0.12”.
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.”.
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:
key - the short commit SHA-1.
committerName - the name of the committer.
committerUrl - a link to the committer’s page on GitHub.
committerAvatar - a link to the committer’s avatar.
key - the issue id.
assignee - the person assigned to the issue.
key - the issue id.
assignee - the person assigned to the issue.
key - the advisory id.
key - the report id, which is simply the CVE name.
key - the bulletin id.
key - the report id.
- key - the alert id.
GITHUB_COMMIT
JIRA
BUGZILLA
NODE_SECURITY_ADVISORY
PIVOTAL_VULNERABILITY_REPORT
FFMPEG_SECURITY - no extra data available.
STRUTS_SECURITY_BULLETIN
XFORCE_VULNERABILITY_REPORT
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