Skip to main content

Applicable Waivers REST API

This API provides a way to obtain all waivers (including Automated Waivers, see endpoint for Automated Waiver) that are applicable to a particular policy violation. A waiver is considered applicable to a given violation if the following conditions apply:

  • PolicyId matches

  • Violated Policy Conditions match

  • If the waiver was scoped to a particular component then the component hash should also match

The API can be accessed via the following endpoint as a GET request, relative to IQ Server's base URL.

GET /api/v2/policyViolations/{policyViolationId}/applicableWaivers

Note

The Policy Violation ID can be obtained by Policy Violation REST API or Report Related REST API.

Assuming a local installation of IQ Server with its default configuration, the following example using cURL lists waivers that apply to a policy violation:

curl -u admin:admin123 -X GET -H "Content-Type: application/json" 'http://localhost:8070/api/v2/policyViolations/{policyViolationId}/applicableWaivers'

The response returned by this API contains two sets of waivers, one set containing active waivers and another containing expired waivers, that apply to the provided violation. Each of the waiver items contains several details regarding the waivers as described in the table below.

Item

Description

policyWaiverId

A unique identifier that identifies this policy waiver.

policyViolationId

The id of the policy violation on which the waiver is acting.

comment

Comment text that was entered during waiver creation.

createTime

The waiver creation time.

expiryTime

The time after which the policy waiver is considered expired.

This field may not be present in the response, in which case it indicates that the waiver is not set to expire.

scopeOwnerType

The scope at which the waiver was applied.

This can be one of three values:

  • root_organization

  • organization

  • application

scopeOwnerId

A unique identifier that identifies the scope.

scopeOwnerName

The descriptive name of the scope.

If the scope type is application, this will be the application name.

If the scope type is organization, this will be the organization name.

If the scope type is root_organization, this will be the root organization name.

hash

If the waiver was applied to a specific component, this will contain the uniquely identifying hash of that component.

If the waiver was applied to all components, the value for this property will be null.

policyId

The unique id of the policy for which the waiver is applied.

creatorId

The ID (username) of the user who created the waiver

creatorName

the full name of the user that created the waiver

matcherStrategy

Enumeration field with 3 possible values EXACT_COMPONENT, ALL_COMPONENTS, ALL_VERSIONS.

associatedPackageUrl

The Package-URL of the component is only present when the waiver is of type ALL_VERSIONS or EXACT_COMPONENT and is not an unknown component.

componentIdentifier

Component Identifier, is only present if the waiver is of type ALL_VERSIONS or EXACT_COMPONENT and is not an unknown component.

displayName

Display Name, only present if the waiver is of type ALL_VERSIONS or EXACT_COMPONENT and is not an unknown component.

reasonText

The reason for applying/requesting this waiver

policyWaiverReasonId

The policy waiver reason id associated with the waiver reason.

Sample response

Here is a sample response that is returned by this API.

{
    "activeWaivers": [
        {
            "policyWaiverId": "9fc1ee3f2761458380d2135ef01135f4",
            "policyViolationId": "5e02da4a230049feb08da590eceb3258",
            "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",
            "creatorId": "admin",
            "creatorName": "Admin BuiltIn",
            "matcherStrategy": "EXACT_COMPONENT",
            "associatedPackageUrl": "pkg:maven/commons-beanutils/commons-beanutils@1.8.3?type=jar",
            "policyWaiverReasonId": "f6990a32cd8d4ea78853ca829d948927",
            "reasonText": "Not exploitable",
            "componentIdentifier": {
                "format": "maven",
                "coordinates": {
                    "artifactId": "commons-beanutils",
                    "extension": "jar",
                    "groupId": "commons-beanutils",
                    "version": "1.8.3"
                }
            },
            "displayName": {
                "parts": [
                    {
                        "field": "Group",
                        "value": "commons-beanutils"
                    },
                    {
                        "value": " : "
                    },
                    {
                        "field": "Artifact",
                        "value": "commons-beanutils"
                    },
                    {
                        "value": " : "
                    },
                    {
                        "field": "Version",
                        "value": "1.8.3"
                    }
                ],
                "name": "commons-beanutils"
            }
        }
    ],
    "expiredWaivers": [
        {
            "policyWaiverId": "d2a933564cdc426785d7309992b66ff2",
            "policyViolationId": "5e02da4a230049feb08da590eceb3258",
            "comment": "",
            "createTime": "2022-10-07T21:41:23.106+0000",
            "expiryTime": "2022-10-15T04:59:59.999+0000",
            "scopeOwnerType": "application",
            "scopeOwnerId": "0d3fa305cb8d4ff4b9442d29816cf24c",
            "scopeOwnerName": "Application - TestApp",
            "hash": "686ef3410bcf4ab8ce7f",
            "policyId": "d378f2c0bb2d404bbec04cd5f894188b",
            "vulnerabilityId": "CVE-2014-0114",
            "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"
                }
            },
            "policyWaiverReasonId": "f6990a32cd8d4ea78853ca829d948927",
            "reasonText": "Not exploitable",
            "displayName": {
                "parts": [
                    {
                        "field": "Group",
                        "value": "commons-beanutils"
                    },
                    {
                        "value": " : "
                    },
                    {
                        "field": "Artifact",
                        "value": "commons-beanutils"
                    },
                    {
                        "value": " : "
                    },
                    {
                        "field": "Version",
                        "value": "1.8.3"
                    }
                ],
                "name": "commons-beanutils"
            }
        }
    ]
}

Retrieving Automated Waiver

GET /api/v2/policyViolations/{policyViolationId}/applicableAutoWaiver

Example:

To retrieve Automated Waiver applicable to a policy violation, see the example request below:

curl -X GET -u admin:admin123 http://localhost:8072/api/v2/policyViolations/<policyViolationId>/applicableAutoWaiver

Response:

{
    "autoPolicyWaiverId": "cacba739c7404778a0f6aeaddf89e45e",
    "ownerId": "5b6c0dde3b0e415487dd0c92220d105c",
    "ownerType": "application",
    "ownerName": "waiver-test",
    "publicId": "waiver-test",
    "threatLevel": 7,
    "reachable": null,
    "pathForward": true,
    "creatorId": "admin",
    "creatorName": "Admin BuiltIn",
    "createTime": "2024-12-11T16:44:47.464+0000"
}

The response contains details for the Automated Waiver created for the policy violation requested.