Policy Waiver REST API - v2

This API can be used to create and retrieve policy waivers.

Methods supported:

POST to create waivers
GET
1. By OwnerId: To retrieve waivers for specific organizational scope
2. By policyWaiverId: To retrieve a single waiver
DELETE to delete waivers

1. POST

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

The scope of the waiver is determined by the parameters ownerType and ownerID . Possible values for ownerType and owner ID are application, organization, root organization, repository or repository container. To obtain the policyViolationID , use Policy Violation REST API or Report Related REST API.

Refer table below for the properties of the JSON object payload that can be sent with the POST request.

Property	Default Value	Description
matcherStrategy		Enumeration field. Possible values: EXACT_COMPONENT, ALL_COMPONENTS, ALL_VERSIONS
expiryTime	null	Optional, datetime to indicate expiry time of the waiver.
comment	null	Optional, describes the waiver.
applytoAllComponents	null	Boolean flag. Possible values true/false. If ‘true’ the waiver will be applied to all components

Examples:

1. JSON payload:

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

2. Create a waiver with scope as root org

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

3. Create a waiver with scope as repository container

curl -u admin:admin123 -X POST http://localhost:8070/api/v2/policyWaivers/repository_container/REPOSITORY_CONTAINER_ID/8124f0f6f0544f7bbe65447bd3ca59ec

4. Create a waiver with scope as repository

curl -u admin:admin123 -X POST http://localhost:8070/api/v2/policyWaivers/repository/84a7c181efac4a94a33bd698f1dbbc33/30817d2b37cd47a3a6931effa1cd71bf

5. Create a waiver with scope as application having public ID WebGoat-6.0.1 and policyViolationId 14f3e0fbc3884c21ac19bce74d7107c1

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

6. Create a time based waiver

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"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

Response:

HTTP status 204 (No content) to indicate that the waiver has been successfully created.

2. GET

By OwnerId

GET /api/v2/policyWaivers/{ownerType: application|organization|repository|repository_container}/{ownerId}

The scope of the waiver is determined by the parameters ownerType and ownerID. Possible values for ownerType and owner ID are application, organization, root organization, repository or repository container.

Examples:

1. Retrieve all policy waivers for the root org

curl -u admin:admin123 http://localhost:8070/api/v2/policyWaivers/organization/ROOT_ORGANIZATION_ID

2. Retrieve all policy waivers for the application id 787c2e3dc8e745c48743926251eef00b

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

3. Retrieve all policy waivers for repository container

curl -u admin:admin123 http://localhost:8070/api/v2/policyWaivers/repository_container/REPOSITORY_CONTAINER_ID

4. Retrieve all policy waivers for repository id 6891f877e254428c991d9be640a32969

curl -u admin:admin123 http://localhost:8070/api/v2/policyWaivers/repository/6891f877e254428c991d9be640a32969

Response:

[
    {
        "policyWaiverId": "f29f2e2927d64f1a91a7c06c3f52dad3",
        "comment": "",
        "createTime": "2022-10-07T21:28:10.418+0000",
        "expiryTime": "2022-11-07T04:59:59.999+0000",
        "scopeOwnerType": "application",
        "scopeOwnerId": "0d3fa305cb8d4ff4b9442d29816cf24c",
        "scopeOwnerName": "Application - TestApp",
        "hash": null,
        "policyId": "8ed35daa437349d8ac08688842fe922f",
        "vulnerabilityId": "sonatype-2020-0926",
        "creatorId": "admin",
        "creatorName": "Admin BuiltIn",
        "matcherStrategy": "ALL_VERSIONS",
        "associatedPackageUrl": "pkg:maven/com.google.guava/guava@25.1-android?type=jar",
        "componentIdentifier": {
            "format": "maven",
            "coordinates": {
                "artifactId": "guava",
                "extension": "jar",
                "groupId": "com.google.guava",
                "version": "25.1-android"
            }
        },
        "displayName": {
            "parts": [
                {
                    "field": "Group",
                    "value": "com.google.guava"
                },
                {
                    "value": " : "
                },
                {
                    "field": "Artifact",
                    "value": "guava"
                },
                {
                    "value": " : "
                },
                {
                    "field": "Version",
                    "value": "25.1-android"
                }
            ],
            "name": "guava"
        }
    },
    {
        "policyWaiverId": "405790725d4d4fc6878a919c3b189f2f",
        "comment": "",
        "createTime": "2022-10-07T21:28:49.860+0000",
        "scopeOwnerType": "application",
        "scopeOwnerId": "0d3fa305cb8d4ff4b9442d29816cf24c",
        "scopeOwnerName": "Application - TestApp",
        "hash": "6fdf25b9d89b961d217a",
        "policyId": "c4a13a490a21435581124b2f9c4ea99c",
        "creatorId": "admin",
        "creatorName": "Admin BuiltIn",
        "matcherStrategy": "EXACT_COMPONENT",
        "associatedPackageUrl": null,
        "componentIdentifier": null,
        "displayName": null
    }
]

Matcher strategy indicates if the retrieved waiver applies to a specific component, all components that exist at the chosen level of hierarchy (roort, org, application,) or all versions (past, present and future) of a component.

associatedPackageUrl, displayName, and componentIdentifier are null when a waiver is of all components type and for unknown components

By policyWaiverId

GET /api/v2/policyWaivers/{ownerType: application|organization|repository|repository_container}/{ownerId}/{policyWaiverId}

The scope of the waiver is determined by the parameters ownerType and ownerID. Possible values for ownerType and owner ID are application, organization, root organization, repository or repository container.

Examples:

1. Retrieve a policy waiver with root org scope and policyWaiverid b0864840e52e41fa9eb80214222ba5e5

curl -u admin:admin123 http://localhost:8070/api/v2/policyWaivers/organization/ROOT_ORGANIZATION_ID/b0864840e52e41fa9eb80214222ba5e5

2. Retrieve a policy waiver with application scope 28fa2fc995784480a781e601b00ebc5c and policyWaiverID ad8aecc1ba2f4ef686f117bf4a05e0e7

curl -u admin:admin123 http://localhost:8070/api/v2/policyWaivers/application/28fa2fc995784480a781e601b00ebc5c/ad8aecc1ba2f4ef686f117bf4a05e0e7

3. Retrieve a policy waiver with repository container scope and policyWaiverID a564d1bd4db734a6ec2b41e9243b8996

curl -u admin:admin123 http://localhost:8070/api/v2/policyWaivers/repository_container/REPOSITORY_CONTAINER_ID/a564d1bd4db734a6ec2b41e9243b8996

4. Retrieve a policy waiver with repository scope ce43cd92d0348c73e27bca58c3ee93a9 and policyWaiverId 76d34c0e3f5230e6ef8fb54ed4c1ee30

curl -u admin:admin123 http://localhost:8070/api/v2/policyWaivers/repository/ce43cd92d0348c73e27bca58c3ee93a9/76d34c0e3f5230e6ef8fb54ed4c1ee30

Response:

{
  "policyWaiverId": "9fc1ee3f2761458380d2135ef01135f4",
  "comment": "",
  "createTime": "2022-10-07T21:49:00.051+0000",
  "expiryTime": "2022-10-22T04:59:59.999+0000",
  "scopeOwnerType": "organization",
  "scopeOwnerId": "e40aed6067cc431491d42154c1257ed6",
  "scopeOwnerName": "MyOrg",
  "hash": "686ef3410bcf4ab8ce7f",
  "policyId": "d378f2c0bb2d404bbec04cd5f894188b",
  "vulnerabilityId": "CVE-2014-0114",
  "policyName": "Security-High",
  "constraintFacts": [
    {
      "constraintId": "6b68cdbe13884c779e44d643062b4b1c",
      "constraintName": "High risk CVSS score",
      "operatorName": "AND",
      "conditionFacts": [
        ...
      ]
    }
  ],
  "constraintFactsJson": "...",
  "creatorId": "admin",
  "creatorName": "Admin BuiltIn",
  "matcherStrategy": "EXACT_COMPONENT",
  "associatedPackageUrl": "pkg:maven/commons-beanutils/commons-beanutils@1.8.3?type=jar",
  "componentIdentifier": {
    "format": "maven",
    "coordinates": {
      "artifactId": "commons-beanutils",
      "extension": "jar",
      "groupId": "commons-beanutils",
      "version": "1.8.3"
    }
  },
  "threatLevel": 9,
  "displayName": {
    "parts": [
      {
        "field": "Group",
        "value": "commons-beanutils"
      },
      {
        "value": " : "
      },
      {
        "field": "Artifact",
        "value": "commons-beanutils"
      },
      {
        "value": " : "
      },
      {
        "field": "Version",
        "value": "1.8.3"
      }
    ],
    "name": "commons-beanutils"
  }
}

NOTES:

associatedPackageUrl, displayName, and componentIdentifier are null when a waiver is of type "all components" and "unknown components."
threatLevel should reflect the threat level of the policy violation.

3. DELETE

DELETE /api/v2/policyWaivers/{ownerType: application|organization|repository|repository_container}/{ownerId}/{policyWaiverId}

The scope of the waiver is determined by the parameters ownerType and ownerID. Possible values for ownerType and owner ID are application, organization, root organization, repository or repository container.

Examples:

1. Delete a policy waiver with id 3458b438595740119043dd49a1a146df that applies to the root org

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/policyWaivers/organization/ROOT_ORGANIZATION_ID/3458b438595740119043dd49a1a146df

2. Delete a policy waiver with id d248b438595740119043dd49a1a146da for an application having application id 787c2e3dc8e745c48743926251eef00b:

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

3. Delete a policy waiver with id 2338b438595740119043dd49a1a146dc in the repository container

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/policyWaivers/repository_container/REPOSITORY_CONTAINER_ID/2338b438595740119043dd49a1a146dc

4. Delete a policy waiver with id e678b438595740119043dd49a1a14645 in the repository having id 6891f877e254428c991d9be640a32969:

curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/policyWaivers/repository/6891f877e254428c991d9be640a32969/e678b438595740119043dd49a1a14645

Response:

No response/content indicates that the waiver has been successfully deleted.

Change history for Policy Waiver REST API v2

Name	Type	Release supported from
policyWaiverId	Input parameter	Release 147
associatedPackageURL	Response field	Release 140
matcherStrategy	Input parameter, Response field	Release 140
creatorID, creatorName	Response fields	Release 131
expirytime	Input parameter	Release 100
DELETE	method	Release 90
GET	method	Release 92
applyToAllComponents	Input parameter	Deprecated, use matcherStrategy instead

Other related APIs:

Policy Violation REST API

Report Related REST API

Applicable Waivers REST API - v2

Component Waivers REST API - v2

Stale Waivers REST API - v2

Transitive Waivers REST API - v2