API capability requires an additional WhiteSource license. Contact your CSM for more details. |
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.0. 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.0' to it. For example: https://saas.whitesourcesoftware.com/api/v1.0.
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.
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:
WhiteSource HTTP API v1.x supports Accept-Charset header.
If the value of the header is a supported charset (see supported values below) the response would be in that charset.
Otherwise, if the value is not supported or the header isn't sent, the default response character set will be UTF-8.
Supported character sets:
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 only execute API calls related to their Projects/Products that are defined in WhiteSource, but they cannot execute Organization related API calls which are outside of their scope. There are two API calls that do not follow this rule:
WhiteSource HTTP API supports the following methods:
Alerts
Alerts by Type
Change Log
Licenses
License Histogram
Project / Product Vitals
Project Tags
Misc.
Reports
Library Locations
Policies
Groups and Users
Project Create / Delete
Product Create / Delete
Project API Requests
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 If the 'Enforce user level access' option is enabled inside the 'Integrate' page, then the userKey field is also mandatory for all requests. |
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.
Date format in all responses is "yyyy-MM-dd". None of the results are sorted in any order. |
Get all alerts for a given organization / product / project.
Organization
{ "requestType" : "getOrganizationAlerts", "orgToken" : "organization_api_key" } |
Product
{ "requestType" : "getProductAlerts", "productToken" : "product_token" } |
Project
{ "requestType" : "getProjectAlerts", "projectToken" : "project_token" } |
Get Alerts by Project Tags
{ "requestType" : "getAlertsByProjectTag", "orgToken" : "product_token", "tagKey":"key1", "tagValue":"value1" } |
Response Format when Direct Dependency
""alerts" : [ { "type" : "alert_type", "level" : "alert_level", "library": { "keyUuid": "library_unique_id", "filename": "library_file_name", "name": "library_name", "groupId": "library_group_id", "artifactId": "library_artifact_id", "version": "library_version", "sha1": "library_sha1", "type": "library_type", "references": { "url": "library_url", "pomUrl": "library_pom_url", "scmUrl": "library_scm_url" }, "licenses": [ { "name": "library_license_name", "url": "library_license_url", "profileInfo": { "copyrightRiskScore": "library_license_copyright_risk_score", "patentRiskScore": "library_patent_risk_score", "copyleft": "library_license_patent_copyleft", "linking": "library_license_linking", "royaltyFree": "library_license_royalty_free" } } ] }, "project" : "project_name", "directDependency": true, "description" : "alert_description", "date" : "alert_creation_date", "time" : "alert_creation_time_in_epoch_format" } ] |
Response Format with Transitive Dependency
"alerts" : [ { "type" : "alert_type", "level" : "alert_level", "library": { "keyUuid": "library_unique_id", "filename": "library_file_name", "name": "library_name", "groupId": "library_group_id", "artifactId": "library_artifact_id", "version": "library_version", "sha1": "library_sha1", "type": "library_type", "references": { "url": "library_url", "pomUrl": "library_pom_url", "scmUrl": "library_scm_url" }, "licenses": [ { "name": "library_license_name", "url": "library_license_url", "profileInfo": { "copyrightRiskScore": "library_license_copyright_risk_score", "patentRiskScore": "library_patent_risk_score", "copyleft": "library_license_patent_copyleft", "linking": "library_license_linking", "royaltyFree": "library_license_royalty_free" } } ] }, "project" : "project_name", "directDependency": false, "description" : "alert_description", "date" : "alert_creation_date", "time" : "alert_creation_time_in_epoch_format" } ] |
Alert level is either minor or major. |
Security Vulnerability alerts will also contain the following object:
"vulnerability" : { "name" : "vulnerability_name", "type" : "vulnerability_type", "description" : "vulnerability_description", "score" : cvss_2_vulnerability_score, "cvss3_score" : cvss_3_vulnerability_score, "cvss3_severity": "cvss 3 score severity", "scoreMetadataVector" : "cvss_3_metadata_vector", "severity" : "vulnerability_severity", "publishDate" : "vulnerability_publish_date" } |
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] |
cvss3_score | The CVSS v3 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 |
scoreMetadataVector | See specification link |
severity | One of { low, medium, high } |
publishDate | Original release date |
Get all alerts of a certain type for a given organization / product / project.
'fromDate' and 'toDate' are optional filtering fields. The format of these fields is either with or without time ('yyyy-MM-dd' or 'yyyy-MM-dd hh:mm:ss'). When 'fromDate' is not specified, it will be treated as the beginning of time. |
Organization
{ "requestType" : "getOrganizationAlertsByType", "alertType" : "alert_type", "orgToken" : "organization_api_key", "fromDate" : "2016-01-01 10:00:00", "toDate" : "2016-01-02 10:00:00" } |
Product
{ "requestType" : "getProductAlertsByType", "alertType" : "alert_type", "productToken" : "product_token", "fromDate" : "2016-01-01 11:00:31", "toDate" : "2016-01-02 11:00:31" } |
Project
{ "requestType" : "getProjectAlertsByType", "alertType" : "alert_type", "projectToken" : "project_token", "fromDate" : "2016-01-01 11:00:00", "toDate" : "2016-01-02 11:00:00" } |
Response Format
Same as alerts response |
Get organization level Change Log Report in various formats.
Request
{ "userKey": "user_key", "orgToken": "organization_api_key", "requestType": "getChangesReport", "startDateTime": "01/01/2018 10:02:00 } |
Optional Parameters
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 all libraries and their licenses for a given organization / product / project.
Organization
{ "requestType" : "getOrganizationLicenses", "orgToken" : "organization_api_key" } |
Product
{ "requestType" : "getProductLicenses", "productToken" : "product_token" } |
Project
{ "requestType" : "getProjectLicenses", "projectToken" : "project_token" } |
Response Format
"libraries" : [ { "licenses" : [ "license_name_1", "license_name_2" ], "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 the license histogram (license name : occurrence) for a given organization / product / project.
Organization
{ "requestType" : "getOrganizationLicenseHistogram", "orgToken" : "organization_api_key" } |
Product
{ "requestType" : "getProductLicenseHistogram", "productToken" : "product_token" } |
Project
{ "requestType" : "getProjectLicenseHistogram", "projectToken" : "project_token" } |
Response Example
{ "licenseHistogram" : { "Apache 2.0" : 2, "BSD 3" : 2, "GPL 3.0" : 1, } } |
Receives an orgToken and returns all products in the organization; name and token of each.
Request
{ "requestType":"getAllProducts", "orgToken":"org_token" } |
Response
{ "products": [ { "productName": "Product A", "productToken": "product_a_token" }, { "productName": "Product B", "productToken": "product_b_token" } ], "message": "Success" } |
Receives a productToken and returns all projects in the product; name and token of each.
Request
{ "requestType":"getAllProjects", "productToken":"product_token" } |
Response
{ "projects": [ { "projectName": "project_a", "projectToken": "project_a_token" }, { "projectName": "project_b", "projectToken": "project_b_token" } ], "message": "Success" } |
Get basic information regarding a project: name, token, creation date and last updated date.
Project
Organization
{ "requestType" : "getOrganizationProjectVitals", "orgToken" : "organization_api_key" } |
Product
{ "requestType" : "getProductProjectVitals", "productToken" : "product_token" } |
Project
{ "requestType" : "getProjectVitals", "projectToken" : "project_token" } |
Response
{ "projectVitals":[ { "pluginName":"fs-agent:18.2.2", "name": "My Project", "token": "project_token", "creationDate": "2016-01-01 12:00:00", "lastUpdatedDate": "2016-02-02 16:50:59" } ] } |
Product
Organization
{ "requestType" : "getOrganizationProductVitals", "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" } ] } |
Get project tags: key, value.
Organization
{ "requestType" : "getOrganizationProjectTags", "orgToken" : "organization_api_key" } |
Product
{ "requestType" : "getProductProjectTags", "productToken" : "product_token" } |
Project
{ "requestType" : "getProjectTags", "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 returned as well |
Save project tags by key, value.
Project
{ "requestType" : "saveProjectTag", "projectToken" : "project_token", "tagKey":"key1", "tagValue":"value1" } |
Response
{ "projectTags": { "name": "My Project 1", "token": "project_token_1", "tags": { "key1": "value1" } } } |
Get the licenses terms and conditions text files contained in a single zip file.
This request is available only for products |
Product
{ "requestType" : "getLicensesTextZip", "productToken" : "product_token" } |
Response
The response will have the following headers:
The response is a zip file, not a json formatted message |
Get the copyrights text files.
This request is available only for products |
Product
{ "requestType" : "getCopyrightsTextFile", "productToken" : "product_token" } |
Response
The response will have the following headers:
Get the notices text files.
This request is available only for products |
Product
{ "requestType" : "getNoticesTextFile", "productToken" : "product_token" } |
Response
The response will have the following headers:
Get organization or product level risk reports in PDF format.
This request is available for organizations or products |
Organization
{ "requestType" : "getOrganizationRiskReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductRiskReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectRiskReport", "projectToken" : "project_token" } |
Response
The response will have the following headers:
Get organization, product or project level inventory reports in Excel (xlsx) or JSON (json) format.
This request is available for organizations, products or projects. |
Organization
{ "requestType" : "getOrganizationInventoryReport", "orgToken" : "organization_api_key", "format" : "json" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductInventoryReport", "productToken" : "product_token", "format" : "xlsx" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectInventoryReport", "projectToken" : "project_token" "format" : "xlsx" } |
Response
The response will have the following headers:
Get organization level Change Log in Excel format.
Request
{ "userKey": "user_key", "orgToken": "organization_api_key", "requestType":"getChangeLogHistoryReport" } |
Response
The response will have the following headers:
Get organization, product or project level vulnerability reports in Excel format.
This request is available for organizations, products or projects. An 'xlsx' format is used when no 'format' parameter is provided. |
Organization
{ "requestType" : "getOrganizationVulnerabilityReport", "orgToken" : "organization_api_key", "format" : "xlsx" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductVulnerabilityReport", "productToken" : "product_token", "format" : "json" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectVulnerabilityReport", "projectToken" : "project_token", "format" : "xlsx" } |
Response
The response will have the following headers:
Get organization or cluster level container vulnerability reports in Excel or JSON format.
This request is available for the organization and cluster level. An 'xlsx' format is used when no 'format' parameter is provided. |
Organization
{ "requestType" : "getOrganizationContainerVulnerabilityReport", "orgToken" : "org_token", "format" : "xlsx" } |
Response
The response will have the following headers:
Cluster
{ "requestType" : "getClusterVulnerabilityReport", "productToken" : "product_token", "format" : "json" } |
Response
The response will have the following headers:
Get organization, product or project level source file inventory reports in Excel (xlsx) or JSON (json) format.
This request is available for organizations, products or projects. |
Organization
{ "requestType" : "getOrganizationSourceFileInventoryReport", "orgToken" : "organization_api_key", "format" : "json" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductSourceFileInventoryReport", "productToken" : "product_token", "format" : "json" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectSourceFileInventoryReport", "projectToken" : "project_token", "format" : "xlsx" } |
Response
The response will have the following headers:
Get organization, product or project level alerts reports in Excel format.
This request is available for organizations, products or projects. An 'xlsx' format is used when no 'format' parameter is provided. |
Organization
{ "requestType" : "getOrganizationAlertsReport", "orgToken" : "organization_api_key", "format" : "xlsx" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductAlertsReport", "productToken" : "product_token", "format" : "json" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectAlertsReport", "projectToken" : "project_token", "format" : "xlsx" } |
Response
The response will have the following headers:
Get organization or product level attributes reports in Excel format.
This request is available for organizations or products |
Organization
{ "requestType" : "getOrganizationAttributesReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductAttributesReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Get organization or product level library location reports in Excel format.
This request is available for organizations or products |
Organization
{ "requestType" : "getOrganizationLibraryLocationReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductLibraryLocationReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Get organization or product level due diligence reports in Excel (xlsx) or JSON (json) format.
This request is available for organizations, products or projects. |
Organization
{ "requestType" : "getOrganizationDueDiligenceReport", "orgToken" : "organization_api_key", "format" : "xlsx" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductDueDiligenceReport", "productToken" : "product_token", "format" : "json" } |
Response
The response will have the following headers:
Get organization or product level effective licenses reports in Excel format.
This request is available for organizations or products |
Organization
{ "requestType" : "getOrganizationEffectiveLicensesReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductEffectiveLicensesReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Get organization, product or project level bugs reports in Excel format.
This request is available for organizations, products or projects |
Organization
{ "requestType" : "getOrganizationBugsReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductBugsReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectBugsReport", "projectToken" : "project_token" } |
Response
The response will have the following headers:
Get organization, product or project level ignored alerts reports in Excel format.
This request is available for organizations, products or projects |
Organization
{ "requestType" : "getOrganizationIgnoredAlertsReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductIgnoredAlertsReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectIgnoredAlertsReport", "projectToken" : "project_token" } |
Response
The response will have the following headers:
Get organization, product or project level resolved alerts reports in Excel format.
This request is available for organizations, products or projects |
Organization
{ "requestType" : "getOrganizationResolvedAlertsReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductResolvedAlertsReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectResolvedAlertsReport", "projectToken" : "project_token" } |
Response
The response will have the following headers:
Get organization, product or project level request history reports in Excel format.
This request is available for organizations, products or projects |
Organization
{ "requestType" : "getOrganizationRequestHistoryReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductRequestHistoryReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectRequestHistoryReport", "projectToken" : "project_token" } |
Response
The response will have the following headers:
Get organization, product or project level members reports in Excel format.
This request is available for organizations, products or projects |
Organization
{ "requestType" : "getOrganizationMembersReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductMembersReport", "productToken" : "product_token" } |
Response
The response will have the following headers:
Project
{ "requestType" : "getProjectMembersReport", "projectToken" : "project_token" } |
Response
The response will have the following headers:
Get organization level plugin request history reports in Excel format.
This request is available for organizations |
Organization
{ "requestType" : "getPluginRequestHistoryReport", "orgToken" : "organization_api_key" } |
Response
The response will have the following headers:
Get organization level product comparison reports in Excel format.
This request is available for use with 2 products |
Organization
{ "requestType" : "getProductComparisonReport", "productToken" : "product_token", "productToken2" : "product_token2" } |
Response
The response will have the following headers:
Product
{ "requestType" : "getProductLibraryLocations", "productToken" : "product_token" } |
Response Format
"libraryLocations" : [ { "name" : "library_name", "keyId" : key_id, "keyUuid" : "key_uuid", "locations": [ { "path" : "library_location_1\library_name", "matchType": "SHA1" }, { "path": "library_location_2\\library_name", "matchType": "FILENAME" } ] } ] |
Project
{ "requestType" : "getProjectLibraryLocations", "projectToken" : "project_token" } |
Response Format
"libraryLocations" : [ { "name" : "library_name", "keyId" : key_id, "keyUuid" : "key_uuid", "locations": [ { "path" : "library_location_1\library_name", "matchType": "SHA1" }, { "path": "library_location_2\\library_name", "matchType": "FILENAME" } ] } ] |
See Policies API for documentation.
{ "requestType": "createGroup", "orgToken": "organization_api_key", "group":{ "name":"group_name", "description":"group_description" } } |
Response Format
{ "group":{ "id": 8340, "name": "test_group", "description": "best group ever", "users":[] }, "message": "Successfully created group test_group" } |
{ "requestType": "createUser", "orgToken": "organization_api_key", "inviter":{ "email": "inviter_email" }, "addedUser":{ "name":"new_user_name", "email":"new_user_email" } } |
Response Format
"message":"Successfully created user new_user_name" |
{ "requestType": "inviteUsers", "orgToken": "organization_api_key", "inviter":{ "email":"inviter_email" }, "emails":[ "new_email1", "new_email2" ] } |
Response Format
"message":"Successfully sent invitation to new_email1,new_email2" |
{ "requestType": "getAllGroups", "orgToken": "organization_api_key" } |
Response Format
{ "groups":[ { "id": 2373, "name": "admins", "description": "Alex playground administrators", "users":[ {"id": 2458, "email": "john1@gmail.com", "name": "John2"}, {"id": 1841, "email": "john2@gmail.com", "name": "John1"} ]}], "message":"Organization groups" } |
{ "requestType": "getAllUsers", "orgToken": "organization_api_key" } |
Response Format
{ "users":[ { "id": 1841, "email": "john@gmail.com", "name": "John Doe" }], "message":"Organization users" } |
{ "requestType": "addUsersToGroups", "orgToken": "organization_api_key", "assignedUsers" : [ [{"name":"group_name"},[{"email":"assigned_user_email"}, {"email":"assigned_user_email"}]] ] } |
Response Format
"message":"Successfully assigned users to groups" |
{ "requestType":"getOrganizationAssignments", "orgToken":"organization_api_key" } |
Response Format
{ "groupRoles":{ "USER":[ { "id":group_id, "name":"users", "description":"All users in organization", "users":[ { "id":user_id, "email":"user_email", "name":"No Name" }, { "id":user_id, "email":"user_email", "name":"user_name" } ] } ], "ADMIN":[ { "id":group_id, "name":"admins", "description":"Administrators", "users":[ { "id":user_id, "email":"user_email", "name":"user_name" } ] } ] }, "userRoles":{ "USER":[ { "id":user_id, "email":"user_email", "name":"user_name" }, { "id":user_id, "email":"user_email", "name":"user_name" } ], "DEFAULT_APPROVER":[ { "id":user_id, "email":"user_email", "name":"user_name" } ] } } |
{ "requestType":"getProductAssignments", "productToken":"product_api_key" } |
Response Format
{ "groupRoles":{ "ALERT_EMAIL_RECEIVER":[ { "id":group_id, "name":"group_name", "description":"Email receivers", "users":[ { "id":user_id, "email":"user_email", "name":"user_name" } ] } ], "ADMIN":[ { "id":group_id, "name":"group_name", "description":"Administrators", "users":[ { "id":user_id, "email":"user_email", "name":"user_name" } ] } ] }, "userRoles":{ } } |
{ "requestType": "setOrganizationAssignments", "orgToken": "organization_api_key", "administrators" : { "groupAssignments":[{"name":"group_name"},{"name":"group_name"}], "userAssignments":[{"email":"user_email"},{"email":"user_email"}] } } |
Response Format
"message":"Successfully set organization assignments" |
{ "requestType": "setProductAssignments", "productToken": "product_api_key", "productMembership" : { "userAssignments":[{"email":"user_email"}], "groupAssignments":[{"name":"group_name"}] } } |
Response Format
"message":"Successfully set product assignments" |
Role Types
Organization Roles |
|
Product Roles |
|
It is possible to use email or id when using "user". |
{ "requestType" : "createProject", "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" } |
{ "requestType" : "deleteProject", "productToken" : "parent product token", "projectToken": "token of the project to be deleted" } |
Response Format
{ "message": "Successfully deleted project <project name>" } |
{ "requestType" : "createProduct", "productName" : "new product name", "orgToken" : "organization token" } |
Response Format
{ "productToken": "new product token", "message": "Successfully created product <new product name>" } |
{ "requestType" : "deleteProduct", "orgToken" : "organization token", "productToken" :"product token" } |
Response Format
{ "message": "Successfully deleted product <product name>" } |
'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", "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" } ] } ] } |
'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", "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" }]} |
{ "requestType":"getProjectState", "projectToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } |
Response Format
{ "projectState":{ "lastProcess":"UPDATE", "inProgress":false, "date":"2017-06-17"} } |
{ "requestType":"getLibrarySourceFiles", "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"}] } |
{ "requestType":"getProjectLibraryDependencies", "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" } ] } ] } |
{ "requestType" : "getRequestState", "orgToken" : "organization token", "requestToken" : "support token" } |
Response Format
{ "requestState": "FINISHED", "timestamp": "2018-02-28T17:48:19Z" } |
Possible requestState values:
The timestamp field is in UTC format.
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
Structure of the vulnerability in each security vulnerability alert object:
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.
The 'vulnerabilityFix' and 'fixResolutionText' fields are populated only when there is an available fix. |
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 |
Each source file object has the following fields:
name - the name of the source file.
sha1 - the SHA-1 checksum.
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
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.
GITHUB_COMMIT
JIRA
BUGZILLA
NODE_SECURITY_ADVISORY
PIVOTAL_VULNERABILITY_REPORT
FFMPEG_SECURITY - no extra data available.
STRUTS_SECURITY_BULLETIN
XFORCE_VULNERABILITY_REPORT
SECURITY_TRACKER