Overview

API capability requires an additional WhiteSource license. Contact your CSM for more details.


To access the new and recommended version of the WhiteSource HTTP API, use HTTP API v1.1.

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

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

Currently, the API supports the following methods:

Alerts

Alerts by Type

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

Endpoint

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

Only POST requests are accepted.

Request payload should have:

API Format


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


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 nameValue
requestType

One of the following:

  • getOrganizationAlerts
  • getProductAlerts
  • getProjectAlerts
  • getAlertsByProjectTag
  • getOrganizationAlertsByType
  • getProductAlertsByType
  • getProjectAlertsByType
  • getOrganizationLicenses
  • getProductLicenses
  • getProjectLicenses
  • getOrganizationLicenseHistogram
  • getProductLicenseHistogram
  • getProjectLicenseHistogram
  • getLicensesTextZip
  • saveProjectTag
  • getProductLibraryLocations 
  • getProjectLibraryLocations
  • getOrganizationRiskReport
  • getProductRiskReport
  • getOrganizationInventoryReport
  • getChangesReport
  • getProductInventoryReport
  • getProjectInventoryReport
  • getOrganizationVulnerabilityReport
  • getProductVulnerabilityReport
  • getProjectVulnerabilityReport
  • getOrganizationContainerVulnerabilityReport
  • getClusterVulnerabilityReport
  • getOrganizationSourceFileInventoryReport
  • getProductSourceFileInventoryReport
  • getOrganizationAlertsReport
  • getProductAlertsReport
  • getProjectAlertsReport
  • getOrganizationAttributesReport
  • getProductAttributesReport
  • getOrganizationLibraryLocationReport
  • getProductLibraryLocationReport
  • getOrganizationDueDiligenceReport
  • getProductDueDiligenceReport
  • getOrganizationEffectiveLicensesReport
  • getProductEffectiveLicensesReport
  • getOrganizationBugsReport
  • getProductBugsReport
  • getProjectBugsReport
  • getOrganizationIgnoredAlertsReport
  • getProductIgnoredAlertsReport
  • getProjectIgnoredAlertsReport
  • getOrganizationResolvedAlertsReport
  • getProductResolvedAlertsReport
  • getProjectResolvedAlertsReport
  • getOrganizationRequestHistoryReport
  • getProductRequestHistoryReport
  • getProjectRequestHistoryReport
  • getPluginRequestHistoryReport
  • getOrganizationMembersReport
  • getProductMembersReport
  • getProjectMembersReport
  • getProductComparisonReport
  • getOrganizationPolicies
  • getProductPolicies
  • addOrganizationPolicy
  • addProductPolicy
  • updateOrganizationPolicy
  • updateProductPolicy
  • removeOrganizationPolicies
  • removeProductPolicies
  • reorderOrganizationPolicyPriorities
  • reorderProductPolicyPriorities
  • getLicenses
  • createUser
  • inviteUsers
  • createGroup
  • getAllGroups
  • getAllUsers
  • getOrganizationAssignments
  • getProductAssignments
  • setOrganizationAssignments
  • setProductAssignments
  • addUsersToGroups
  • createProject
  • deleteProject
  • createProduct
  • deleteProduct
  • getProjectHierarchy
  • getProjectInventory
  • getProjectState
  • getLibrarySourceFiles
orgTokenYour organization API key
userKeyYour user key (can be obtained from your Profile page)
productTokenA unique identifier for your product
projectTokenA 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

NameDescription
SECURITY_VULNERABILITYA security vulnerability has been detected for a library in the inventory
NEW_MAJOR_VERSIONA new major version has been released for a library in the inventory (only if major version updates is enabled)
NEW_MINOR_VERSIONA new minor version has been released for a library in the inventory (only if minor version updates is enabled)
MULTIPLE_LIBRARY_VERSIONSMultiple versions of the same library are being used
REJECTED_BY_POLICY_RESOURCEA 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".

Non of the results are sorted by any order.


Alerts

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 / major.



Security Vulnerability alerts will also contain the following object:


"vulnerability" : {
	"name" : "vulnerability_name",
	"type" : "vulnerability_type",
	"description" : "vulnerability_description",
	"score" : vulnerability_score,
	"severity" : "vulnerability_severity",
	"publishDate" : "vulnerability_publish_date"
}

The vulnerability object has the following fields:

Field nameValue
nameThe id in the vulnerability DB (CVE or WS)
typeEither CVE or WS
descriptionA short description of the security vulnerability
scoreThe CVSS v2 base score [0.0 - 10.0]
severityOne of { low, medium, high }
publishDateOriginal release date


Alerts by Type

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

{
	"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 10:00:00",
	"toDate" : "2016-01-02 11:00:00"
}

Project

{
	"requestType" : "getProjectAlertsByType",
	"alertType" : "alert_type",
	"projectToken" : "project_token",
	"fromDate" : "2016-01-01 10:00:10",
	"toDate" : "2016-01-02 10:00:10"
}


Response Format


Same as alerts response


Licenses

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"
						}
	}
]


License Histogram

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,
	}
}


Get All Products

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"
}

Get All Projects

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"
}

Project / Product Vitals

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"
		}
	]
}

Project Tags

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

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"
				}
		}
}


Licenses Text Zip

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


Copyrights Text File

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:

Notices Text File

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:


Risk Report

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:

Inventory Report

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

This request is available for organizations, products or projects

Organization

{
	"requestType" : "getOrganizationInventoryReport",
	"orgToken" : "organization_api_key"
}

Response

The response will have the following headers:

Product

{
	"requestType" : "getProductInventoryReport",
	"productToken" : "product_token"
}

Response

The response will have the following headers:

Project

{
	"requestType" : "getProjectInventoryReport",
	"projectToken" : "project_token"
}

Response

The response will have the following headers:

Change Log Report

Get organization level Change Log Report in various formats.

Request 

{
      "userKey": "user_key", 
      "orgToken": "organization_api_key",
      "requestType": "getChangesReport",
	  "startDateTime": "2018-01-01 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"
        }
    ]
}

Vulnerability Report

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" : "xlxs"
}

Response

The response will have the following headers:

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

{
    "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:

Source File Inventory Report

Get organization or product level source file inventory reports in Excel format.

This request is available for organizations or products

Organization

{
	"requestType" : "getOrganizationSourceFileInventoryReport",
	"orgToken" : "organization_api_key"
}

Response

The response will have the following headers:

Product

{
	"requestType" : "getProductSourceFileInventoryReport",
	"productToken" : "product_token"
}

Response

The response will have the following headers:

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

{
	"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" : "json"
}

Response

The response will have the following headers:

Attributes Report

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:

Library Location Report

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:

Due Diligence Report

Get organization or product level due diligence reports in Excel format.

This request is available for organizations or products

Organization

{
	"requestType" : "getOrganizationDueDiligenceReport",
	"orgToken" : "organization_api_key"
}

Response

The response will have the following headers:

Product

{
	"requestType" : "getProductDueDiligenceReport",
	"productToken" : "product_token"
}

Response

The response will have the following headers:

Effective Licenses Report

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:

Bugs Report

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:

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

{
	"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:


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

{
	"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:

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

{
	"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:

Members Report

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:

Plugin Request History Report

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:

Product Comparison Report

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:

Library Locations

Product

{
	"requestType" : "getProductLibraryLocations",
	"productToken" : "product_token"
}

Response Format

"libraryLocations" : [
	{
		"name" : "library_name"
		 "locations": [
			"library_location_1\library_name",
			"library_location_2\\library_name"
		]
	}
]


Project

{
	"requestType" : "getProjectLibraryLocations",
	"projectToken" : "project_token"
}

Response Format

"libraryLocations" : [
	{
		"name" : "library_name"
		 "locations": [
			"library_location_1\library_name",
			"library_location_2\\library_name"
		]
	}
]

Policies

See Policies API for documentation.

Groups and Users

Create Group

{
  "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"
}

Create user

{
  "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"


Invite Users

{
  "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"


Get All Groups

{
  "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"
}

Get All users

{
  "requestType": "getAllUsers",
  "orgToken": "organization_api_key"
}

Response Format

{
"users":[
{
"id": 1841,
"email": "john@gmail.com",
"name": "John Doe"
}],
"message":"Organization users"
}

Add Users to Groups

{
  "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"

Get Organization Assignments

{
    "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"
         }
      ]
   }
}


Get Product Assignments

{
    "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":{
   }
}


Set Organization Assignments

{
  "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"


Set Product 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
  • administrators
  • alertsEmailReceivers
  • defaultApprover
Product Roles
  • productAdmins
  • alertsEmailReceivers
  • productMembership
  • productApprovers


It is possible to use email or id when using "user".


Project Create / Delete

Create Project

{
    "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"
}


Delete Project

{
"requestType" : "deleteProject",
"productToken" : "parent product token",
"projectToken": "token of the project to be deleted"
}

Response Format

{
"message": "Successfully deleted project <project name>"
}


Product Create / Delete

Create Product

{
"requestType" : "createProduct",
"productName" : "new product name",
"orgToken" : "organization token"
}

Response Format

{
"productToken": "new product token",
"message": "Successfully created product <new product name>"
}


Delete Product

{
"requestType" : "deleteProduct",
"orgToken" : "organization token",
"productToken" :"product token"
}

Response Format

{
"message": "Successfully deleted product <product name>"
}


Project Requests

Get Project Hierarchy

'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"
        }
      ]
    }
  ]
}

Get Project Inventory

'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"
}]}

Get Project State

{
    "requestType":"getProjectState",
  	"projectToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response Format

{
	"projectState":{
	"lastProcess":"UPDATE",
	"inProgress":false,
	"date":"2017-06-17"}
}

Get Library Source Files

{
    "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"}]
}

Get Project Library Dependencies

{
  "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"
            }
         ]
      }
   ]
}

Plugin Request State

Get Request State

{
    "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 displated as "Support Token" when printing results to the console from the plugins) can be found in the data of the response returned form the server).

Note: Available since version 18.2.1

Response Structure

Structure of the vulnerability in each security vulnerability alert object:

Vulnerability

Each vulnerability object has the following fields:

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

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

    1. HIGH

    2. MEDIUM

    3. LOW

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

  4. description - the vulnerability description.

  5. publishDate - the publish date.

  6. sourceFile - in case the vulnerability was matched to a source file, not the binary library, the sourceFile field will be populated (see details below).
    Note: only libraries with type SOURCE_LIBRARY have source files.

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

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


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


Library details overview

typegroupIdartifactIdversionnamefilename

ActionScript

Alpine

Arch Linux

Debian

Java Archive

JavaScript

javascript/Node.js

Nuget

Python

RPM

Ruby

Package nameFilenamePackage versionPackage nameFilename (taken from artifactId)
JavaMaven groupIdMaven artifactIdMaven versionMaven project nameartifactId + version + extension
javascript/BowerProject ownerPackage namePackage versionPackage nameartifactId + version
.NETOwner / Organization.NET project namePackage version.NET project nameartifactId + version + extension
Source LibraryProject ownerSCM project nameRepository version / tagartifactId + versionartifactId + version
Unknown Library

-

If the artifact has owner, it will be displayed as groupId

filename + extension.

-

Will be shown only in case the artifact has version when uploaded

filename + extension

If the artifact has artifactId and version, the name will consist of them

Filename + extension

Source File

Each source file object has the following fields:

  1. name - the name of the source file.

  2. sha1 - the SHA-1 checksum.

Vulnerability Fix

Each vulnerability fix object has the following fields:

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

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

    1. CHANGE_FILES

    2. PATCH

    3. UPGRADE_VERSION

  3. vulnerabilityFixOrigin - the site, service or provider of the fix, can be one of:

    1. GITHUB_COMMIT

    2. JIRA

    3. BUGZILLA

    4. NODE_SECURITY_ADVISORY

    5. PIVOTAL_VULNERABILITY_REPORT

    6. FFMPEG_SECURITY

    7. STRUTS_SECURITY_BULLETIN

    8. XFORCE_VULNERABILITY_REPORT

    9. SECURITY_TRACKER

    10. WHITESOURCE_EXPERT - Used whenever a WhiteSource security researcher discovers that a vulnerability can be fixed by upgrading to a newer version, and there are no other sources for the vulnerability fix.

  4. url - the URL of the fix.

  5. fixResolution - the fix resolution. Depending on the origin the fixResolution field may vary:

    1. GITHUB_COMMIT - comma separated file names to change.

    2. JIRA - comma separated list of versions, e.g. “1.0.5,1.1.3”.

    3. BUGZILLA - comma separated list of versions.

    4. NODE_SECURITY_ADVISORY - text taken as-is from the origin, e.g. “>= 1.0.4” or “Upgrade to version 0.2.5 or greater.”

    5. PIVOTAL_VULNERABILITY_REPORT - text taken as-is from the origin.

    6. FFMPEG_SECURITY - comma separated list of versions.

    7. STRUTS_SECURITY_BULLETIN - text taken as-is from the origin, e.g. “Developers should upgrade to Struts 2.0.12”.

    8. XFORCE_VULNERABILITY_REPORT - text taken as-is from the origin, e.g. “Refer to ASA-2007-010 for patch, upgrade or suggested workaround information. See References.”.

    9. SECURITY_TRACKER - text taken as-is from origin, e.g. “The vendor has issued a fix (2.3.17, 2.4.11).”.

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

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

  8. extraData - extra data stored for each fix in key_1=value_1&key_2&value_2 pairs. Depending on the origin the extraData field may vary:

    1. key - the short commit SHA-1.

    2. committerName - the name of the committer.

    3. committerUrl - a link to the committer’s page on GitHub.

    4. committerAvatar - a link to the committer’s avatar.

    1. key - the issue id.

    2. assignee - the person assigned to the issue.

    1. key - the issue id.

    2. assignee - the person assigned to the issue.

    1. key - the advisory id.

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

    1. key - the bulletin id.

    1. key - the report id.

    1. key - the alert id.

    1. GITHUB_COMMIT

    2. JIRA

    3. BUGZILLA

    4. NODE_SECURITY_ADVISORY

    5. PIVOTAL_VULNERABILITY_REPORT

    6. FFMPEG_SECURITY - no extra data available.

    7. STRUTS_SECURITY_BULLETIN

    8. XFORCE_VULNERABILITY_REPORT

    9. SECURITY_TRACKER

Project State

  1. SETUP - Initializing project.
  2. DIFF - Calculating inventory changes.
  3. UPDATE - Updating inventory.
  4. CHANGE_EXCLUSIONS - Updating dependency exclusions.
  5. CHANGE_LOCAL_PATHS - Updating library paths.
  6. REMOVE - Removing libraries.
  7. PARTNER_UPDATE - Updating inventory.
  8. UPDATE_ALERTS - Updating alerts.
  9. CREATE_ISSUES - Creating external tickets

Assignments

  1. ADMIN
  2. ALERTS_IGNORER
  3. ALERT_EMAIL_RECEIVER
  4. DEFAULT_APPROVER
  5. LEGAL_ASSIGNER
  6. USER