Component Waivers REST API
Note
All repository reports must be re-evaluated in order to include the most accurate policy waiver information used by this API.
The Component Waivers API focuses on existing policy waivers by component. The waivers can be at any scope (app, org, root org, repository, or all repositories). Waivers are listed for each stage to fully detail all the waivers for an application. Stages can carry duplicate waivers, but this accurately reflects every waiver in which a component is in one stage and not another. For repository waivers the only applicable stage is the proxy stage.
Requesting Component Waivers
To list the component waivers:
GET api/v2/reports/components/waivers
A sample request to list the component waivers is done with the following command:
curl -u admin:admin123 -X GET http://localhost:8070/api/v2/reports/components/waivers
This API currently supports filtering by component format/ecosystem. To retrieve waivers only for components in a particular ecosystem, for example maven, add a "format" query parameter to the URL as follows:
GET api/v2/reports/components/waivers?format=maven
Response Description
The server will respond with JSON that groups waivers by application components and repository components. The waived application violations will be listed per stage and include the waiver details. Similarly, the waived repository violations will be listed in the proxy stage and include waiver details.
Here is a brief outline of the response which describes the high-level object composition. For the full response details continue to the Response Sample.
Response Outline
{
"applicationWaivers": [
{
"application": {},
"stages": [
{
"stageId": "build",
"componentPolicyViolations": [
{
"component": {},
"waivedPolicyViolations": [
{
"policyWaiver": {
"policyWaiverId": "e8f43ba30718456eadad6f0616f4c68e",
"comment": "temporary waiver",
"isObsolete": false,
"createTime": "2019-10-16T20:52:27.659+0000",
"expiryTime": "2019-10-23T00:00:00.000+0000",
"reasonId": "Not reachable",
"policyWaiverReasonId": "policyWaiverReasonId",
"scopeOwnerType": "root_organization",
"scopeOwnerId": "ROOT_ORGANIZATION_ID",
"scopeOwnerName": "Root Organization",
"hash": "1249e25aebb15358bedd",
"policyId": "775a6e88799040c5bb2dd8f020124d07",
"creatorId": "authorizedUser",
"creatorName": "Authorized User",
"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"
}
},
"displayName": {
"parts": [
{
"field": "Group",
"value": "commons-beanutils"
},
{
"value": " : "
},
{
"field": "Artifact",
"value": "commons-beanutils"
},
{
"value": " : "
},
{
"field": "Version",
"value": "1.8.3"
}
],
"name": "commons-beanutils"
}
}
}
]
}
]
},
{
"stageId": "release",
"componentPolicyViolations": [
{
"component": {},
"waivedPolicyViolations": [
{
"policyWaiver": {
"comment": "The waiver cannot be found. Please re-evaluate.",
"isObsolete": true
}
}
]
}
]
}
]
}
],
"repositoryWaivers": [
{
"repository": {},
"stages": [
{
"stageId": "proxy",
"componentPolicyViolations": [
{
"component": {},
"waivedPolicyViolations": [
{
"policyWaiver": {
"policyWaiverId": "e8f43ba30718456eadad6f0616f4c68e",
"comment": "temporary waiver",
"isObsolete": false,
"createTime": "2019-10-16T20:52:27.659+0000",
"scopeOwnerType": "root_organization",
"scopeOwnerId": "ROOT_ORGANIZATION_ID",
"scopeOwnerName": "Root Organization",
"hash": "1249e25aebb15358bedd",
"policyId": "775a6e88799040c5bb2dd8f020124d07",
"creatorId": "authorizedUser",
"creatorName": "Authorized User",
"matcherStrategy": "EXACT_COMPONENT",
"associatedPackageUrl": "pkg:maven/commons-beanutils/commons-beanutils@1.8.4?type=jar",
"componentIdentifier": {
"format": "maven",
"coordinates": {
"artifactId": "commons-beanutils",
"extension": "jar",
"groupId": "commons-beanutils",
"version": "1.8.4"
}
},
"displayName": {
"parts": [
{
"field": "Group",
"value": "commons-beanutils"
},
{
"value": " : "
},
{
"field": "Artifact",
"value": "commons-beanutils"
},
{
"value": " : "
},
{
"field": "Version",
"value": "1.8.4"
}
],
"name": "commons-beanutils"
}
}
}
]
}
]
}
]
}
]
}Item | Description |
|---|---|
applicationWaivers | List of applications that have waived violations. |
application | Application details. |
repositoryWaivers | List of repositories that have waived violations |
repository | Repository details |
stages | List of stages applicable for the violations of the repository or application |
stageId | Stage of the waived violations |
componentPolicyViolations | List of components and their waived violations |
component | Component details. |
waivedPolicyViolations | List of waived policy violation details that applied to a component. |
policyWaiver | Waiver details for a waived policy violation. |
policyWaiverId | The ID of the policy waiver when there is an active waiver for the violation. |
scopeOwnerType | The owner type of the policy waiver's scope. Applies for waivers that are not obsolete. |
scopeOwnerId | The owner ID of the policy waiver's scope. Applies for waivers that are not obsolete. |
scopeOwnerName | The owner name of the policy waiver's scope. Applies for waivers that are not obsolete. |
hash | The hash of the component the policy waiver applies to. May be null if the waiver applies to all components or all versions of a component. |
policyId | The ID of policy the policy waiver applies to. |
isObsolete | Indicates |
comment | The policy waiver comment when there is an active waiver for the violation. If the waiver is obsolete then there will be a message indicating the waiver cannot be found and re-evaluation is necessary. This item has no character restrictions. Appropriate measures should be taken in order to prevent security issues such as Injection and Cross-Site Scripting (XSS). |
createTime | The date and time the policy waiver was created when there is an active waiver for the violation. Note: This is not the time the violation was waived during an evaluation. |
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. Note: This API will not return any waivers that have already expired, i.e. this field containing an expiration date in the past. |
policyWaiverReasonId | The policy waiver reason id associated with the waiver reason. |
reasonText | The reason for applying/requesting this waiver (e.g., Acknowledged violation, Mitigated externally, No upgrade path, Not reachable, Not exploitable, Researching, Other). |
creatorId | the id (username) of the user that 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 | Package URL of the component, only present if the waiver is of type ALL_VERSIONS or EXACT_COMPONENT and is not an unknown component. |
componentIdentifier | Component identifier of the component, only present if the waiver is of type ALL_VERSIONS or EXACT_COMPONENT and is not an unknown component. |
displayName | Display name of the component, only present if the waiver is of type ALL_VERSIONS or EXACT_COMPONENT and is not an unknown component. |
Sample Response
A sample response returned by the API:
Sample Response
{
"applicationWaivers": [
{
"application": {
"id": "0d3fa305cb8d4ff4b9442d29816cf24c",
"publicId": "application",
"name": "Application - TestApp",
"organizationId": "e40aed6067cc431491d42154c1257ed6",
"contactUserName": null
},
"stages": [
{
"stageId": "build",
"componentPolicyViolations": [
{
"component": {
"packageUrl": "pkg:maven/commons-beanutils/commons-beanutils@1.8.3?type=jar",
"hash": "686ef3410bcf4ab8ce7f",
"componentIdentifier": {
"format": "maven",
"coordinates": {
"artifactId": "commons-beanutils",
"classifier": "",
"extension": "jar",
"groupId": "commons-beanutils",
"version": "1.8.3"
}
},
"displayName": "commons-beanutils : commons-beanutils : 1.8.3"
},
"waivedPolicyViolations": [
{
"policyId": "d378f2c0bb2d404bbec04cd5f894188b",
"policyName": "Security-High",
"policyViolationId": "5e02da4a230049feb08da590eceb3258",
"threatLevel": 9,
"constraintViolations": [
{
"constraintId": "6b68cdbe13884c779e44d643062b4b1c",
"constraintName": "High risk CVSS score",
"reasons": [
{
"reason": "Found security vulnerability CVE-2014-0114 with severity >= 7 (severity = 7.5)",
"reference": {
"type": "SECURITY_VULNERABILITY_REFID",
"value": "CVE-2014-0114"
}
},
{
"reason": "Found security vulnerability CVE-2014-0114 with severity < 9 (severity = 7.5)",
"reference": {
"type": "SECURITY_VULNERABILITY_REFID",
"value": "CVE-2014-0114"
}
}
]
}
],
"policyWaiver": {
"policyWaiverId": "9fc1ee3f2761458380d2135ef01135f4",
"comment": "",
"createTime": "2022-10-07T21:49:00.051+0000",
"expiryTime": "2022-10-22T04:59:59.999+0000",
"reasonText": "Not exploitable",
"policyWaiverReasonId": "f6990a32cd8d4ea78853ca829d948927",
"isObsolete": false,
"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",
"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"
}
}
}
]
},
{
"component": {
"packageUrl": "pkg:maven/org.sonatype.nexus/nexus-rest-client@3.25.1-01?classifier=sources&type=jar",
"hash": "3ef19d8647bc8031ee94",
"componentIdentifier": {
"format": "maven",
"coordinates": {
"artifactId": "nexus-rest-client",
"classifier": "sources",
"extension": "jar",
"groupId": "org.sonatype.nexus",
"version": "3.25.1-01"
}
},
"displayName": "org.sonatype.nexus : nexus-rest-client : jar : sources : 3.25.1-01"
},
"waivedPolicyViolations": [
{
"policyId": "a9f5f3450375455b8335e02a1ee222db",
"policyName": "Component-Similar",
"policyViolationId": "4b8e59f540424081965533a668b568ba",
"threatLevel": 7,
"constraintViolations": [
{
"constraintId": "c6b8ac4472d24f29bfa8a1d79f28653e",
"constraintName": "Unknown modification to component",
"reasons": [
{
"reason": "Match state was 'Similar'",
"reference": null
},
{
"reason": "Coordinates were org.sonatype.nexus : nexus-rest-client : jar : sources : 3.25.1-01 (do not match org.eclipse.* : * : * : * : *)",
"reference": null
}
]
}
],
"policyWaiver": {
"policyWaiverId": "88a3cca014dd4122ae24b07e3d2477cb",
"comment": "",
"createTime": "2022-10-07T21:29:39.111+0000",
"expiryTime": "2022-11-07T04:59:59.999+0000",
"reasonText": "Not exploitable",
"policyWaiverReasonId": "f6390a32cd8d2ea78453ca829d948927",
"isObsolete": false,
"scopeOwnerType": "application",
"scopeOwnerId": "0d3fa305cb8d4ff4b9442d29816cf24c",
"scopeOwnerName": "Application - TestApp",
"hash": "3ef19d8647bc8031ee94",
"policyId": "a9f5f3450375455b8335e02a1ee222db",
"creatorId": "admin",
"creatorName": "Admin BuiltIn",
"matcherStrategy": "EXACT_COMPONENT",
"associatedPackageUrl": "pkg:maven/org.sonatype.nexus/nexus-rest-client@3.25.1-01?classifier=sources&type=jar",
"componentIdentifier": {
"format": "maven",
"coordinates": {
"artifactId": "nexus-rest-client",
"classifier": "sources",
"extension": "jar",
"groupId": "org.sonatype.nexus",
"version": "3.25.1-01"
}
},
"displayName": {
"parts": [
{
"field": "Group",
"value": "org.sonatype.nexus"
},
{
"value": " : "
},
{
"field": "Artifact",
"value": "nexus-rest-client"
},
{
"value": " : "
},
{
"field": "Extension",
"value": "jar"
},
{
"value": " : "
},
{
"field": "Classifier",
"value": "sources"
},
{
"value": " : "
},
{
"field": "Version",
"value": "3.25.1-01"
}
],
"name": "nexus-rest-client"
}
}
}
]
}
]
}
]
}
],
"repositoryWaivers": []
}Note
The returned component hash value is truncated and is meant to be used as an identifier that can be passed into subsequent REST API calls. It is not intended to be used as a checksum.