Skip to end of metadata
Go to start of metadata

Overview

The API is just a HTTP endpoint implementing a JSON speaking web service. Communication is secured with SSL like the service itself.

Currently the API supports these methods:

  • Register Organization
  • Register Product
  • Register User
  • Get All Organizations
  • Get All Products
  • Remove Organization
  • Remove Product
  • Rename Organization
  • Rename Product
  • Update Product Inventory
  • Get Product Summary
  • Get Product Vulnerabilities
  • Get Product RPM Vulnerabilities
  • Get Product Alpine Vulnerabilities
  • Get Product DEB Vulnerabilities
  • Get Product Unix Licenses
  • Get Product Licenses
  • Get Product License Histogram
  • Analyze Inventory

Endpoint

The service listens on saas.whitesourcesoftware.com/partner on both HTTP and HTTPS protocols.

Only POST requests are expected.

Each request should have the following headers:

  • Content-Type=application/json
  • Charset=UTF-8

Request Format

Some requests require a Partner token that will be provided offline (not through the API) via White Source.

Request Fields

Field nameValueRemarks
requestType

One of the following:

  • registerOrganization
  • registerProduct
  • registerUser
  • getAllOrganizations
  • getAllProducts
  • removeOrganization
  • removeProduct
  • renameOrganization
  • renameProduct
  • updateProductInventory
  • getProductSummary
  • getProductVulnerabilities
  • getProductAlpineVulnerabilities
  • getProductRpmVulnerabilities
  • getProductDebVulnerabilities
  • getProductUnixLicenses
  • getProductLicenses
  • getProductLicenseHistogram
 
partnerTokenYour partner API token 
orgTokenThe organization token generated when registering the organization 
productTokenThe product token generated when registering the product 
orgNameName of the organization to register 
productNameName of the product to register 
sha1sArray of sha1 values 
emailEmail address of the user to add to the organization 
description

A description of the product, may contain internal data such as id

Sent while registering or renaming a product

Optional

The requestType field is mandatory for each request

Response Fields

Field nameValue
orgTokenThe organization token generated when registering the organization
productTokenThe product token generated when registering the product
sha1sArray of sha1 values
vulnerabilityThe information regarding the security vulnerability
messageAn informative message describing the success of a request with no specific return value
errorCode

Integer for identifying the error

errorMessageAn error message describing the problem

 

The vulnerability format is:

ParameterValue
nameThe id in the vulnerability database (CVE or OSVDB)
typeEither CVE or OSVDB
descriptionA short description of the security vulnerability
scoreThe CVSS v2 base score [0.0 - 10.0]
severityOne of { low, medium, high }
publishDateOriginal release date in the following format: yyyy-MM-dd HH:mm

 

Errors are represented by an errorCode and errorMessage:

errorCodeerrorMessage

1000

Unsupported request type
1001Incorrect partner token
1002Incorrect organization token
1003Incorrect product token
2000Organization name occupied
2001Product name occupied
2002Partner unauthorized to perform this operation
3000Invalid request params
3001Invalid JSON format
3002Invalid request content-type
3003Problem reading request
3008Invalid parameter value
4000Unexpected error

 

These are the various types of methods available through the API:

MethodRequired FieldsReturn Values
Register OrganizationPartner token

Organization token

Register Product

Org token

Product name

Product token

Register User

Org token

User email

Confirmation message
Get All OrganizationsPartner tokenMap of organization names and their tokens
Get All ProductsOrg tokenMap of product names and their tokens
Remove Organization

Partner token

Org token

Confirmation message
Remove Product

Product token

Confirmation message
Rename OrganizationOrg tokenConfirmation message
Rename ProductProduct tokenConfirmation message
Update Product Inventory

Product token

SHA1 list

Confirmation message describing the number of libraries added and removed after the update process
Get Product SummaryProduct tokenTotal libraries, high vulnerable libraries, medium vulnerable libraries, low vulnerable libraries, non vulnerable libraries, total vulnerable and updated, total vulnerable and outdated
Get Product Vulnerabilities

Product token

List of security vulnerabilities for each SHA1 found in the product's inventory
Get Product RPM Vulnerabilities

Product token

RPM filename list

List of security vulnerabilities for each filename sent in the request
Get Product Alpine Vulnerabilities

Product token

Alpine filename list

List of security vulnerabilities for each filename sent in the request
Get Product Licenses

Product token

List of licenses for each SHA1 found in the product's inventory
Get Product Unix licensesProduct tokenList of licenses for each filename sent in the request
Get Product License HistogramProduct tokenMap of licenses and their occurrences
Replace Organization TokenOrg TokenA new Organization Token

Request Types

Register Organization

Request

Response

 

Register Product

Request

Request (with description)

Response

 

Register User

Request

Response

 

Update Product Inventory

You will only need to send SHA1s once to the WhiteSource server in order to update and persist the inventory of each product. Afterwards getting the product licenses and vulnerabilities will be done using only the productToken.

Request

Response


Alternative Request

You can also send just the sha1s without the file names, this will result in slower performance.

Old Response

 

Get Product Summary

Request

Response

The totalHighVulnerabilities counts the number of (High-Severity Vulnerability, Library) pairs (for example, if vulnerability CVE-2014-0114 effects 3 libraries it will be counted 3 times).

The totalMediumVulnerabilities counts the number of (Medium-Severity Vulnerability, Library) pairs.

The totalLowVulnerabilities counts the number of (Low-Severity Vulnerability, Library) pairs.

The vulnerabilityScore field can be high, medium, low or secure.

 

Get Product Vulnerabilities

Request

This request has been changed and currently doesn't accept a list of SHA1s, use updateProductInventory before sending this request

Response

View the structure of each Vulnerability and VulnerabilityFix.

Get Product RPM Vulnerabilities

Inventory is not stored for this request type

Request

This request will only yield results for .rpm / .drpm / .src.rpm files

Response

Get Product Alpine Vulnerabilities

Inventory is not stored for this request type

Request

This request will only yield results for .apk

Response

Get Product DEB Vulnerabilities

Inventory is not stored for this request type

Request

This request requires the debian Os release code name as described in https://www.debian.org/releases/ (i.e jessie, wheezy etc...)

This request will only yield results for .deb files.

Response

A response with a vulnerability might have an empty description and an empty severity which will be marked as -1.

Get Product Licenses

Request

This request has been changed and currently doesn't accept a list of SHA1s, use updateProductInventory before sending this request

Response

Get Product Unix licenses

Request

Response

Get Product License Histogram

Request

Response

Get Product Risk Report

Request

Response

The response JSON format is explained below: ResponseStructure.

Get All Organizations

Request

Response

 

Get All Products

Request

Response

 

Remove Organization

Request

Response

 

Remove Product

Request

Response

 

Rename Organization

Request

Response

Rename Product

Request

Request (with description)

Response

 

Analyze Inventory

Send an array of SHA1 File name pairs and receive an analysis result with License and URL of the file.

Request

Response

The response returns an array of analysis results, each object has the following fields:

NameValueOptional
sha1The sha1 checksum of the analyzed fileNo
urlDownload link for binary files, repository link for source filesYes
licensesAn array of license namesYes
resultIf the file was not matched in any known open source index the value is "no match"Yes

Replace Organization Token

Request

Response

Response Structure

Vulnerability

Each vulnerability object has the following fields:

  1. name - the name of the vulnerability (e.g. CVE-2008-0983).

  2. severity - the CVSS severity (as taken from NVD), can be one of:

    1. HIGH

    2. MEDIUM

    3. LOW

  3. score - the CVSS score (as taken from NVD), values range from 0-10.

  4. description - the vulnerability description.

  5. publishDate - the publish date.

  6. 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 or SOURCE_FILE_CLUSTER have source files.

  7. vulnerabilityFix - the top fix of the vulnerability (see details below).

  8. fixResolutionText - the actual resolution text to display for the given fix.

 

Only if there's an available fix for will the vulnerabilityFix and fixResolutionText fields be populated.

 

Source File

Each source file object has the following fields:

  1. name - the name of the source file.

  2. sha1 - the SHA-1 checksum.

Vulnerability Fix

Each vulnerability fix object has the following fields:

  1. vulnerability - the name of the vulnerability (e.g. CVE-2008-0983).

  2. type - the type of fix available, can be one of:

    1. CHANGE_FILES

    2. PATCH

    3. UPGRADE_VERSION

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

  4. url - the url of the fix.

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

  6. date - publish date of the fix (not always available).

  7. messsage - the title / description of the fix as taken from the origin.

  8. 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. GITHUB_COMMIT

      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.

    2. JIRA

      1. key - the issue id.

      2. assignee - the person assigned to the issue.

    3. BUGZILLA

      1. key - the issue id.

      2. assignee - the person assigned to the issue.

    4. NODE_SECURITY_ADVISORY

      1. key - the advisory id.

    5. PIVOTAL_VULNERABILITY_REPORT

      1. key - the report id, which is simply the CVE name.

    6. FFMPEG_SECURITY - no extra data available.

    7. STRUTS_SECURITY_BULLETIN

      1. key - the bulletin id.

    8. XFORCE_VULNERABILITY_REPORT

      1. key - the report id.

    9. SECURITY_TRACKER

      1. key - the alert id.

Workflow

  1. Register an organization using your partnerToken and receive its orgToken.
  2. Register a product using the orgToken and receive its productToken.
  3. Update the product's inventory using the productToken and a list of SHA1s.
  4. Get product licenses and vulnerabilities using only the productToken.
Labels
  • None