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

Methods supported:

1. POST to create waivers
2. GET
   
   1. By OwnerId: To retrieve waivers for specific organizational scope
   2. By policyWaiverId: To retrieve a single waiver
3. 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.

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:

1. associatedPackageUrl, displayName, and componentIdentifier are null when a waiver is of type "all components" and "unknown components."
2. 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