HTTP API v1.3

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:

Overview

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

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

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

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

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

API Execution Scope

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

  • getProjectVitals – Product administrators can use the Organization level call and get the product/project vitals related to their products/projects.

  • getRequestState – Although an Organization token is required in the call, a product administrator can also execute it.

API URL

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

Only POST requests are accepted. 

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

Character Sets

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

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

Supported character sets are:

  • utf-8

  • utf-16

  • iso-8859-1

  • iso-8859-2

  • iso-8859-4

  • iso-8859-5

  • iso-8859-7

  • iso-8859-9

  • us-ascii

Special Characters

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

Supported Methods

WhiteSource HTTP API supports the following methods:

Alerts

  • Get All Organization Alerts

  • Get All Product Alerts

  • Get All Project Alerts

  • Get Alerts by Project tag

Alerts by Type

  • Get Organization Alerts by Type

  • Get Product Alerts by Type

  • Get Project Alerts by Type

Change Log

  • Get Change Log

Licenses

  • Get All Organization Licenses

  • Get All Product Licenses

  • Get All Project Licenses

License Histogram

  • Get Organization License Histogram

  • Get Product License Histogram

  • Get Project License Histogram

Organization Vitals

  • Get All Organizations

  • Get Organization Details

Project / Product Vitals

  • Get All Products

  • Get All Projects

  • Get Organization Project Vitals (vitals of all projects within an organization)

  • Get Product Project Vitals (vitals of all projects within a product)

  • Get Project Vitals

  • Get Organization Product Vitals (vitals of all products within an organization)

Project Tags

  • Get Organization Project Tags

  • Get Product Project Tags

  • Get Project Tags

  • Save Project Tag

Misc.

  • Get Product Licenses Text Zip file

  • Update project with JNinka result file (jninka.xml)

Reports

  • Get Organization Risk Report

  • Get Product Risk Report

  • Get Organization Inventory Report

  • Get Product Inventory Report

  • Get Project Inventory Report

  • Get Organization Container Vulnerability Report

  • Get Prioritize/ Effective Usage Analysis Report

  • Get Cluster Vulnerability Report

  • Get Organization Vulnerability Report

  • Get Product Vulnerability Report

  • Get Project 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 Effective Usage Analysis 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 Attribution Report

  • Get Project Attribution Report

Library Locations

  • Get Product Library Locations

  • Get Project Library Locations


Policies

See Policies API.

  • Get Organization Policies

  • Get Product Policies

  • Get Project Policies

  • Add Organization Policy

  • Add Product Policy

  • Add Project Policies

  • Update Organization Policy

  • Update Product Policy

  • Update Project Policy

  • Remove Organization Policies

  • Remove Product Policies

  • Remove Project Policies

  • Reorder Organization Policy Priorities

  • Reorder Product Policy Priorities

  • Reorder Project 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

  • Remove User from Group

  • Remove User from Organization:

Project Create / Delete

  • Create Project

  • Delete Project

Product Create / Delete

  • Create Product

  • Delete Product

Project API Requests

  • Get Project Hierarchy

  • Get Project Inventory

  • Get Project State

  • Get Library Source Files

WhiteSource Advise for Chrome

  • Invite user to WhiteSource Advise for Chrome

API Format

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

The requestType field is mandatory for all requests.

Fields

Field name

Value

Field name

Value

requestType

One of the following:

  • getOrganizationAlerts

  • getOrganizationIgnoredAlerts

  • getProductAlerts

  • getProjectAlerts

  • getAlertsByProjectTag

  • getOrganizationAlertsByType

  • getProductAlertsByType

  • getProjectAlertsByType

  • getOrganizationLicenses

  • getProductLicenses

  • getProjectLicenses

  • getOrganizationEffectiveUsageAnalysis

  • getOrganizationLicenseHistogram

  • getProductLicenseHistogram

  • getProjectLicenseHistogram

  • getLicensesTextZip

  • saveProjectTag

  • getProductLibraryLocations 

  • getProjectLibraryLocations

  • getOrganizationRiskReport

  • getProductRiskReport

  • getOrganizationInventoryReport

  • getProductInventoryReport

  • getProjectInventoryReport

  • getOrganizationVulnerabilityReport

  • getOrganizationContainerVulnerabilityReport

  • getClusterVulnerabilityReport

  • getProductVulnerabilityReport

  • getProjectVulnerabilityReport

  • getOrganizationSourceFileInventoryReport

  • getProductSourceFileInventoryReport

  • getProjectSourceFileInventoryReport

  • getOrganizationAlertsReport

  • getProductAlertsReport

  • getProjectAlertsReport

  • getOrganizationAttributesReport

  • getProductAttributesReport

  • getOrganizationCustomAttributeValues

  • getProductCustomAttributeValues

  • getProjectCustomAttributeValues

  • getOrganizationLibraryLocationReport

  • getProductLibraryLocationReport

  • getOrganizationDueDiligenceReport

  • getProductDueDiligenceReport

  • getProjectDueDiligenceReport

  • getOrganizationEffectiveLicensesReport

  • getProductEffectiveLicensesReport

  • getOrganizationBugsReport

  • getProductBugsReport

  • getProjectBugsReport

  • getOrganizationIgnoredAlertsReport

  • getProductIgnoredAlertsReport

  • getProjectIgnoredAlertsReport

  • getOrganizationResolvedAlertsReport

  • getProductResolvedAlertsReport

  • getProjectResolvedAlertsReport

  • getOrganizationRequestHistoryReport

  • getProductRequestHistoryReport

  • getProjectRequestHistoryReport

  • getPluginRequestHistoryReport

  • getOrganizationMembersReport

  • getProductMembersReport

  • getProjectMembersReport

  • getProductComparisonReport

  • getProjectComparisonReport

  • getOrganizationInHouseReport

  • getProductInHouseReport

  • getProjectInHouseReport

  • getOrganizationPolicies

  • getChangesReport

  • getProductAttributionReport

  • getProjectAttributionReport

  • getProductPolicies

  • addOrganizationPolicy

  • addProductPolicy

  • updateOrganizationPolicy

  • updateProductPolicy

  • removeOrganizationPolicies

  • removeProductPolicies

  • reorderOrganizationPolicyPriorities

  • reorderProductPolicyPriorities

  • getLicenses

  • createUser

  • inviteUsers

  • createGroup

  • getAllGroups

  • getAllUsers

  • getOrganizationAssignments

  • getProductAssignments

  • setOrganizationAssignments

  • setProductAssignments

  • addUsersToGroups

  • removeUserFromGroup

  • removeUserFromOrganization

  • createProject

  • deleteProject

  • createProduct

  • deleteProduct

  • getProjectHierarchy

  • getProjectInventory

  • getProjectState

  • getLibrarySourceFiles

  • inviteUserToWebAdvisor

  • createServiceUser

  • changeOriginLibrary

orgToken

Your organization API key

productToken

A unique identifier for your product

projectToken

A unique identifier for your project

alertType

One of the following:

  • SECURITY_VULNERABILITY

  • NEW_MAJOR_VERSION

  • NEW_MINOR_VERSION

  • MULTIPLE_LIBRARY_VERSIONS

  • REJECTED_BY_POLICY_RESOURCE


Alert Types

Name

Description

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.

Alerts

Get Alerts

For customers who have enabled vulnerability based alerting, there are several changes to API version 1.3. Refer here for details.

Get all alerts for a given organization/product/project.

Organization

1 2 3 4 5 { "requestType" : "getOrganizationAlerts", "userKey": "user_key", "orgToken" : "organization_api_key" }

Product

1 2 3 4 5 { "requestType" : "getProductAlerts", "userKey": "user_key", "productToken" : "product_token" }

Project

1 2 3 4 5 { "requestType" : "getProjectAlerts", "userKey": "user_key", "projectToken" : "project_token" }

Get Alerts by Project Tags

For customers who have enabled Security Alerts: View By Vulnerability, there are several changes to API version 1.3. Refer here for details.

1 2 3 4 5 6 7 { "requestType" : "getAlertsByProjectTag", "userKey": "user_key", "orgToken" : "orgToken", "tagKey":"key1", "tagValue":"value1" }

Response Format when Direct Dependency

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 "apiAlertInfo" : [ { "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", "description": "library_description", "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" "alertUuid": "6f07c029-f211-4d14-bbb6-5628aa87a1d1" } ] 

Response Format with Transitive Dependency

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 "apiAlertInfo" : [ { "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", "description": "library_description", "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" "alertUuid": "6f07c029-f211-4d14-bbb6-5628aa87a1d1" } ]

Alert level is either minor or major.

Get Ignored Alerts

For customers who have enabled Security Alerts: View By Vulnerability, there are several changes to API version 1.3. Refer here for details.

Get a list of ignored alerts per scope (organization/product/project).

Organization

1 2 3 4 5 { "requestType" : "getOrganizationIgnoredAlerts", "userKey": "user_key", "orgToken" : "organization_api_key" }

Product

1 2 3 4 5 { "requestType" : "getProductIgnoredAlerts", "userKey": "user_key", "productToken" : "product_token" }

Project

1 2 3 4 5 { "requestType" : "getProjectIgnoredAlerts", "userKey": "user_key", "projectToken" : "project_token" }

Response Format

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 { "alerts": [ { "vulnerability": { "name": "CVE-2019-10202", "type": "CVE", "severity": "high", "score": 7.5, "cvss3_score": 0.0, "publishDate": "2019-10-01", "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-10202", "description": "A series of deserialization vulnerabilities have been discovered in Codehaus 1.9.x implemented in EAP 7. This CVE fixes CVE-2017- 17485, CVE-2017-7525, CVE-2017-15095, CVE-2018-5968, CVE-2018-7489, CVE-2018-1000873, CVE-2019-12086 reported for FasterXML jackson-databind by implementing a whitelist approach that will mitigate these vulnerabilities and future ones alike.", "allFixes": [], "references": [] }, "type": "SECURITY_VULNERABILITY", "level": "MAJOR", "library": { "keyUuid": "029092aa-fe0c-4ab5-ae02-a5a05c9cb8c5", "keyId": 13673550, "filename": "jackson-mapper-asl-1.9.2.jar", "type": "Java", "description": "Data Mapper package is a high-performance data binding package\nbuilt on Jackson JSON processor", "references": { "url": "http://jackson.codehaus.org", "issueUrl": "http://jira.codehaus.org/browse/JACKSON", "pomUrl": "https://index.whitesourcesoftware.com/nexus/content/groups/public-on-prem/org/codehaus/jackson/jackson-mapper-asl/1.9.2/jackson-mapper-asl-1.9.2.pom" }, "sha1": "95400a7922ce75383866eb72f6ef4a7897923945", "name": "Data Mapper for Jackson", "artifactId": "jackson-mapper-asl", "version": "1.9.2", "groupId": "org.codehaus.jackson", "licenses": [ { "name": "Apache 2.0", "url": "http://www.opensource.org/licenses/Apache-2.0", "profileInfo": { "copyrightRiskScore": "THREE", "patentRiskScore": "ONE", "copyleft": "NO", "linking": "DYNAMIC", "royaltyFree": "CONDITIONAL" }, "references": [ { "referenceType": "POM file", "reference": "https://index.whitesourcesoftware.com/nexus/content/groups/public-on-prem/org/codehaus/jackson/jackson-mapper- asl/1.9.2/jackson-mapper-asl-1.9.2.pom" } ] } ] }, "project": "wss-dal-entity-mysql", "projectId": 1976, "projectToken": "fe305449dc244aeb8f0dd729182669b1251ceabede7548b4a86e61b3903f02e4", "directDependency": true, "description": "Medium:1,", "date": "2019-10-10", "time": 1570703663000, "alertUuid": "e2d992ce-eaa6-4469-98b3-221e35d6f5fe", "comments": "Ignore this alert" }, { "vulnerability": { "name": "CVE-2019-10202", "type": "CVE", "severity": "high", "score": 7.5, "cvss3_score": 0.0, "publishDate": "2019-10-01", "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2019-10202", "description": "A series of deserialization vulnerabilities have been discovered in Codehaus 1.9.x implemented in EAP 7. This CVE fixes CVE-2017-17485, CVE-2017-7525, CVE-2017-15095, CVE-2018-5968, CVE-2018-7489, CVE-2018-1000873, CVE-2019-12086 reported for FasterXML jackson-databind by implementing a whitelist approach that will mitigate these vulnerabilities and future ones alike.", "allFixes": [], "references": [] }, "type": "SECURITY_VULNERABILITY", "level": "MAJOR", "library": { "keyUuid": "029092aa-fe0c-4ab5-ae02-a5a05c9cb8c5", "keyId": 13673550, "filename": "jackson-mapper-asl-1.9.2.jar", "type": "Java", "description": "Data Mapper package is a high-performance data binding package\nbuilt on Jackson JSON processor", "references": { "url": "http://jackson.codehaus.org", "issueUrl": "http://jira.codehaus.org/browse/JACKSON", "pomUrl": "https://index.whitesourcesoftware.com/nexus/content/groups/public-on-prem/org/codehaus/jackson/jackson-mapper-asl/1.9.2/jackson-mapper-asl-1.9.2.pom" }, "sha1": "95400a7922ce75383866eb72f6ef4a7897923945", "name": "Data Mapper for Jackson", "artifactId": "jackson-mapper-asl", "version": "1.9.2", "groupId": "org.codehaus.jackson", "licenses": [ { "name": "Apache 2.0", "url": "http://www.opensource.org/licenses/Apache-2.0", "profileInfo": { "copyrightRiskScore": "THREE", "patentRiskScore": "ONE", "copyleft": "NO", "linking": "DYNAMIC", "royaltyFree": "CONDITIONAL" }, "references": [ { "referenceType": "POM file", "reference": "https://index.whitesourcesoftware.com/nexus/content/groups/public-on-prem/org/codehaus/jackson/jackson-mapper-asl/1.9.2/jackson-mapper-asl-1.9.2.pom" } ] } ] }, "project": "wss-server", "projectId": 1978, "projectToken": "2e139a0b5c494042b2c92807bc595c0bdd4645ae5ab34800a968999140e38e24", "directDependency": true, "description": "Medium:1,", "date": "2019-10-10", "time": 1570703663000, "alertUuid": "5f869dba-9d5d-437a-8a03-b51c23997f99", "comments": "Ignore this alert as well" } ] }

Security Vulnerability 

Alerts will also contain the following object:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 "vulnerability": { "name": "vulnerability_name", "type": "vulnerability_type", "severity": "vulnerability_severity", "score": cvss_2_vulnerability_score, "cvss3_severity": "cvss_3_score_severity", "cvss3_score": cvss_3_vulnerability_score, "publishDate": "vulnerability_publish_date" "scoreMetadataVector": "cvss_3_metadata_vector", "url": "URL_of_vulnerability" "description": "vulnerability_description", "topFix": { "vulnerability": "vulnerability_fix_name", "type": "vulnerability_fix_type", "origin": "origin_of_fix", "url": "URL_of_fix", "fixResolution": "fix_resolution", "date": "date_of_fix", "message": "summary_of_fix", "extraData": "additional_data_on_fix" }, "allFixes": [{ "vulnerability": "vulnerability_fix_name", "type": "vulnerability_fix_type", "origin": "origin_of_fix", "url": "URL_of_fix", "fixResolution": "fix_resolution", "date": "date_of_fix", "message": "details_on_fix", "extraData": "additional_data" }] }

 

topFix & allFixes objects:

These objects are displayed only when a fix is available for the specific vulnerability.

The vulnerability object has the following fields:

Field name

Value

Field name

Value

name

The id in the vulnerability DB (CVE or WS)

type

Either CVE or WS

severity

Severity of the CVSS 2 vulnerability (low, medium, high)

score

The CVSS 2 base score [0.0 - 10.0]

cvss3_severity

The score severity, if CVSS 3 score is between 0-3.9 - Low, if CVSS 3 score is between 4-6.9 - Medium, if CVSS 3 score is between 7-10 - High

cvss3_score

The CVSS 3 base score [0.0 - 10.0]

scoreMetadataVector

See specification link

publishDate

Original release date

url

URL of the CVE

description

A short description of the security vulnerability

topFix

Top recommended fix (when available)

allFixes

List of all fixes (when available)

fixResolutionText

The actual resolution text to display for the given fix.

Get Alerts by Type

For customers who have enabled Security Alerts: View By Vulnerability, there are several changes to API version 1.3. Refer here for details.

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.
When 'toDate' is not specified, it will be treated as the current date and time.

The following API calls return all alerts that were created or modified within the provided date range:

Organization

1 2 3 4 5 6 7 8 { "requestType" : "getOrganizationAlertsByType", "userKey": "user_key", "alertType" : "alert_type", "orgToken" : "organization_api_key", "fromDate" : "2016-01-01 10:00:00", "toDate" : "2016-01-02 10:00:00" }

Product

1 2 3 4 5 6 7 8 { "requestType" : "getProductAlertsByType", "userKey": "user_key", "alertType" : "alert_type", "productToken" : "product_token", "fromDate" : "2016-01-01 11:00:31", "toDate" : "2016-01-02 11:00:31" }

Project

1 2 3 4 5 6 7 8 9 { "requestType" : "getProjectAlertsByType", "userKey": "user_key", "alertType" : "alert_type", "projectToken" : "project_token", "fromDate" : "2016-01-01 11:00:00", "toDate" : "2016-01-02 11:00:00", "sourceFiles": true }

Optional Parameters:

  • When sourceFiles is set to true in the API request, the response will include the vulnerable source files.


Response Format

Same as alerts response

Ignore Alerts

Enables users with Organization Administrators role to ignore alerts according to their unique identifier. You can use any alert-related API to get the alertUUID of a particular alert. 

'alertUuids' and 'comments' are mandatory fields. 

Request

1 2 3 4 5 6 7 { "requestType":"ignoreAlerts", "orgToken": "organization_api_key", "userKey": "user_key", "alertUuids": ["22f72c74-c2ea-4ed9-b37f-75d77bc52045","22f72c74-c2ea-4ed9-b37f-75d77bc52046"], "comments": "alerts not relevant to service" }

Response

1 2 3 { "message": "Successfully ignored alerts" }

Set Alert Status

Enables users with Organization Administrators role to set the status of alert(s) according to their unique identifier. This API can also be used to change the alert's comments.  

Request

1 2 3 4 5 6 7 8 { "requestType":"setAlertsStatus", "orgToken":"organization_api_key", "userKey": "user_key", "alertUuids": ["alert1_UUID", "alert2_UUID"], "comments": "Enter you comment here", "status": "Active" }

Status can have one of the following values: Active or Ignored. 

Response

1 2 3 { "message": "Successfully set the alert's status" }

Get Change Log Report

Get organization level Change Log Report in various formats.

Request 

1 2 3 4 5 6 { "userKey": "user_key", "orgToken": "organization_api_key", "requestType": "getChangesReport", "startDateTime": "2019-08-21 08:08:08" }

 

Optional Parameters

  • startDateTime: Date and time for the reported change. Default value: The last seven days including today's date. For example, if today is March 15, then the filtering is for the dates 9-15 of March.
    Valid options (strings in uppercase):

    • Any past valid date and time in the following format: 'yyyy-mm-dd hh:mm:ss'. 

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { "changes": [ { "startDateTime": "2018-07-04 09:07:21", "category": "METADATA", "type": "SOURCE_MATCHING", "changeType": "CHANGED", "scope": "SOURCE_FILE", "scopeName": "activation_mode.h", "scopeId": 2922950, "beforeChange": [ "tensorflow-v1.4.0-rc0" ], "afterChange": [ "tensorflow-v1.4.0-rc0" ], "operator": "USER", "userEmail": "john@doe.com", "productId": 69491, "productName": "tensorflow", "projectId": 338568, "projectName": "tensor", "comment": "changed lib of source file" } ] }

Get Licenses

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

Organization

1 2 3 4 5 6 { "requestType" : "getOrganizationLicenses", "userKey": "user_key", "orgToken" : "organization_api_key", "excludeProjectOccurrences" : true/false }

Product

1 2 3 4 5 6 { "requestType" : "getProductLicenses", "userKey": "user_key", "productToken" : "product_token", "excludeProjectOccurrences" : true/false }

Project

1 2 3 4 5 6 { "requestType" : "getProjectLicenses", "userKey": "user_key", "projectToken" : "project_token", "excludeProjectOccurrences" : true/false }

Response Format

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 "libraries" : [ { "licenses" : [ "license_name_1", "license_name_2", "spdxName":"license_spdx_name" ], "copyrightReferences": [ { "copyright": "library_copyright_text", "startYear": "library_copyright_start_year" } ], "keyUuid": "library_key_uuid", "keyId": "library_key_id", "filename": "library_file_name", "name" : "libarary_name", "groupId" : "library_group_id", "artifactId" : "library_artifact_id", "version" : "library_version", "sha1" : "library_sha1", "languages": "library_language", "references" : {"url":"library_url", "downloadLink":"library_download_link" } } ]

Get License Histogram

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

Organization

1 2 3 4 5 { "requestType" : "getOrganizationLicenseHistogram", "userKey": "user_key", "orgToken" : "organization_api_key" }

Product

1 2 3 4 { "requestType" : "getProductLicenseHistogram", "productToken" : "product_token" }

Project

1 2 3 4 5 { "requestType" : "getProjectLicenseHistogram", "userKey": "user_key", "projectToken" : "project_token" }

Response Example

1 2 3 4 5 6 7 { "licenseHistogram" : { "Apache 2.0" : 2, "BSD 3" : 2, "GPL 3.0" : 1, } }

Get Organization Details

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

Request

1 2 3 4 5 { "requestType":"getOrganizationDetails", "orgToken":"org_token", “userKey”:”user_key” }

Response (Example)

1 2 3 4 5 6 7 8 9 { "orgName": "Org A", "orgToken": "Org_a_token" "creationDate": "2016-01-01 12:00:00" "numberOfProducts": "15" "numberOfProjects": "105" "numberOfGroups": "2" "numberOfUsers": "3" }

Get All Products

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

Request

1 2 3 4 5 { "requestType":"getAllProducts", "userKey": "user_key", "orgToken":"org_token" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 { "products": [ { "productName": "Product A", "productToken": "product_a_token" }, { "productName": "Product B", "productToken": "product_b_token" } ], "message": "Success" }

Get All Projects

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

Request

1 2 3 4 5 { "requestType":"getAllProjects", "userKey": "user_key", "productToken":"product_token" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 { "projects": [ { "projectName": "project_a", "projectToken": "project_a_token" }, { "projectName": "project_b", "projectToken": "project_b_token" } ], "message": "Success" }

Get In-House Libraries

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

Request

Organization Level

1 2 3 4 5 { "requestType" : "getOrganizationInHouseLibraries", "orgToken" : "organization_api_key", "userKey": "user_key" }

Product Level

1 2 3 4 5 { "requestType" : "getProductInHouseLibraries", "productToken" : "product_token", "userKey": "user_key" }

Project Level

1 2 3 4 5 { "requestType" : "getProjectInHouseLibraries", "projectToken" : "project_token", "userKey": "user_key" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 "libraries" : [ { "matchType" : "manual", "comment": "manually set to in-house", "keyUuid": "library_unique_id", "filename": "library_file_name", "groupId": "library_group_id", "artifactId": "library_artifact_id", "version": "library_version", "sha1": "library_sha1", "type": "library_type", "description": "library_description", "productName" : "product_name", "productToken" : "product_token", "projectName" : "project_name", "projectToken" : "project_token" }, { "matchType" : "automatic", "pattern" : "common-*", "keyUuid": "library_unique_id", "filename": "library_file_name", "groupId": "library_group_id", "artifactId": "library_artifact_id", "version": "library_version", "sha1": "library_sha1", "type": "library_type", "description": "library_description", "productName" : "product_name", "productToken" : "product_token", "projectName" : "project_name", "projectToken" : "project_token } ]

 

Response Parameters

  • matchType parameter value can be either 'manual' (manually marked by user) or 'automatic' (automatically marked by in-house rule).

  • pattern parameter is not returned for a library if matchType value is 'manual'.

  • comment parameter is not returned for a library if matchType value is 'automatic'.

Unmark In-House Libraries

Unmark libraries that were manually assigned as in-house.

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

Request

Organization Level

1 2 3 4 5 6 { "requestType": "unmarkManualInHouseLibrary", "userKey": "user_key", "orgToken": "organization_api_key", "keyUuid" : "library_UUID" }

Response

1 2 3 { "message": "Successfully unmarked in-house library" }

Get Project Vitals

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

Organization

1 2 3 4 5 { "requestType" : "getOrganizationProjectVitals", "userKey": "user_key", "orgToken" : "organization_api_key" }

Product

1 2 3 4 5 { "requestType" : "getProductProjectVitals", "userKey": "user_key", "productToken" : "product_token" }

Project

1 2 3 4 5 { "requestType" : "getProjectVitals", "userKey": "user_key", "projectToken" : "project_token" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 { "projectVitals":[ { "pluginName":"fs-agent:18.2.2", "name": "My Project", "token": "project_token", "uploadedBy": "name_of_user_who_ran_scan", "creationDate": "2016-01-01 12:00:00", "lastUpdatedDate": "2016-02-02 16:50:59" } ] }

Get Product Vitals

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

Organization

1 2 3 4 5 { "requestType" : "getOrganizationProductVitals", "userKey": "user_key", "orgToken" : "organization_api_key" }


Response

1 2 3 4 5 6 7 8 9 10 { "productVitals":[ { "name": "My Product", "token": "product_token", "creationDate": "2016-01-01 12:00:00", "lastUpdatedDate": "2016-02-02 16:50:59" } ] }

Global Organization

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

Create Global Organization 

1 2 3 4 5 6 { "requestType": "createGlobalOrg", "userKey": "user_key", "name": "global_org_name", "accountAdminEmail": "enter_account_admin_email@here.com" }

Response

1 2 3 { "globalOrgToken": "global_org_token" }

Assign Global Organization to an Organization

1 2 3 4 5 6 {    "requestType": "assignGlobalOrgToOrg",    "userKey": "user_key",    "orgToken": "org_token",    "globalOrgToken": "global_org_token" }

Remove Global Organization from an Organization

1 2 3 4 5 6 {    "requestType": "removeGlobalOrgFromOrg",    "userKey": "user_key",    "orgToken": "org_token",    "globalOrgToken": "global_org_token" }

Get All Organizations

Returns data on all organizations within the Global Organization.

Request

1 2 3 4 5 { "requestType":"getAllOrganizations", "userKey": "user_key", "globalOrgToken":"global_organization_token" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 { "organizations": [ { "orgName": "Org A", "orgToken": "Org_a_token" }, { "orgName": "Org B", "orgToken": "Org_b_token" } ], "message": "Success" }

Product Tags 

Get Product Tags

Get product tags: key, value.

Request

1 2 3 4 5 { "requestType": "getProductTags", "userKey": "user_key", "productToken": productToken }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { "productTags":[ { "name": "My Product A", "token": "product_token", "tags": { "newKey": [ "newValue", "newValue2" ], "tagKeyA": [ "tagValueA" ] } } ]

 

Products without tags are returned as well.

Save a Product Tag

Save a product tag: key, value.

Request

1 2 3 4 5 6 7 { "requestType": "saveProductTag", "userKey": "user_key", "productToken": "productToken", "tagKey": "newKey", "tagValue": "newValue" }

Response

1 2 3 4 5 6 7 8 9 { "productTagsInfo": { "name": "productA", "token": {productToken}, "tags": { "newKey": "newValue" } } }

 

Products without tags are also returned.

Get Organizational Product Tags

Get organizational product tags: key, value.

Request

1 2 3 4 5 { "requestType": "getOrganizationProductTags", "userKey": "user_key", "orgToken": "orgToken" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { "productTags": [ { "name": "productA", "token": " productAToken", "tags": { "newKey": [ "newValue", "newValue2" ], "tagKeyA": [ "tagValueA" ] } }, { "name": " productB", "token": " productBToken", "tags": {} } ] }

 

Products without tags are also returned.

Remove a Product Tag

Remove a product tag: key, value.

Request

1 2 3 4 5 6 7 { "requestType" : "removeProductTag", "userKey": "user_key", "productToken" : "product_token", "tagKey": "newKey", "tagValue": "newValue" }

Response

1 2 3 { "message": "Successfully removed product tag" }

Project Tags

Get Project Tags

Get project tags: key, value.

Organization

1 2 3 4 5 { "requestType" : "getOrganizationProjectTags", "userKey": "user_key", "orgToken" : "organization_api_key" }

Product

1 2 3 4 5 { "requestType" : "getProductProjectTags", "userKey": "user_key", "productToken" : "product_token" }

Project

1 2 3 4 5 { "requestType" : "getProjectTags", "userKey": "user_key", "projectToken" : "project_token" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "projectTags":[ { "name": "My Project 1", "token": "project_token_1", "tags":{ "Component": "Database", "Module": "Server" } }, { "name": "My Project 2", "token": "project_token_2", "tags":{} } ] }

 

Projects without tags are also returned.

Save a Project Tag

Save a project tag by key, value.

Project

1 2 3 4 5 6 7 { "requestType" : "saveProjectTag", "userKey": "user_key", "projectToken" : "project_token", "tagKey":"key1", "tagValue":"value1" }

Response

1 2 3 4 5 6 7 8 9 10 11 { "projectTags": { "name": "My Project 1", "token": "project_token_1", "tags": { "key1": "value1" } } }

Licenses Text Zip

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

Product

1 2 3 4 5 { "requestType" : "getLicensesTextZip", "userKey": "user_key", "productToken" : "product_token" }

Project

1 2 3 4 5 { "requestType" : "getProjectLicensesTextZip", "userKey": "user_key", "projectToken" : "project_token" }

Response

The response will have the following headers:

  • Content-Type = application/zip

  • Content-Disposition: attachment; filename=product_name-licenses.zip

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

Copyrights Text File

Get the copyrights' text files.

Product

1 2 3 4 5 { "requestType" : "getCopyrightsTextFile", "userKey": "user_key", "productToken" : "product_token" }

Project

1 2 3 4 5 { "requestType" : "getProjectCopyrightsTextFile", "userKey": "user_key", "projectToken" : "project_token" }

Response

The response will have the following headers:

  • Content-Type = text/plain

  • Content-Disposition: attachment; filename=product_name-copyrights.zip

Set Library Notices

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

Request

1 2 3 4 5 6 7 8 { "requestType": "setLibraryNotice", "orgToken" : "org_token", "userKey": "user_key", "libraryUUID": "library_UUID", "text": "Notices are fun!", "reference": "And references are too" }

NOTE: The reference field is optional.

Response

1 2 3 { "message": "Successfully set notice" }

Get Notices Text File

Get the notices text files.

This request is available only for products

Product

1 2 3 4 5 { "requestType" : "getNoticesTextFile", "userKey": "user_key", "productToken" : "product_token" }

Response

The response will have the following headers:

  • Content-Type = text/plain

  • Content-Disposition: attachment; filename=product_name-notices.zip

Get Risk Report

Get organization or product level risk reports in PDF format.

This request is available for organizations or products


Organization

1 2 3 4 5 { "requestType" : "getOrganizationRiskReport", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response

The response will have the following headers:

  • Content-Type = application/pdf

  • Content-Disposition: attachment; filename=<organization name>.pdf

Product

1 2 3 4 5 { "requestType" : "getProductRiskReport", "userKey": "user_key", "productToken" : "product_token" }

Response

The response will have the following headers:

  • Content-Type = application/pdf

  • Content-Disposition: attachment; filename=<product name>.pdf

Project

1 2 3 4 5 { "requestType" : "getProjectRiskReport", "userKey": "user_key", "projectToken" : "project_token" }

Response

The response will have the following headers:

  • Content-Type = application/pdf

  • Content-Disposition: attachment; filename=<project name>.pdf

Get Inventory Report

Get organization, product or project level inventory reports in Excel (xlsx) or JSON (json) format.

This request is available for organizations, products or projects.
An xlsx format is used when no format is provided.

Organization

1 2 3 4 5 6 { "requestType" : "getOrganizationInventoryReport", "userKey": "user_key", "orgToken" : "organization_api_key", "format" : "json" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 6 { "requestType" : "getProductInventoryReport", "userKey": "user_key", "productToken" : "product_token", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

1 2 3 4 5 6 { "requestType" : "getProjectInventoryReport", "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=<project name>.xlsx

Get Change Log Report

Get organization level Change Log in Excel format.

Request 

1 2 3 4 5 { "userKey": "user_key", "orgToken": "organization_api_key", "requestType":"getChangeLogHistoryReport" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=response.xlsx

Get Vulnerability Report

Get organization, product or project level vulnerability reports in Excel or JSON format.

This request is available for organizations, products or projects. An 'xlsx' format is used when no 'format' parameter is provided.

Organization

1 2 3 4 5 6 { "requestType" : "getOrganizationVulnerabilityReport", "userKey": "user_key", "orgToken" : "organization_api_key", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 6 { "requestType" : "getProductVulnerabilityReport", "userKey": "user_key", "productToken" : "product_token", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

1 2 3 4 5 6 { "requestType" : "getProjectVulnerabilityReport", "userKey": "user_key", "projectToken" : "project_token", "format" : "json" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<project name>.xlsx

Get Container Vulnerability Report

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

1 2 3 4 5 6 { "requestType" : "getOrganizationContainerVulnerabilityReport", "userKey": "user_key", "orgToken" : "org_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>.xlsx

Cluster

1 2 3 4 5 6 { "requestType" : "getClusterVulnerabilityReport", "userKey": "user_key", "productToken" : "product_token", "format" : "json" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<cluster name>.xlsx

Get Source File Inventory Report

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.
An xlsx format is used when no format is provided.

Organization

1 2 3 4 5 6 { "requestType" : "getOrganizationSourceFileInventoryReport", "userKey": "user_key", "orgToken" : "organization_api_key", "format" : "json" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 6 { "requestType" : "getProductSourceFileInventoryReport", "userKey": "user_key", "productToken" : "product_token", "format" : "json" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

1 2 3 4 5 6 { "requestType" : "getProjectSourceFileInventoryReport", "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=<product name>.xlsx

Prioritize/ Effective Usage Analysis

See here for details.

Get Alerts Report

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

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getOrganizationAlertsReport", "userKey": "user_key", "orgToken" : "organization_api_key", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getProductAlertsReport", "userKey": "user_key", "productToken" : "product_token", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getProjectAlertsReport", "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=<project name>.xlsx

Get Attributes Report

Get organization or product level attributes reports in Excel format.

This request is available for organizations or products

Organization

1 2 3 4 5 { "requestType" : "getOrganizationAttributesReport", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 { "requestType" : "getProductAttributesReport", "userKey": "user_key", "productToken" : "product_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Get Custom Attributes Values

Returns list of all custom attributes along with their set values for each library.

Organization

1 2 3 4 5 6 { "requestType":"getOrganizationCustomAttributeValues", "userKey": "user_key", "orgToken": "<orgToken>", // For example, orgToken for "ACME Corporation" "userKey": "<userKey>" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 "customAttributeValues": [ { "<keyUuid>": [ { "organizationAttr0": "value0", "context": "Organizational", "contextId": 2133534, "contextToken": "4534fgdfjghj5456jlklsdf7", "contextName": "ACME Corporation" } ] }, { "<keyUuid>": [ { "organizationAttr0": "valueX", "context": "Organizational", "contextId": 2133534, "contextToken": "4534j5456jlklsdf7", "contextName": "ACME Corporation" }, { "productAttr1": "valueA", "context": "Product", "contextId": 989795, "contextToken": "isdfsdfkhosdf935pokwt", "contextName": "Product A" }, { "productAttr1": "valueB", "context": "Product", "contextId": 07435365, "contextToken": "llsfi4trerg90824sdf", "contextName": "Product B" }, { "projectAtt2": "value", "context": "Project", "contextId": 985743395, "contextToken": "ldshwufnvf9235jgdg0", "contextName": "Project A" }, { "projectAtt2": "value", "context": "Project", "contextId": 098345345, "contextToken": "klasd309438dflkl0934t", "contextName": "Project B" } ] } ]

Product

1 2 3 4 5 6 { "requestType":"getProductCustomAttributeValues", "userKey": "user_key", "productToken": "<productToken>", // For example, productToken for "Product A" "userKey": "<userKey>" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 "customAttributeValues": [ { "<keyUuid>": [ { "organizationAttr0": "value0", "context": "Organizational", "contextId": 2133534, "contextToken": "45345345fdg5456jlklsdf7", "contextName": "ACME Corporation" } ] }, { "<keyUuid>": [ { "organizationAttr0": "valueX", "context": "Organizational", "contextId": 2133534, "contextToken": "45345345fdgdfgdfjghjlsdf7", "contextName": "ACME Corporation" }, { "productAttr1": "valueA", "context": "Product", "contextId": 989795, "contextToken": "isdfsdfkh3086h35pokwt", "contextName": "Product A" }, { "projectAtt2": "value", "context": "Project", "contextId": 985743395, "contextToken": "ldshwufnvo59332hf9gdg0", "contextName": "Project A" }, { "projectAtt2": "value", "context": "Project", "contextId": 098345345, "contextToken": "klasd309438dflkjg94t0934t", "contextName": "Project B" } ] } ]

Project

1 2 3 4 5 6 { "requestType":"getProjectCustomAttributeValues", "userKey": "user_key", "projectToken": "<projectToken>", // For example, projectToken for "Project A" that belongs to "Product A" "userKey": "<userKey>" }

Response

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 "customAttributeValues": [ { "<keyUuid>": [ { "organizationAttr0": "value0", "context": "Organizational", "contextId": 2133534, "contextToken": "45345345fdgdfgd456jlklsdf7", "contextValue": "ACME Corporation" } ] }, { "<keyUuid>": [ { "organizationAttr0": "valueX", "context": "Organizational", "contextId": 2133534, "contextToken": "45345345fdgdfgdfjghjlklsdf7", "contextName": "ACME Corporation" }, { "productAttr1": "valueA", "context": "Product", "contextId": 989795, "contextToken": "isdfsdfkh30osdf935pokwt", "contextName": "Product A" }, { "projectAtt2": "value", "context": "Project", "contextId": 985743395, "contextToken": "ldshwufnvo59332hfjgdg0", "contextName": "Project A" } ] } ]

Get Library Location Report

Get organization or product level library location reports in Excel format.

This request is available for organizations or products

Organization

1 2 3 4 5 { "requestType" : "getOrganizationLibraryLocationReport", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 { "requestType" : "getProductLibraryLocationReport", "userKey": "user_key", "productToken" : "product_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Get Due Diligence Report

Get organization or product level due diligence reports in Excel (xlsx) or JSON (json) format.

This request is available for organizations, products or projects.
An xlsx format is used when no format is provided.

Organization

1 2 3 4 5 6 { "requestType" : "getOrganizationDueDiligenceReport", "userKey": "user_key", "orgToken" : "organization_api_key", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 6 { "requestType" : "getProductDueDiligenceReport", "userKey": "user_key", "productToken" : "product_token", "format" : "json" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

1 2 3 4 5 6 { "requestType" : "getProjectDueDiligenceReport", "userKey": "user_key", "projectToken" : "project_token", "format" : "json" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Get Effective Licenses Report

Get organization or product level effective licenses reports in Excel format.

This request is available for organizations or products

Organization

1 2 3 4 5 { "requestType" : "getOrganizationEffectiveLicensesReport", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 { "requestType" : "getProductEffectiveLicensesReport", "userKey": "user_key", "productToken" : "product_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Get Bugs Report

Get organization, product or project level bugs reports in Excel format.

This request is available for organizations, products or projects

Organization

1 2 3 4 5 { "requestType" : "getOrganizationBugsReport", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 { "requestType" : "getProductBugsReport", "productToken" : "product_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

1 2 3 4 5 { "requestType" : "getProjectBugsReport", "userKey": "user_key", "projectToken" : "project_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<project name>.xlsx

Get Ignored Alerts Report

Get organization, product or project level ignored alerts reports in Excel format.

This request is available for organizations, products or projects.

Organization

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getOrganizationIgnoredAlertsReport", "userKey": "user_key", "orgToken" : "organization_api_key", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getProductIgnoredAlertsReport", "userKey": "user_key", "productToken" : "product_token", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getProjectIgnoredAlertsReport", "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=<project name>.xlsx

Get Resolved Alerts Report

Get organization, product or project level resolved alerts reports in Excel format.

This request is available for organizations, products or projects

Organization

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getOrganizationResolvedAlertsReport", "userKey": "user_key", "orgToken" : "organization_api_key", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getProductResolvedAlertsReport", "userKey": "user_key", "productToken" : "product_token", "format" : "xlsx" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

For customers who have enabled Security Alerts: View By Vulnerability, this API will not be available.

1 2 3 4 5 6 { "requestType" : "getProjectResolvedAlertsReport", "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=<project name>.xlsx

Get Attribution Report

Get product or project level attribution reports in HTML or text format.

The requests are available for products or projects

Product

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "requestType": "getProductAttributionReport", "productToken" : "product_token", "userKey": "user_key", "reportHeader": "header_text", // Default "Attribution Report" "reportTitle": "title_text", // Default "" "reportFooter": "footer_text", // Default "" "reportingScope": ( SUMMARY | LICENSES | COPYRIGHTS | NOTICES | PRIMARY_ATTRIBUTES), // Default all options (SUMMARY, LICENSES, COPYRIGHTS, NOTICES, PRIMARY_ATTRIBUTES) "reportingAggregationMode": ( BY_COMPONENT | BY_PROJECT ), // Mandatory "missingLicenseDisplayOption": ( BLANK | GENERIC_LICENSE ), // Default "BLANK" "exportFormat": ( TXT | HTML | JSON ), // Case insensitive "licenseReferenceTextPlacement": ( LICENSE_SECTION | APPENDIX_SECTION ), // Default "LICENSE_SECTION" "customAttribute": "custom_attribute_name", "includeVersions": "false" // Optional parameter, default value is "true". If set to "false", the attribution report will not include the field "version". }

Response

The response is in text or HTML formats.

Project

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "requestType": "getProjectAttributionReport", "projectToken" : "project_token", "userKey": "user_key", "reportHeader": "header_text", // Default "Attribution Report" "reportTitle": "title_text", // Default "" "reportFooter": "footer_text", // Default "" "reportingScope": ( SUMMARY | LICENSES | COPYRIGHTS | NOTICES | PRIMARY_ATTRIBUTES ), // Default all options (SUMMARY, LICENSES, COPYRIGHTS, NOTICES, PRIMARY_ATTRIBUTES) "reportingAggregationMode": ( BY_COMPONENT | BY_PROJECT ), // Mandatory "missingLicenseDisplayOption": ( BLANK | GENERIC_LICENSE ), // Default "BLANK" "exportFormat": ( TXT | HTML | JSON ), // Case insensitive "licenseReferenceTextPlacement": ( LICENSE_SECTION | APPENDIX_SECTION ), // Default "LICENSE_SECTION" "customAttribute": "custom_attribute_name", "includeVersions": "true" // Optional parameter, default value is "true". If set to "false", the attribution report will not include the field "version". }

Response

The response is in text or HTML formats.

Get Request History Report

Get organization, product or project level request history reports in Excel format.

This request is available for organizations, products or projects

Organization

1 2 3 4 5 { "requestType" : "getOrganizationRequestHistoryReport", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 { "requestType" : "getProductRequestHistoryReport", "userKey": "user_key", "productToken" : "product_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

1 2 3 4 5 { "requestType" : "getProjectRequestHistoryReport", "userKey": "user_key", "projectToken" : "project_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<project name>.xlsx

Get Members Report

Get organization, product or project level members reports in Excel format.

This request is available for organizations, products or projects

Organization

1 2 3 4 5 { "requestType" : "getOrganizationMembersReport", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Product

1 2 3 4 5 { "requestType" : "getProductMembersReport", "userKey": "user_key", "productToken" : "product_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product name>.xlsx

Project

1 2 3 4 5 { "requestType" : "getProjectMembersReport", "userKey": "user_key", "projectToken" : "project_token" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<project name>.xlsx

Get Plugin Request History Report

Get organization level plugin request history reports in Excel format.

This request is available for organizations

Organization

1 2 3 4 5 { "requestType" : "getPluginRequestHistoryReport", "userKey": "user_key", "orgToken" : "organization_api_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>.xlsx

Get Product Comparison Report

Get organization level product comparison reports in Excel format.

This request is available for use with 2 products

Organization

1 2 3 4 5 6 { "requestType" : "getProductComparisonReport", "userKey": "user_key", "productToken" : "product_token", "productToken2" : "product_token2" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<product>-<product2>-product-comparison.xlsx

Get Project Comparison Report 

Get organization level project comparison reports in Excel format.

This request is available for use with 2 projects

Organization

1 2 3 4 5 6 { "requestType" : "getProjectComparisonReport", "userKey": "user_key", "projectToken" : "project_token", "projectToken2" : "project_token2" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<project>-<project2>-project-comparison.xlsx

Get In-House Report

Get organization, product, and project level in-house report(s) in Excel format.

Organization

1 2 3 4 5 { "requestType" : "getOrganizationInHouseReport", "orgToken" : "organization_api_key", "userKey": "user_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<organization name>-in-house-report.xlsx

Product

1 2 3 4 5 { "requestType" : "getProductInHouseReport", "productToken" : "product_token", "userKey": "user_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;'|

  • Content-Disposition: attachment; filename=<product name>-in-house-report.xlsx

Project

1 2 3 4 5 { "requestType" : "getProjectInHouseReport", "projectToken" : "project_token", "userKey": "user_key" }

Response

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename=<project name>-in-house-report.xlsx

Get License Compatibility Report 

Get the compatibility of libraries with different software licenses distributed together in the same product/project, in Excel format.

Product

1 2 3 4 5 { "requestType" : "getProductLicenseCompatibilityReport", "productToken" : "product_token", "userKey": "user_key" }

Response 

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename*=UTF-8''<Product Name>-license-compatibility-report.xlsx

Project 

1 2 3 4 5 { "requestType" : "getProjectLicenseCompatibilityReport", "projectToken" : "project_token", "userKey": "user_key" }

Response 

The response will have the following headers:

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

  • Content-Disposition: attachment; filename*=UTF-8''<Project Name>-license-compatibility-report.xlsx

Get Library Locations

Product

1 2 3 4 5 { "requestType" : "getProductLibraryLocations", "userKey": "user_key", "projectToken" : "project_token" }

Response Format

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 "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

1 2 3 4 5 { "requestType" : "getProjectLibraryLocations", "userKey": "user_key", "projectToken" : "project_token" }

Response Format

1 2 3 4 5 6 7 8 9 10 11