Policy Waiver REST API - v2

Policy Waivers

Adding Policy Waivers

NEW IN RELEASE 97

To add a policy waiver the policy violation ID must be known in advance. Policy waivers can be added by sending a POST request to

POST /api/v2/policyWaivers/{ownerType: application|organization}/{ownerId}/{policyViolationId}

Where ownerType and ownerId determine the scope of the waiver (application, organization or root organization).

The server will respond with a 204 status upon success. There is no content in the response.

Waiver options

The following waiver options can be provided in the JSON body payload:

Item	Description
DEPRECATED applyToAllComponents	Boolean flag. If true the waiver will be applied to all components with matching violations within specified scope. Deprecated: Use `matcherStrategy` instead
comment	Optional comment
NEW IN RELEASE 100 expiryTime	Optional waiver expiration date timestamp. Time-based Waivers can be created by specifying a future date at which the waiver should expire. Once the specified date is reached, the waiver will expire and the violations will be reported on the next scan.
NEW IN RELEASE 140 matcherStrategy	Enumeration field with 3 possible values EXACT_COMPONENT, ALL_COMPONENTS, ALL_VERSIONS. EXACT_COMPONENT is the same to applyToAllComponents = false and ALL_COMPONENTS is the same to applyToAllComponents = true `ALL_VERSIONS` applies the waiver for all versions (past, present and future) of a component If both matcherStrategy and applyToAllComponents are sent, applyToAllComponents is ignored.

Here is an example payload:

{
    "applyToAllComponents": false,
    "comment": "adding a waiver",
    "expiryTime": "2020-12-26T00:00:00.000+0000"
    "matcherStrategy": "ALL_COMPONENTS"
}

To create a waiver with Root Organization scope using cURL, the syntax would be as follows:

curl -u admin:admin123 -X POST http://localhost:8070/api/v2/policyWaivers/organization/ROOT_ORGANIZATION_ID/14f3e0fbc3884c21ac19bce74d7107c1

To add policy waiver with the application scope, where WebGoat-6.0.1 is an application publicId and 14f3e0fbc3884c21ac19bce74d7107c1 is a policyViolationId:

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"comment": "adding waiver for all components"}' http://localhost:8070/api/v2/policyWaivers/application/WebGoat-6.0.1/14f3e0fbc3884c21ac19bce74d7107c1

NEW IN RELEASE 100

To add a time-based waiver:

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"applyToAllComponents": false, "comment": "adding a time-based waiver", "expiryTime": "2020-12-26T13:00:00.000+0000"}' http://localhost:8070/api/v2/policyWaivers/application/WebGoat-6.0.1/14f3e0fbc3884c21ac19bce74d7107c1

Getting Policy Waivers

NEW IN RELEASE 92

Policy waivers for an application can be retrieved by sending a GET request to

GET /api/v2/policyWaivers/application/{applicationId}

As an example, to get policy waivers for the application with id 787c2e3dc8e745c48743926251eef00b using cURL the command would be as follows:

curl -u admin:admin123 http://localhost:8070/api/v2/policyWaivers/application/787c2e3dc8e745c48743926251eef00b

The server returns the list of policy waivers related to the application.

NEW IN RELEASE 131

The response will now include information about who created the specific waiver:

creatorId: username of the person that created the waiver

creatorName: full name of the person that created the waiver

NEW IN RELEASE 140

The response will now include information about the type of waiver:

matcherStrategy: the type of the waiver

associatedPackageUrl: the PURL of the component, only present if matcherStrategy is ALL_VERSIONS

A sample response would be as follows:

[
  {
    "policyWaiverId": "4dc85bcf566f4a9b83550267d9e80074",
    "comment": "Lorem ipsum.",
    "createTime": "2020-05-20T14:47:56.137+0000",
    "expiryTime": "2020-05-27T00:00:00.000+0000",
    "scopeOwnerType": "application",
    "scopeOwnerId": "787c2e3dc8e745c48743926251eef00b",
    "scopeOwnerName": "My-Application",
    "hash": "81e4d9cc2e8fac88ab4e",
    "policyId": "b7863359e04e443e803caf0389e779b1",
    "creatorId": "authorizedUser",
    "creatorName": "Authorized User",
    "matcherStrategy": "EXACT_COMPONENT"
  },
  {
    "policyWaiverId": "079dc8bdae7348e48a1b0939715d5e47",
    "comment": "1234",
    "createTime": "2020-05-20T14:47:39.511+0000",
    "scopeOwnerType": "application",
    "scopeOwnerId": "787c2e3dc8e745c48743926251eef00b",
    "scopeOwnerName": "My-Application",
    "hash": "52ee272b0181a1c0df5c",
    "policyId": "b7863359e04e443e803caf0389e779b1",
    "creatorId": "authorizedUser",
    "creatorName": "Authorized User",
    "matcherStrategy": "ALL_VERSIONS",
    "associatedPackageUrl": "pkg:maven/group/artifact@*?classifier=c1&type=jar"
  }
]

Policy waivers for an organization or a repository can be retrieved by replacing the application in the path mentioned above either by an organization , repository or repository_container and using the id of the relevant owner as follows.

GET /api/v2/policyWaivers/organization/{organizationId}
GET /api/v2/policyWaivers/repository/{repositoryId}
GET /api/v2/policyWaivers/repository_container/REPOSITORY_CONTAINER_ID

Deleting a Policy Waiver

NEW IN RELEASE 90

A policy waiver for an application can be deleted by sending a DELETE request to

DELETE /api/v2/policyWaivers/application/{applicationId}/{policyWaiverId}

As an example, in order to delete a policy waiver with id d248b438595740119043dd49a1a146da using cURL for the application with id 787c2e3dc8e745c48743926251eef00b the command would be as follows:

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/policyWaivers/application/787c2e3dc8e745c48743926251eef00b/d248b438595740119043dd49a1a146da

The server returns no content in case of success.

A policy waiver can be deleted for an organization or a repository by replacing the application in the path mentioned above either by an organization , repository or repository_container and using the id of the relevant owner as follows.

DELETE /api/v2/policyWaivers/organization/{organizationId}/{policyWaiverId}
DELETE /api/v2/policyWaivers/repository/{repositoryId}/{policyWaiverId}
DELETE /api/v2/policyWaivers/repository_container/REPOSITORY_CONTAINER_ID/{policyWaiverId}

Policy Waiver API related to "Requesting a Waiver to be Added"

NEW IN RELEASE 71

The intended use of this API is for workflows that require separate review and approval for waiving violations, which uses the Policy Violation ID. The Policy Violation ID, along with the scope of application or organization, is required for the API call. A comment is optional when adding the waiver. The Policy Violation ID can be obtained by Requesting a Waiver to be Added, Policy Violation REST API, or Report Related REST API.

To create a waiver the policy violation ID must be known in advance:

POST /api/v2/policyWaiver/{policyViolationId}/{application|organization}

A sample request to create an application waiver with a comment is done with the following command (comment is optional):

curl -u user:password -H "Content-Type: text/plain; charset=UTF-8" -X POST http://localhost:8070/api/v2/policyWaiver/14f3e0fbc3884c21ac19bce74d7107c1/application --data-binary "waiver comment (optional)"