Skip to main content

REST APIs 25.3

Vulnerabilities

Vulnerabilities are defined as entries based on the possible risk of allowing traffic on a port/protocol combination, and a vulnerability instance is the existence of a vulnerability.

This Public Experimental API lists, creates, updates, and deletes vulnerabilities.

Note

The Illumio Core Vulnerability Maps license is required to import Qualys report data into the Illumio PCE. For information about obtaining the Illumio Core Vulnerability Maps license, contact Illumio Support. When you obtain your license, you also receive information about how to install it.

Delete the Vulnerability License

To delete the vulnerability license, use the following CURL command from your CLI environment:

export API_KEY=api_key_username:api_key_secret
curl -i -H "Content-Type: application/json" https://pce_fqdn:8443/api/v2/orgs/org_id/licenses/9df01357-93cf-4f33-b720-e47bba783c55 -X DELETE -u $API_KEY

Replace the variables, which are entered in blue bold.

Vulnerability API Methods

Functionality

HTTP

URI

Get vulnerabilities

GET

[api_version][org_href]vulnerabilities

Get an individual vulnerability.

GET

[api_version][org_href][vulnerabilities_href]

Create an individual vulnerability.

POST

[api_version][org_href][vulnerabilities_href]

Modify an individual vulnerability.

PUT

[api_version][org_href][vulnerabilities_href]

Delete an individual vulnerability.

DELETE

[api_version][org_href][vulnerabilities_href]

Vulnerability Reports

This Public Experimental API creates, updates, and deletes vulnerability reports.

Note

An Illumio Core Vulnerability Maps license is required to import Qualys report data into the Illumio PCE. For information about obtaining the Illumio Core Vulnerability Maps license, contact Illumio Support. When you obtain your license, you also receive information about how to install it.

Vulnerability Reports API Methods

HTTP

Functionality

URI

GET

Get a collection of vulnerability reports.

[api_version][org_href]/vulnerability_reports

GET

Get an individual vulnerability report.

[api_version][vulnerability_reports_href]

POST

Create an individual vulnerability report.

[api_version][vulnerability_reports_href]

PUT

Update an individual vulnerability report.

[api_version][vulnerability_reports_href]

DELETE

Delete an individual vulnerability report.

[api_version][vulnerability_reports_href]

Get a Collection of Vulnerability Reports

This method gets a collection of all vulnerability reports in your organization.

By default, the maximum number of vulnerability reports returned by a GET collection is 500. For more than 500 vulnerability reports, use Asynchronous GET Collections.

Delete a Vulnerability Report

To delete an individual vulnerability report, specify the last element of its HREF, which can be obtained from the response from GET /vulnerabilities.

Delete a Vulnerability

To delete an individual vulnerability, specify its HREF, which can be obtained from the response from GET /vulnerabilities.

Vulnerabilities API Reference

This topic contains properties and examples for vulnerability APIs.

Examples of Vulnerability APIs
Get a Collection of all Vulnerabilities

This example sets the maximum number of vulnerability reports to 2. Not using this query parameter in this GET method would return all the vulnerability reports up to a maximum of 500.

Parameter

Description

Data Type

org_id

Integer

max_results

The maximum number of vulnerabilities returned by a call to

GET /vulnerabilities.

(Optional. If not specified, all vulnerabilities are returned up to a maximum of 500.)

Integer

Curl Command to Get Collection of Vulnerabilities

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/vulnerabilities -H 'Accept: application/json' -u $KEY:$TOKEN

Response Body

[ 
  {
    "href": "/orgs/2/vulnerabilities/qualys-xxxxxebe7e17",
    "name": "Host Scan Time", 
    "score": 37,
    "description": "{\"severity\":\"1\"}",
    "cve_ids": [],
    "created_at": "2017-12-21T19:15:48.000Z",
    "updated_at": "2017-12-21T19:17:26.000Z",
    "created_by": null,
    "updated_by": null
  },
...........................................................
]
Get an Individual Vulnerability

Parameters

Parameter

Description

Parameter Type

org_id

Organization

Integer

reference_id

The ID of the vulnerability to return by GET /vulnerabilities/{reference_id}.

String

Curl Command to Get an Individual Vulnerability

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/vulnerabilities/qualys-xxxxxebe7e18 -H 'Accept: application/json' -u $KEY:$TOKEN

Response Body

{
  "href": "/orgs/2/vulnerabilities/qualys-xxxxxebe7e18",
  "name": "Host Scan Time",
  "score": 37,
  "description": "{\"severity\":\"1\"}",
  "cve_ids": [],
  "created_at": "2017-12-21T19:15:48.000Z",
  "updated_at": "2017-12-21T19:17:26.000Z",
  "created_by": null,
  "updated_by": null
}
Create or Update a Vulnerability
Parameters

Parameter

Description

Parameter Type

Data Type

reference_id

The ID of the vulnerability. The reference_id is the last element

of the href property returned by a call to GET /vulnerabilities.

Path

String

score

The normalized score of the vulnerability in the range of

0 to 100 inclusive. CVSS Score can be used here with a 10x multiplier.

Body

Integer

name

The title/name of the vulnerability.

Body

String

cve-ids

The cve_ids for the vulnerability.

Body

[String]

description

An arbitrary field to store details about the vulnerability class.

Body

String

Curl Command to Create or Update Vulnerability

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/7/vulnerabilities/qualys-xxxxxebe7e18 -H 'Content-Type: application/json' -u $KEY:$TOKEN -d '{"score": 50, "cve_ids": ["CVE-2012-xxxx", "CVE-2017-xxxx"], "description": "My vulnerability test."}'

Example Request Body

{
  "score": 50, 
  "cve_ids": ["CVE-2012-xxxx", "CVE-2017-xxxx"], 
  "description": "My vulnerability test."
}

Response

On success, the system displays HTTP/1.1 204 No Content.

Request Parameter to delete a vulnerability

Parameter

Description

Parameter Type

Data Type

reference_id

The reference ID of the vulnerability.

The last element of the href property of a vulnerability

returned by a call to GET /vulnerabilities.

Path

String

Curl Command to Delete Vulnerability

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/7/vulnerabilities/qualys-xxxxxebe7e18 -u $KEY:$TOKEN

Curl Command to Get Collection of Vulnerability Reports

In this example, the maximum number of vulnerability reports is set to 2. Not using this query parameter in this GET method would return all the vulnerability reports up to a maximum of 500.

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/vulnerability_reports -H 'Accept: application/json' -u $KEY:$TOKEN

Query Parameter to Get a Collection of Vulnerability Reports

Parameter

Description

Parameter Type

Data Type

max_results

The maximum number of vulnerability reports returned by a call to GET /vulnerability_reports.

Optional. If not specified, by default, all vulnerability reports are returned up to a maximum of 500.

Query

Integer

Response Body

[ 
  {
    "href": "/orgs/2/vulnerability_reports/qualys-report-12345",
    "report_type": "qualys",
    "name": "my-report-2017-12-21-19-15-47",
    "created_at": "2017-12-21T19:15:48.000Z",
    "updated_at": "2017-12-21T19:15:48.000Z",
    "num_vulnerabilities": 4887,
    "created_by": null,
    "updated_by": null
  },
  {
    "href": "/orgs/2/vulnerability_reports/qualys-report-12346",
    "report_type": "qualys",
    "name": "my-report-2017-12-21-19-17-15",
    "created_at": "2017-12-21T19:17:15.000Z",
    "updated_at": "2017-12-21T19:17:15.000Z",
    "num_vulnerabilities": 1776,
    "created_by": null,
    "updated_by": null
  }
]
Get a Vulnerability Report

Curl Command to Get Vulnerability Report

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/vulnerability_reports/qualys-report-123456 -H 'Accept: application/json' -u $KEY:$TOKEN

Request Parameter to Get an Individual Vulnerability Report

The following required path parameter restricts the results of the GET command to the specified vulnerability report.

Parameter

Description

Parameter Type

Data Type

reference_id

The ID of the vulnerability report (this is the last element

in the vulnerability report HREF returned by a call to GET /vulnerability_reports).

Path

String

Response Body

{
  "href": "/orgs/2/vulnerability_reports/qualys-report-123456",
  "report_type": "qualys",
  "name": "my-report-2017-12-21-19-17-15",
  "created_at": "2017-12-21T19:17:15.000Z",
  "updated_at": "2017-12-21T19:17:15.000Z",
  "num_vulnerabilities": 1776,
  "created_by": null,
  "updated_by": null
}
Create or Update a Vulnerability Report

Curl Command to Update a Vulnerability Report

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/7/vulnerability_reports/qualys-report-123456 -H 'Content-Type: application/json' -u $KEY:$TOKEN -d '{"name": "My vulnerability report", "report_type": "qualys"}'

Response Properties

Property

Description

Data Type

name

User generated the name of the vulnerability report.

Integer

report_type

A string representing the type of the report.

String

authoritative

Boolean value specifies whether a report is authoritative or not.

[String]

scanned_ips

The ips on which the scan was performed.

Enforced 100K maxitem limit.

String

detected_vulnerabilities

An array of parameters, of which ip_address, workload,

and vulnerability are required.

Enforced 100K maxitem limit.

ip_address: (Required) The IP address of the host where the vulnerability is found (string)

port: The port associated with the vulnerability (integer)

proto: The protocol that is associated with the vulnerability (integer)

workload: (Required) The URI of the workload associated

with this vulnerability (string)

vulnerability: (Required) The URI of the vulnerability

class associated with this vulnerability (string)

external_data_reference

(PUT only) This parameter supports third-party reference data

state

(PUT only) Enables deletion, addition, or updating of

vulnerabilities

exported_at

(PUT only) Saves the timestamp for the next delta pull.

Example Request Body

{
  "name":"My vulnerability report",
  "report_type": "qualys",
  "authoritative": true
}

Response

On success, the system displays HTTP/1.1 204 No Content.

Curl Command to Delete Vulnerability Report

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/7/vulnerability_reports/qualys-report-2017-12-21-19-17-15 -u $KEY:$TOKEN

Request Parameter

Parameter

Description

Parameter Type

Data Type

reference_id

The ID of the vulnerability report (this is the last element in

the vulnerability report HREF returned by a call to GET /vulnerability_reports).

Path

String

Vulnerability Exposure per Enforcement Mode

Before release 24.4, the vulnerability APIs allowed users to calculate vulnerability exposure only for the full enforcement mode.

The two new and several changed common schemas now support multiple calculated values for vulnerability exposure for each enforcement mode.

The UI is updated to allow users to see the exposure scores for different enforcement modes without changing the workload's enforcement mode.

These two new schemas are referenced from the other schemas.

common vulnerability_summary_exposure
{  
    "$schema": "http://json-schema.org/draft-04/schema#",  
    "type": "object",  
    "description": "Vulnerability exposure details",  
    "properties": {    
        "vulnerable_port_exposure": {      
            "description": "The aggregated vulnerability port exposure score of the workload in the specified mode across all the vulnerable ports",      
            "type": ["integer", "null"]    
},    
    "vulnerability_exposure_score": {      
        "description": "The aggregated vulnerability exposure score of the workload in the specified mode across all vulnerable ports",      
        "type": ["integer", "null"]    
        }  
    }
}
common workloads_detected_vulnerabilities_exposure
{  
    "$schema": "http://json-schema.org/draft-04/schema#",  
    "type": "object",  
    "description": "Vulnerability exposure details for workloads",  
    "properties": {    
       "vulnerable_port_exposure": {      
         "description": "The exposure of the port based on the current policy for the specified enforcement mode",      
         "type": ["integer", "null"]    
    },    
    "port_vulnerability_exposure_score": {      
        "description": "The vulnerability exposure score calculated for the port, based on the port exposure and vulnerability for the specified enforcement mode",      
        "type": ["integer", "null"]    
        }  
    }
}
APIs Affected

The following table shows the affected vulnerability APIs:

Table 7. Vulnerability API Changes

Method

URL

Description

GET

/orgs/:xorg_id//workloads/<:id>/detected_vulnerabilities

Four new columns are being added to the workload vulnerabilities tables in the UI to support comparing exposure and ve-scores based on different enforcement types.

GET

/orgs/:xorg_id//workloads?representation=workload_labels_vulnerabilities

Four new columns are being added to the workload list tables in the UI to support comparing exposure and ve-scores for different enforcement types.

GET

/orgs/:xorg_id//workloads/:workload_id?representation=workload_labels_vulnerabilities

GET

/orgs/:xorg_id/aggregated_detected_vulnerabilities

The vulnerability scores and summary scores are now in additional tables, and scores from them are added to the response.

GET

/orgs/:xorg_id/app_groups

GET

/orgs/:xorg_id/workloads/detailed_vulnerabilities

The vulnerability data in response is not computed at runtime but is taken from the database generated by the proper stats processor.



Vulnerability Exposure per Enforcement Mode Reference

This topic contains some examples and code changes for the vulnerability APIs that regulate exposure per enforcement mode.

API Changes for Vulnerability APIs

Changes in the existing schemas are shown below.

common aggregated_detected_vulnerability

{
  "properties": {
    "aggregated_detected_vulnerabilities": {
      "items": {
        "properties": {
          "full_enforcement_vulnerability_exposure__added": {
            "$ref": "workloads_detected_vulnerabilities_exposure.schema.json",
            "description": "vulnerability exposure details for full enforcement mode"
          },
          "selective_enforcement_vulnerability_exposure__added": {
            "$ref": "workloads_detected_vulnerabilities_exposure.schema.json",
            "description": "vulnerability exposure details for selective enforcement mode"
          },
          "visibility_enforcement_vulnerability_exposure__added": {
            "$ref": "workloads_detected_vulnerabilities_exposure.schema.json",
            "description": "vulnerability exposure details for visibility-only enforcement mode"
          },
          "current_enforcement_vulnerability_exposure__added": {
            "$ref": "workloads_detected_vulnerabilities_exposure.schema.json",
            "description": "vulnerability exposure details for the current enforcement mode"
          }
        }
      }
    }
  }
}

common vulnerability_summary

{
  "properties": {
    "full_enforcement_vulnerability_exposure__added": {
      "$ref": "vulnerability_summary_exposure.schema.json",
      "description": "vulnerability exposure details for full enforcement mode"
    },
    "selective_enforcement_vulnerability_exposure__added": {
      "$ref": "vulnerability_summary_exposure.schema.json",
      "description": "vulnerability exposure details for selective enforcement mode"
    },
    "visibility_enforcement_vulnerability_exposure__added": {
      "$ref": "vulnerability_summary_exposure.schema.json",
      "description": "vulnerability exposure details for visibility-only enforcement mode"
    },
    "current_enforcement_vulnerability_exposure__added": {
      "$ref": "vulnerability_summary_exposure.schema.json",
      "description": "vulnerability exposure details for the current enforcement mode"
    },
    "max_vulnerability_exposure_score__added": {
      "description": "The maximum vulnerability exposure score of the workload in its current enforcement state across all vulnerable ports",
      "type": [
        "integer",
        "null"
      ]
    },
    "last_updated_at__added": {
      "description": "Indicates when the vulnerability data was last updated",
      "type": "string",
      "format": "date-time"
    },
    "vulnerable_port_exposure": {
      "description": {
        "__old": "The aggregated vulnerability port exposure score of the workload across all the vulnerable ports",
        "__new": "The aggregated vulnerability port exposure score of the workload in full enforcement mode across all the vulnerable ports"
      }
    },
    "vulnerability_exposure_score": {
      "description": {
        "__old": "The aggregated vulnerability exposure score of the workload across all the vulnerable ports.",
        "__new": "The aggregated vulnerability exposure score of the workload in full enforcement mode across all the vulnerable ports."
      }
    }
  }
}

common workload_detected_vulnerabilities

{
  "properties": {
    "last_updated_at__added": {
      "description": "Indicates when the vulnerability data was last updated",
      "type": "string",
      "format": "date-time"
    },
    "workload_detected_vulnerabilities": {
      "items": {
        "properties": {
          "full_enforcement_vulnerability_exposure__added": {
            "$ref": "workloads_detected_vulnerabilities_exposure.schema.json",
            "description": "vulnerability exposure details for full enforcement mode"
          },
          "selective_enforcement_vulnerability_exposure__added": {
            "$ref": "workloads_detected_vulnerabilities_exposure.schema.json",
            "description": "vulnerability exposure details for selective enforcement mode"
          },
          "visibility_enforcement_vulnerability_exposure__added": {
            "$ref": "workloads_detected_vulnerabilities_exposure.schema.json",
            "description": "vulnerability exposure details for visibility-only enforcement mode"
          },
          "current_enforcement_vulnerability_exposure__added": {
            "$ref": "workloads_detected_vulnerabilities_exposure.schema.json",
            "description": "vulnerability exposure details for the current enforcement mode"
          }
        }
      }
    }
  }
}