# Transitive Waivers REST API

## Transitive Violations

A transitive policy violation is a violation in the report that is brought in by a transitive dependency.

Following APIs provide a way of getting and waiving transitive violations of a component in a specific stage (e.g. Build, Stage Release, and Release) or scan.

### Get Transitive Violations by Stage ID

This API allows getting all the transitive violations for a given component from the latest stage report(s) at the given scope.

#### Request

```
GET api/v2/policyViolations/transitive/{ownerType: application|organization}/{ownerId}/stages/{stage}?componentIdentifier={componentIdentifier}&packageUrl={packageUrl}&hash={hash}
```

Here is a description of the properties of the request:

| Property            | Description                                                                               |
|---------------------|-------------------------------------------------------------------------------------------|
| ownerType           | Scope (application, organization, or root organization)                                   |
| ownerId             | organizationId for ownerType: `organization`<br>application name for ownerType: `application` |
| stage               | Stage ID                                                                                   |
| componentIdentifier* | Component Identifier of the component                                                     |
| packageUrl*        | Package Url of the Component                                                               |
| hash*              | Hash of the component                                                                      |

**Note**  
Only one of componentIdentifier or packageUrl or hash is required. If multiple are supplied we favor them in the order specified here.

Assuming a local installation of IQ Server with its default configuration, the following example using the `cURL` tool finds the transitive policy violations for a component using its packageUrl:

```
curl -u admin:admin123 --request GET 'http://localhost:8070/api/v2/policyViolations/transitive/application/npm/stages/build?packageUrl=pkg:npm/%40iarna/cli@1.2.0'
```

The server returns the list of transitive policy violations related to the component. A sample response would be as follows:

```
{
    "componentIdentifier": {
        "format": "npm",
        "coordinates": {
            "packageId": "@iarna/cli",
            "version": "1.2.0"
        }
    },
    "packageUrl": "pkg:npm/%40iarna/cli@1.2.0",
    "hash": "0f7af5e851afe8951045",
    "displayName": "@iarna/cli : 1.2.0",
    "isInnerSource": false,
    "transitivePolicyViolations": [
        {
            "policyId": "1df00277de9041a29f0f4b2537b0501e",
            "policyName": "Architecture-Quality",
            "threatLevel": 1,
            "threatCategory": "quality",
            "policyViolationId": "3063a76f84624e12bb715f0b8ae1c824",
            "componentIdentifier": {
                "format": "npm",
                "coordinates": {
                    "packageId": "get-caller-file",
                    "version": "1.0.2"
                }
            },
            "packageUrl": "pkg:npm/get-caller-file@1.0.2",
            "hash": "f702e63127e7e231c160",
            "displayName": "get-caller-file : 1.0.2"
        },
        {
            "policyId": "1df00277de9041a29f0f4b2537b0501e",
            "policyName": "Architecture-Quality",
            "threatLevel": 1,
            "threatCategory": "quality",
            "policyViolationId": "3038a9231ba847658a319690fe3dabbf",
            "componentIdentifier": {
                "format": "npm",
                "coordinates": {
                    "packageId": "y18n",
                    "version": "3.2.1"
                }
            },
            "packageUrl": "pkg:npm/y18n@3.2.1",
            "hash": "6d15fba884c08679c0d7",
            "displayName": "y18n : 3.2.1"
        }
    ]
}
```

### Get Transitive Violations by Report ID

This API allows getting all the transitive violations for a given component in a specific scan.

#### Request

```
GET api/v2/policyViolations/transitive/{ownerType:application}/{ownerId}/{reportId}?componentIdentifier={componentIdentifier}&packageUrl={packageUrl}&hash={hash}
```

Here is a description of the properties of the request:

| Property            | Description                                                                               |
|---------------------|-------------------------------------------------------------------------------------------|
| ownerType           | Scope (application)                                                                       |
| ownerId             | Public ID of the owner<br>organizationId for ownerType: `organization`<br>application name for ownerType: `application` |
| reportId            | Report ID                                                                                 |
| componentIdentifier* | Component Identifier of the component                                                     |
| packageUrl*        | Package Url of the Component                                                               |
| hash*              | Hash of the component                                                                      |

**Note**  
Only one of componentIdentifier or packageUrl or hash is required. If multiple are supplied we favor them in the order specified here.

**Note**  
The Report ID can be obtained by [Report Related REST API](https://help.sonatype.com/en/report-rest-api.html "Report REST APIs").

```
curl -u admin:admin123 --request GET 'http://localhost:8070/api/v2/policyViolations/transitive/application/npm/df7d9a3b7fd044809ec032e464c54541?packageUrl=pkg:npm/%40iarna/cli@1.2.0'
```

The server returns the list of transitive policy violations related to the component. A sample response would be as follows:

### Group Waiving Transitive Violations for a given component in a scan

This API allows group waiving of all transitive violations for a given component in a specific scan.

#### Request

```
POST api/v2/policyWaivers/transitive/{ownerType:application}/{ownerId}/{reportId}?componentIdentifier={componentIdentifier}&packageUrl={packageUrl}&hash={hash}
```

Here is a description of the properties of the request:

| Property            | Description                                                                               |
|---------------------|-------------------------------------------------------------------------------------------|
| ownerType           | Scope (application)                                                                       |
| ownerId             | organizationId for ownerType: `organization`<br>application name for ownerType: `application` |
| reportId            | Report ID                                                                                 |
| componentIdentifier* | Component Identifier of the component                                                     |
| packageUrl*        | Package Url of the Component                                                               |
| hash*              | Hash of the component                                                                      |

**Note**  
Only one of componentIdentifier or packageUrl or hash is required. If multiple are supplied we favor them in the order specified here.

**Note**  
The Report ID can be obtained by [Report Related REST API](https://help.sonatype.com/en/report-rest-api.html "Report REST APIs").

With the POST request, you will need to provide the waiving details in the payload.

```
{
    "expiryTime" :  "2021-06-30T00:00:00.000+0000" ,
    "comment" :  "Test Comment"
}
```

Both **expiryTime**and **comment** are optional, if **expiryTime**is not set it means the waiver will never expire.

Assuming a local installation of IQ Server with its default configuration, the following example using the `cURL` tool waives the transitive policy violations for a component in a scan using its packageUrl:

```
curl -u admin:admin123 --request POST 'http://localhost:8070/api/v2/policyWaivers/transitive/application/npm/df7d9a3b7fd044809ec032e464c54541?packageUrl=pkg:npm/%40iarna/cli@1.2.0' --header 'Content-Type: application/json' --data-raw '{"expiryTime": "2021-06-30T00:00:00.000+0000","comment" :"Test Comment"}'
```

#### Response

The server will respond with a 204 status upon success.

### Group Waiving Transitive Violations for a given component in a specific stage

This API allows group waiving of all transitive violations for a given component from the latest stage report(s) at the given scope.

#### Request

```
POST api/v2/policyWaivers/transitive/{ownerType:application|organization}/{ownerId}/stages/{stageId}?componentIdentifier={componentIdentifier}&packageUrl={packageUrl}&hash={hash}
```

Here is a description of the properties of the request:

**Note**  
Only one of componentIdentifier or packageUrl or hash is required. If multiple are supplied we favor them in the order specified here.

With the POST request, you will need to provide the waiving details in the payload.

```
{
    "expiryTime" :  "2021-06-30T00:00:00.000+0000" ,
    "comment" :  "Test Comment"
}
```

Both **expiryTime**and **comment** are optional, if **expiryTime**is not set it means the waiver will never expire.

Assuming a local installation of IQ Server with its default configuration, the following example using the `cURL` tool waives the transitive policy violations for a component using its packageUrl:

```
curl -u admin:admin123 --request POST 'http://localhost:8070/api/v2/policyWaivers/transitive/application/npm/stages/build?packageUrl=pkg:npm/%40iarna/cli@1.2.0' --header 'Content-Type: application/json' --data-raw '{"expiryTime": "2021-06-30T00:00:00.000+0000","comment" :"Test Comment"}'
```

#### Response

The server will respond with a 204 status upon success.

#### Other Related REST APIs

1. [Policy Waiver REST API](https://help.sonatype.com/en/policy-waiver-rest-api.html "Policy Waiver REST API")

2. [Applicable Waivers REST API](https://help.sonatype.com/en/applicable-waivers-rest-api.html "Applicable Waivers REST API")

3. [Component Waivers REST API](https://help.sonatype.com/en/component-waivers-rest-api.html "Component Waivers REST API")

4. [Stale Waivers REST API](https://help.sonatype.com/en/stale-waivers-rest-api.html "Stale Waivers REST API")