Versions Compared

Old Version 17

changes.mady.by.user Ronen Sigan

Saved on

compared with

New Version Current

changes.mady.by.user Tsur Rothfeld

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Info

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

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.0. The API URL can be obtained by copying the 'WhiteSource Server URL', which can be retrieved from your 'Profile' page on the 'Server URLs' panel. Then, add the path '/api/v1.0' to it. For example: https://saas.whitesourcesoftware.com/api/v1.0.

...

Note

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
  • getProductInventoryReport
  • getProjectInventoryReport
  • getOrganizationVulnerabilityReport
  • getOrganizationContainerVulnerabilityReport
  • getClusterVulnerabilityReport
  • getProductVulnerabilityReport
  • getProjectVulnerabilityReport
  • getOrganizationSourceFileInventoryReport
  • getProductSourceFileInventoryReport
  • getProjectSourceFileInventoryReport
  • 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
  • getChangesReport
  • 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

...

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.


Info

Date format in all responses is "yyyy-MM-dd".

None of the results are sorted in any order.

...

Info

Same as alerts response

Change Log

Get organization level Change Log Report in various formats.

Request 

Code Block
{
      "userKey": "user_key", 
      "orgToken": "organization_api_key",
      "requestType": "getChangesReport",
	  "startDateTime": "01/01/2018 10:02:00 	
}

...

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

Code Block
{
  "requestType":"getAllProducts",
  "orgToken":"org_token"
}

Response

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

Code Block
{
  "requestType":"getAllProjects",
  "productToken":"product_token"
}

Response

Code Block
{
    "projects": [
        {
            "projectName": "project_a",
            "projectToken": "project_a_token"
        },
        {
            "projectName": "project_b",
            "projectToken": "project_b_token"
        }
    ],
    "message": "Success"
}

...

Code Block
{
	"projectTags":[
    	{
			"name": "My Project 1",
			"token": "project_token_1",
			"tags":{
				"Component": "Database",
				"Module": "Server"
			}
		},
		{
			"name": "My Project 2",
			"token": "project_token_2",
			"tags":{}
		}
	]
}


Info

Projects without tags are returned as well

Save Project Tags

Save project tags by key, value.

...

  • Content-Type = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • Content-Disposition: attachment; filename=<project name>.xslx

Change Log Report

Get organization level Change Log in Excel format.

Request 

Code Block
{
    "userKey": "user_key",
    "orgToken": "organization_api_key",
	"requestType":"getChangeLogHistoryReport"	
}

...

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

Info

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

Organization

Code Block
{
	"requestType" : "getOrganizationVulnerabilityReport",
	"orgToken" : "organization_api_key",
	"format" : "xlsx"	
}

...

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

Info

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

Organization

Code Block
{
	"requestType" : "getOrganizationAlertsReport",
	"orgToken" : "organization_api_key",
	"format" : "xlsx"
}

...

Get Project Hierarchy

Info

'includeInHouseData' is an optional parameter. When set to ‘false’, in-house libraries data is not returned in the API response (default is ‘true’).

...

Get Project Inventory

Info

'includeInHouseData' is an optional parameter. When set to ‘false’, in-house libraries data is not returned in the API response (default is ‘true’).

...

  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. cvss3_score - the CVSS score 3 (as taken from NVD), values range from 0-10.
  5. cvss3_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
  6. scoreMetadataVector - a text representation of a set of CVSS metrics. See also related specification.

  7. description - the vulnerability description.

  8. publishDate - the publish date.

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

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

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

...

  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

...