Stale Waivers REST API - v2
NEW IN RELEASE 84
The Stale Waivers REST API reports waivers that are stale. A waiver is considered to be stale when it is not used in IQ Server. Examples are:
- A waiver applied in an evaluation and later skipped in another evaluation because the violation it waived does not exist anymore (perhaps due to component upgrade) is a stale waiver
- A waiver added but not applied because there was no evaluation is a stale waiver (it is not used until there is an evaluation)
A list of stale waivers is useful to identify potential risks in future evaluations because it helps to determine where violations can be unintentionally waived.
Stale evaluations listed under stale waivers help determine where evaluations may be needed in order to verify that the waivers are truly not used. An application or repository evaluation is considered to be stale if a new waiver has been created since the last evaluation.
All repository reports must be re-evaluated after Nexus IQ Server version 76 in order to include the most accurate policy waiver information used by the new API.
Scope of waivers and user permissions
Only the stale waivers that the specific user has permissions to see will be returned, even though the computation of staleness of a waiver can include applications and/or repositories that the user does not have permissions to see.
For example, when Organization A has Application 1 and Application 2, and a user has permissions to only Application 1, the user will see waivers scoped to Organization A because Application 1 is too under the scope of those waivers, but the user will not see waivers scoped to Application 2 because Application 1 is not under the scope of those waivers. Also, the computation of staleness of a waiver scoped to Organization A will include both Application 1 and Application 2, even if the user has only access to Application 1.
In the case of stale evaluations, only applications and repositories that are stale and that the user has permissions to see will be returned.
Before performing any actions on stale waivers it is recommended to have complete visibility of what can be affected. This can be achieved by calling the API with sufficient user permissions (preferably an admin user).
Requesting Stale Waivers
An HTTP GET method is used to list the Stale Waivers:
GET /api/v2/reports/waivers/stale
A sample request to list the stale waivers is done by issuing the following curl command:
curl -u admin:admin123 -X GET 'http://localhost:8070/api/v2/reports/waivers/stale'
Response description
The response is a JSON object with the property "staleWaivers". This property has an array with stale waivers.
Here is a sample response:
{
"staleWaivers": [
{
"waiverId": "943d67ad7b904ea092ce0487a99b358e",
"policyId": "112b8420643b4219a7775ba5d37889b5",
"policyName": "Security-Critical",
"comment": "",
"scopeOwnerType": "root_organization",
"scopeOwnerId": "ROOT_ORGANIZATION_ID",
"scopeOwnerName": "Root Organization",
"createTime": "2020-01-21T20:56:35.803+0000",
"expiryTime": "2020-02-21T20:56:35.803+0000",
"creatorId": "authorizedUser",
"creatorName": "Authorized User",
"constraintFacts": [
{
"constraintName": "Critical risk CVSS score",
"constraintId": "5ec402530f6849dab3066d6a598fd7d2",
"reasons": [
{
"reason": "Found security vulnerability sonatype-2015-0002 with severity >= 9 (severity = 9.0)"
}
]
}
],
"staleEvaluations": {
"applications": [
{
"application": {
"id": "887474a442524a8e950cb90e906b53a8",
"publicId": "webgoat",
"name": "WebGoat",
"organizationId": "b301c86db103482cb276f4c9ca388d9f",
"contactUserName": null
},
"stages": [
{
"stageId": "build",
"lastEvaluationDate": "2020-01-21T20:55:44.362+0000"
}
]
}
],
"repositories": [
{
"repository": {
"repositoryId": "2c52468043374959946a679082c72434",
"publicId": "maven-central-proxy",
"format": "maven2"
},
"stages": [
{
"stageId": "proxy",
"lastEvaluationDate": "2020-01-21T20:48:30.433+0000"
}
]
}
]
}
}
]
}Here is a description of the properties of a stale waiver:
| Item | Description |
|---|---|
| waiverId | ID of the stale waiver. |
| policyId | ID of the policy. |
| policyName | Name of the policy. |
| comment | Comment of the waiver. |
| scopeOwnerType | The owner type of the policy waiver's scope. |
| scopeOwnerId | The owner id of the policy waiver's scope. |
| scopeOwnerName | The owner name of the policy waiver's scope. |
| createTime | Time at which the waiver was created. |
NEW IN RELEASE 101 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. |
| constraintFacts | Constraint facts that were copied over from policy violation during waiver creation. |
NEW IN RELEASE 85 staleEvaluations | Lists applications and/or repositories under the scope of the waiver that have not been re-evaluated since the waiver was added. |
NEW IN RELEASE 85 stages | Date and time of the last evaluation for each of the stages. Repositories will only have the "proxy" stage. |
NEW IN RELEASE 131 creatorId | the id (username) of the user that created the waiver |
NEW IN RELEASE 131 creatorName | the full name of the user that created the waiver |