Policies API

Abstract

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 showcases the API requests for getting, adding, updating and removing policies.

• Policy conflicts are resolved by priority
• Product level policies are of a higher priority than Organization level policies
• Project level policies are of a higher priority than Product level policies

Requests

Get Policies

Get all global organization-level / organization-level / product-level policies.

Global Organization

Response Format


Organization

Response Format

The response is a JSON collection of all organization-level policies (see details below).

Response example:

Product
Project

Response Format

The response is a JSON collection of all project-level policies (see details below).

Add Policy

Add a single policy to your global organization / organization / product.

Mandatory policy object fields: name, owner (id / email), filter, action.

A unique id will be created after creation.

Global Organization


Response Format

Organization


Response Format

The response is the added policy:

Product
Project

Response Format

The response is the added policy.

Update Policy

Update a single global organization-level / organization-level / product-level policy.

The id field is mandatory, enter only the fields and values to update.

Global Organization


Response Format

The response is the updated policy:


Organization

Response Format

The response is the updated policy:

Product

Response Format

The response is the updated policy.

Project

Response Format

The response is the updated policy.

Remove Policies

Remove global organization-level / organization-level / product-level policies by ids.

Global Organization

Response Format


Organization

Response Format

Product

Response Format

Project

Response Format

Update Policy Priorities

Update priorities of all global organization-level / organization-level / product-level policies.

Global Organization

Response Format

The response is a JSON collection of all global organization-level policies with the updated priorities.


Organization

Response Format

The response is a JSON collection of all organization-level policies with the updated priorities.

Product

Response Format

The response is a JSON collection of all product-level policies with the updated priorities.

Project

Response Format

The response is a JSON collection of all project-level policies with the updated priorities.

Get Global Licenses

Get all licenses to set in a license-type policy.

Request

Response Format

A collection of license objects:

JSON Object Response Structure

Policy

Each policy object has the following fields:

  1. id - the policy id
  2. name - the display name of the policy
  3. owner - the owner of the policy
  4. creationTime - the creation time of the policy (date format is "yyyy-MM-dd")
  5. priority - a positive integer defining priority of the policies. Policies are checked by order of priority (1 is the lowest priority)
  6. inclusive  - only used when filter licenses for the rest always be "false", trigger only when ALL licenses are matched
  7. filter - the policy filter defines how to match libraries (e.g. by license)
  8. action - the policy action defines what to do when a library matches the policy's filter
  9. productLevel - whether or not it's a product-level policy
  10. enabled - whether or not the policy is enabled. When policies are disabled they are ignored while checking policies

Filter

The policy filter defines the criteria for matching libraries (e.g. by the library's license).

Each filter object has a type field, the fields change according to the filter type:

TypeMatch LogicFields
LICENSEMatch libraries by their licenseslicenses - collection of license objects
RESOURCE_NAME_REGEXMatch libraries by name via GLOB patternlibraryNameRegex - GLOB pattern to match library by name
GAV_REGEXMatch libraries by GLOB of their groupId, artifactId or version

groupIdRegex - GLOB pattern to match library by groupId

artifactIdRegex - GLOB pattern to match library by artifactId

versionRegex - GLOB pattern to match library by version

VULNERABILITY_SEVERITY

Match libraries by severity of their vulnerabilities.

vulnerabilitySeverity - can be one of:

    • HIGH
    • MEDIUM
    • LOW

effectiveVulnerabilitiesOnly - (default = false) For Prioritize users, setting as true enables you to apply this match to libraries with Effective Vulnerability (red shield). 

VULNERABILITY_SCOREMatch libraries by CVSS score (0 - 10) of their vulnerabilities

scoreFrom - minimal CVSS score range

scoreTo - maximum CVSS score range

BUG_SCOREMatch libraries by their bug score

bugScore - can be one of:

    • HIGH
    • MEDIUM
    • LOW
VERSION_ACTIVITY_SCOREMatch libraries by the version activity score

versionActivityScore - can be one of:

    • HIGH
    • MEDIUM
    • LOW
LIBRARY_STALENESSMatch libraries older than a specific number of monthsmonthsBack - threshold of library age in months
PRIMARY_ATTRIBUTE_VALUEMatch libraries by their primary attribute valueprimaryAttributeValue - value of the primary attribute
PRODUCTMatch libraries if they're in a product's inventoryproductToken - product token

License

A license has the following fields:

  1. id - license id
  2. name - display name of the license



Action

The policy action defines what to do when a library matches a policy (e.g. reject the library or create a condition).

Each action object has a type field, the fields change according to the action type:

TypeActionFields
APPROVE

Automatically approve and close requests

-
REJECT

Automatically reject and close requests

Return policy violation indication when using plugins with checkPolicies set to 'true'

When applying policies on existing inventory, 'Policy Violation' alerts will be created

-
REASSIGNAutomatically reassign a request to a user, as opposed to the default approver

user - the user to reassign the request to

CONDITIONSAutomatically create conditions for a request

conditions - collection of conditions

approveWhenAllSatisfied - boolean deciding whether or not the request should be approved if all conditions are satisfied

rejectWhenOneRejected - boolean deciding whether or not the request should be rejected if at least on condition has been rejected

CREATE_ISSUEAutomatically creates an issue in your Issue TrackerissueSettings - object containing all information regarding the created issue

Condition

The condition object has the following fields:

  1. requestDuty - set assignee by duty (not user), can be one of:
    1. REQUESTER
    2. APPROVER
  2. user - set assignee by user (not duty)
  3. conditionText - the message displayed to the condition assignee
  4. duePeriod - number of days the assignee has to review the condition

Create Issue

The issueSettings object has the following fields:

Follow the table below to fill in the correct parameters for each Issue Tracker:

FieldJiraWork Items
summarySummary that will be written when issue is created.
descriptionDescription that will be written when issue is created.
issueTrackerTypeJIRAWORK_ITEMS
issueAsigneeDisplay name of the user you wish to assign the issue to, as it written in the Issue Tracker ("displayName" field).
issueProject

Insert the project key in the "key" field:

Insert the project name in the "name" field:

issueType

One of the following ("name" field):

  • Bug
  • Improvement
  • Task
  • New feature
  • Epic
  • Story


One of the following ("name" field):

  • Bug
  • Code Review Request
  • Test Case
  • Shared Steps
  • Epic
  • Task
  • Feature
  • Code Review Response
  • Feedback Request
  • Feedback Response
  • Test Plan
  • User Story
  • Shared Parameter
  • Test Suite
  • Issue
issuePriorityInfo

One of the following ("name" field):

  • Highest
  • High
  • Medium
  • Low
  • Lowest
----
requiredFieldsInfo

User

The user object has the following fields:

  1. id - user id
  2. email - email address of the user
  3. name - display name of the user