Skip to main content

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 an application must be assigned to for this custom attribute to be used. Application categories can only be set when setting this custom attribute under an organization's scope.

  • comment (optional): text sent to the 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-12345and 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-12345and 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 payload5.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 90is 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/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.

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.

{
  "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/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.)

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.

{
  "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/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.)

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.

{
  "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/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.

{
  "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"
}