Policy Waiver REST API

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

NOTE: The GET Method currently does not support retrieval of expired waivers.

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 that are applied to the application with application id787c2e3dc8e745c48743926251eef00b.

NOTE: The results do not include inherited waivers, i.e. those applied at the organization or root level.

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"
            }
        },
        "reasonText": "Acknowledged violation",
        "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 (root, 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.

POST

Create a New Waiver

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 REST APIs.

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
waiverReasonId RELEASE 183	null	The Id associated with the Waiver Reason. Use the Waiver Reason REST API to view the available Waiver Reasons and the corresponding Id.

Examples:

1. JSON payload:

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

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 a scope on a 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 a scope on a 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.

PUT to Update an Existing Waiver

PUT api/v2/policyWaivers/{ownerType: application|organization|repository|repository_manager|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.

Use the GET method above to retrieve the policyWaiverID.

Specify the policyWaiverID in the PUT request, for the policy waiver to be updated.

NOTE: Updating matcherStrategy is currently unsupported.

Examples:

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

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

2. JSON payload:

{
    "comment": "updating expiryTime",
    "expiryTime": "2025-12-26T00:00:00.000+0000",
    "matcherStrategy": "ALL_COMPONENTS",
    "waiverReasonId": "5810538dfd311b6da17557360a10dc64"
}

Response:

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

DELETE

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

The scope of the waiver is determined by the parameters ownerType andownerID. 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
PUT	Method	Release 188
waiverReasonId	Input parameter	Release 183
reasonText	Response field	Release 183
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

Policy Waiver REST API

GET

By OwnerId

By policyWaiverId

POST

Create a New Waiver

PUT to Update an Existing Waiver

DELETE

Change history for Policy Waiver REST API v2

Other Related REST APIs

Search results