# Vulnerability Custom Attributes REST API

The Vulnerability Custom Attributes REST API allows you to customize the attributes of a vulnerability, such as CWE ID, CVSS vector string, severity, and remediation. Customizing the vulnerability attributes to match your development environment can help with prioritizing the remediation of vulnerabilities. These values will override Sonatype-provided values. You can set up policy constraints based on these custom attributes.

## User Permissions Required to Invoke this API call

- Edit IQ Elements

## Methods supported

### POST

You can create new custom vulnerability attributes, by making an authenticated HTTP POST request:

```
POST /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/{attributePath}
```

Where {ownerType: application|organization} is an owner type, {ownerId} is an owner identification, and {attributePath} is the path of the custom attribute which will be created.

The accompanying JSON payload can include the following fields:

- **ownerId**: ID for the owner matching the one used at the path serving as scope where the custom attribute applies to.
- **refId**: Reference ID for the vulnerability.
- **componentIdentifier**: JSON object representing the vulnerable component the custom attribute applies to.
- **applicationCategoryIds** (optional): Array with the IDs of the [Application Categories](https://help.sonatype.com/en/application-categories.html "Application Categories") an application must be assigned to for this custom attribute to be used.
- **comment** (optional): text sent to the [Audit Log](https://help.sonatype.com/en/audit-log.html "Audit Log") used to describe why the vulnerability data is being customized, for better traceability and accountability.

Using the POST request you can customize the following vulnerability attributes, by passing them as {attributePath}:

#### Customize the CWE ID

```
POST /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cwe
```

##### Example

```
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"ownerId":"ROOT_ORGANIZATION_ID","refId":"CVE-2023-12345","componentIdentifier":{"format":"npm","coordinates":{"packageId":"test","version":"0.0.1"}},"applicationCategoryIds":["17c59bf0674f404281dd2bbbda139ba2"],"cwe":"678","comment":"Just for audit log"}' 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cwe'
```

In this request, **678** is the custom CWE ID for the vulnerability **CVE-2023-12345** and the component identifier refers to NPM component **test** version **0.0.1** under the **Root organization** and applies for applications assigned to the category with ID **17c59bf0674f404281dd2bbbda139ba2**.

You can set multiple custom CWE IDs using a comma-separated list.

#### Customize the CVSS Vector String

```
POST /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/vector
```

##### Example

```
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"ownerId":"ROOT_ORGANIZATION_ID","refId":"CVE-2023-12345","componentIdentifier":{"format":"npm","coordinates":{"packageId":"test","version":"0.0.1"}},"applicationCategoryIds":["17c59bf0674f404281dd2bbbda139ba2"],"vector":"some/custom/vector","comment":"Just for audit log"}' 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cvss/vector'
```

In this request payload, **some/custom/vector** is the custom CVSS Vector for the vulnerability **CVE-2023-12345** and the component identifier refers to NPM component **test** version **0.0.1** under the **Root organization** and only applies for applications assigned to the category with ID **17c59bf0674f404281dd2bbbda139ba2**.

#### Customize the Severity

```
POST /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/severity
```

##### Example

```
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"ownerId":"ROOT_ORGANIZATION_ID","refId":"CVE-2023-12345","componentIdentifier":{"format":"npm","coordinates":{"packageId":"test","version":"0.0.1"}},"applicationCategoryIds":["17c59bf0674f404281dd2bbbda139ba2"],"severity":5.5,"comment":"Just for audit log"}' 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cvss/severity'
```

In this request payload **5.5** is the custom severity for the vulnerability **CVE-2023-12345** and the NPM component **test** version **0.0.1** under the **Root organization** and only applies for applications assigned to the category with ID **17c59bf0674f404281dd2bbbda139ba2**.

The custom severity can be a number 0.0 and 10.0.

#### Set Custom Remediation

```
POST /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/remediation
```

##### Example

```
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"ownerId":"ROOT_ORGANIZATION_ID","refId":"CVE-2023-12345","componentIdentifier":{"format":"npm","coordinates":{"packageId":"test","version":"0.0.1"}},"applicationCategoryIds":["17c59bf0674f404281dd2bbbda139ba2"],"remediation":"Some custom instructions","comment":"Just for audit log"}' 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/remediation'
```

In this request payload **Some custom instructions** is the custom remediation for the vulnerability **CVE-2023-12345** and the NPM component **test** version **0.0.1** under the **Root organization** and only applies for applications assigned to the category with ID **17c59bf0674f404281dd2bbbda139ba2**.

#### Updating the custom vulnerability attributes

You can update a previously customized vulnerability attribute by making an authenticated HTTP POST request to the same endpoints as above and including the ID of the custom attribute to update:

##### Example

```
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"id": "bd40c64b493042f9944d73ac3241fab7", "ownerId":"ROOT_ORGANIZATION_ID","refId":"CVE-2023-12345","componentIdentifier":{"format":"npm","coordinates":{"packageId":"test","version":"0.0.1"}},"applicationCategoryIds":["17c59bf0674f404281dd2bbbda139ba2"],"cwe":"90","comment":"Just for audit log"}' 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cwe'
```

In this request **90** is the new custom CWE ID for the existing Vulnerability Custom Attribute with ID **bd40c64b493042f9944d73ac3241fab7**.

#### Response

On successful execution of all POST requests above, the return value is the ID of the created or updated custom vulnerability attribute:

```
bd40c64b493042f9944d73ac3241fab7
```

### DELETE

You can delete an existing custom vulnerability attribute by making an authenticated HTTP DELETE request:

```
DELETE /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/{attributePath}/{vulnerabilityCustomAttributeId}
```

Where {ownerType: application|organization} is an owner type, {ownerId} is an owner identification, {attributePath} is the specific vulnerability custom attribute and {vulnerabilityCustomAttributeId} is the ID of the custom vulnerability attribute to delete.

Using the DELETE request you can delete the following vulnerability attributes:

- CWE ID
- CVSS vector string
- Severity
- Delete custom remediation

#### Delete a custom CWE ID

```
DELETE /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cwe/{vulnerabilityCustomAttributeId}
```

##### Example

```
curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cwe/bd40c64b493042f9944d73ac3241fab7'
```

Where **bd40c64b493042f9944d73ac3241fab7** is the custom vulnerability attribute ID to be deleted.

#### Delete a Custom CVSS Vector String

```
DELETE /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/vector/{vulnerabilityCustomAttributeId}
```

##### Example

```
curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cvss/vector/bd40c64b493042f9944d73ac3241fab7'
```

Where **bd40c64b493042f9944d73ac3241fab7** is the custom vulnerability attribute ID to be deleted.

#### Delete a Custom Severity

```
DELETE /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/severity/{vulnerabilityCustomAttributeId}
```

##### Example

```
curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cvss/severity/bd40c64b493042f9944d73ac3241fab7'
```

Where **bd40c64b493042f9944d73ac3241fab7** is the custom vulnerability attribute ID to be deleted.

#### Delete a Custom Remediation

```
DELETE /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/remediation/{vulnerabilityCustomAttributeId}
```

##### Example

Where **bd40c64b493042f9944d73ac3241fab7** is the custom vulnerability attribute ID to be deleted.

#### Response

A return HTTP 204 code indicates the successful execution of all DELETE requests above.

### GET

You can retrieve data for an existing custom vulnerability attribute by making an authenticated HTTP GET request:

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/{attributePath}/{vulnerabilityCustomAttributeId}
```

Where {ownerType: application|organization} is an owner type, {ownerId} is an owner identification, {attributePath} is the specific custom vulnerability attribute and {vulnerabilityCustomAttributeId} is the ID of the custom vulnerability attribute to retrieve.

Using the GET request you can retrieve the following vulnerability attributes:

- CWE ID
- CVSS vector string
- Severity
- Custom remediation

In scenarios, where the component refID and a URL encoded JSON that indicates where the vulnerability applies, is available, you can provide these to retrieve the custom vulnerability attributes.

#### Retrieve the CWE ID

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cwe/{vulnerabilityCustomAttributeId}
```

##### Example

```
curl -u admin:admin123 -X GET 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cwe/bd40c64b493042f9944d73ac3241fab7'
```

Where **bd40c64b493042f9944d73ac3241fab7** is the custom vulnerability attribute ID to retrieve.

#### Response

On successful execution of the GET request, the response JSON returns the CWE corresponding to the custom vulnerability attribute ID provided:

```
{
  "id":"bd40c64b493042f9944d73ac3241fab7",
  "ownerId":"ROOT_ORGANIZATION_ID",
  "refId":"CVE-2023-12345",
  "componentIdentifier":{
    "format":"npm",
    "coordinates":{
      "packageId":"test",
      "version":"0.0.1"
    }
  },
  "applicationCategoryIds":[
    "17c59bf0674f404281dd2bbbda139ba2"
  ],
  "cwe":"678"
}
```

#### Retrieve the CVSS vector string

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/vector/{vulnerabilityCustomAttributeId}
```

##### Example

```
curl -u admin:admin123 -X GET 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cvss/vector/bd40c64b493042f9944d73ac3241fab7'
```

Where **bd40c64b493042f9944d73ac3241fab7** is the custom vulnerability attribute ID to retrieve.

#### Response

On successful execution of the GET request, the response JSON returns the CVSS vector string corresponding to the custom vulnerability attribute ID provided:

```
{
  "id":"bd40c64b493042f9944d73ac3241fab7",
  "ownerId":"ROOT_ORGANIZATION_ID",
  "refId":"CVE-2023-12345",
  "componentIdentifier":{
    "format":"npm",
    "coordinates":{
      "packageId":"test",
      "version":"0.0.1"
    }
  },
  "applicationCategoryIds":[
    "17c59bf0674f404281dd2bbbda139ba2"
  ],
  "vector":"some/custom/vector"
}
```

#### Retrieve the Severity

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/severity/{vulnerabilityCustomAttributeId}
```

##### Example

```
curl -u admin:admin123 -X GET 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/cvss/severity/bd40c64b493042f9944d73ac3241fab7'
```

Where **bd40c64b493042f9944d73ac3241fab7** is the custom vulnerability attribute ID to retrieve.

#### Response

On successful execution of the GET request, the response JSON returns the severity corresponding to the custom vulnerability attribute ID provided:

```
{
  "id":"bd40c64b493042f9944d73ac3241fab7",
  "ownerId":"ROOT_ORGANIZATION_ID",
  "refId":"CVE-2023-12345",
  "componentIdentifier":{
    "format":"npm",
    "coordinates":{
      "packageId":"test",
      "version":"0.0.1"
    }
  },
  "applicationCategoryIds":[
    "17c59bf0674f404281dd2bbbda139ba2"
  ],
  "severity":5.5
}
```

#### Retrieve the Custom Remediation

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/remediation/{vulnerabilityCustomAttributeId}
```

##### Example

```
curl -u admin:admin123 -X GET 'http://localhost:8070/api/experimental/vulnerability/customData/organization/ROOT_ORGANIZATION_ID/remediation/bd40c64b493042f9944d73ac3241fab7'
```

Where **bd40c64b493042f9944d73ac3241fab7** is the custom vulnerability attribute ID to retrieve.

#### Response

On successful execution of the GET request, the response JSON returns the custom remediation text corresponding to the custom vulnerability attribute ID provided:

```
{
  "id":"bd40c64b493042f9944d73ac3241fab7",
  "ownerId":"ROOT_ORGANIZATION_ID",
  "refId":"CVE-2023-12345",
  "componentIdentifier":{
    "format":"npm",
    "coordinates":{
      "packageId":"test",
      "version":"0.0.1"
    }
  },
  "applicationCategoryIds":[
    "17c59bf0674f404281dd2bbbda139ba2"
  ],
  "remediation":"Some custom instructions"
}
```

#### Retrieve custom vulnerability attributes by passing component refID and a URL encoded JSON that indicates where the vulnerability applies

You can retrieve the custom vulnerability attribute for a vulnerability under a given scope (application, organization or root) by making an authenticated HTTP GET request:

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/{attributePath}/refId/{refId}?componentIdentifier={componentIdentifierJson}
```

Where {ownerType: application|organization} is an owner type or scope, {ownerId} is an owner identification (application ID or organization ID), {attributePath} is the specific custom vulnerability attribute, {refId} is the CVE of the vulnerability to retrieve and {componentIdentifierJson} is the URL encoded JSON representation of the component identifier where the vulnerability applies.

#### Retrieve the CWE ID

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cwe/refId/{refId}?componentIdentifier={componentIdentifierJson}
```

##### Example

```
curl -u admin:admin123 -X GET 'http://localhost:8070/api/experimental/vulnerability/customData/application/aa6aee4d80624f80bba6e90a75ffd677/cwe/refId/CVE-2023-12345?componentIdentifier=%7B%22format%22%3A%22npm%22%2C%22coordinates%22%3A%7B%22packageId%22%3A%22test%22%2C%22version%22%3A%220.0.1%22%7D%7D
```

Where **aa6aee4d80624f80bba6e90a75ffd677** is an application ID and **CVE-2023-12345** is the vulnerability's refID.

#### Response

On successful execution of the GET request, the response JSON returns the CWE-ID for the component found where the vulnerability applies (provided as URL encoded as JSON.)

NOTE: The scope or owner type passed in the GET request for this response was "application," but the return response shows ROOT_ORGANIZATION_ID. This is because when no data is found for the scope specified in the GET request, it fetches data related to the next higher element in the application and organization hierarchy.

#### Retrieve the CVSS vector string

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/vector/refId/{refId}?componentIdentifier={componentIdentifierJson}
```

##### Example

```
curl -u admin:admin123 -X GET 'http://localhost:8070/api/experimental/vulnerability/customData/application/aa6aee4d80624f80bba6e90a75ffd677/cvss/vector/refId/CVE-2023-12345?componentIdentifier=%7B%22format%22%3A%22npm%22%2C%22coordinates%22%3A%7B%22packageId%22%3A%22test%22%2C%22version%22%3A%220.0.1%22%7D%7D
```

Where **aa6aee4d80624f80bba6e90a75ffd677** is an application ID and **CVE-2023-12345** is the vulnerability refID.

#### Response

On successful execution of the GET request, the response JSON returns the CVSS vector string for the component found where the vulnerability applies (provided as URL encoded as JSON.)

#### Retrieve the Severity

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/cvss/severity/refId/{refId}?componentIdentifier={componentIdentifierJson}
```

##### Example

```
curl -u admin:admin123 -X GET 'http://localhost:8070/api/experimental/vulnerability/customData/application/aa6aee4d80624f80bba6e90a75ffd677/cvss/severity/refId/CVE-2023-12345?componentIdentifier=%7B%22format%22%3A%22npm%22%2C%22coordinates%22%3A%7B%22packageId%22%3A%22test%22%2C%22version%22%3A%220.0.1%22%7D%7D
```

Where **aa6aee4d80624f80bba6e90a75ffd677** is an application ID and **CVE-2023-12345** is the vulnerability refID.

#### Response

On successful execution of the GET request, the response JSON returns the severity for the component found where the vulnerability applies (provided as URL encoded as JSON.)

#### Retrieve the Custom Remediation

```
GET /api/experimental/vulnerability/customData/{ownerType: application|organization}/{ownerId}/remediation/refId/{refId}?componentIdentifier={componentIdentifierJson}
```

##### Example

```
curl -u admin:admin123 -X GET 'http://localhost:8070/api/experimental/vulnerability/customData/application/aa6aee4d80624f80bba6e90a75ffd677/remediation/refId/CVE-2023-12345?componentIdentifier=%7B%22format%22%3A%22npm%22%2C%22coordinates%22%3A%7B%22packageId%22%3A%22test%22%2C%22version%22%3A%220.0.1%22%7D%7D
```

Where **aa6aee4d80624f80bba6e90a75ffd677** is an application ID and **CVE-2023-12345** is the vulnerability refID.

#### Response

On successful execution of the GET request, the response JSON returns the text that was supplied as custom remediation, for the component found where the vulnerability applies (provided as URL encoded as JSON.)

The scope or owner type passed in the GET request for this response was "application," but the return response shows ROOT_ORGANIZATION_ID. This is because when no data is found for the scope specified in the GET request, it fetches data related to the next higher element in the application and organization hierarchy.