REST APIs for 23.5

{
  "properties": {	 
     "ven_type": { 
   "$ref": "../common/ven_type.schema.json"
}

Properties for GET

The new field vulnerability_computation_state is added to vulnerability_summary for all APIs that return the namespace. It defines three computation states:

The following APIs have been updated to return vulnerability_computation_state:

Example of Computation States:

syncing: Workload is in the syncing state (VES is calculable but hasn't been calculated yet):

"vulnerability_summary": {
	"num_vulnerabilities": 30,
	"max_vulnerability_score": 88,
	"vulnerability_score": 1248,
	"vulnerable_port_exposure": null,
	"vulnerable_port_wide_exposure": {
		"any": null,
		"ip_list": null
	},
	"vulnerability_exposure_score": null,
	"vulnerability_computation_state": "syncing"
},

The workloads GET collection API includes query parameters to filter returned workloads based on their Vulnerability Exposure Score.

These vulnerability filters are considered experimental and might be changed in the future.

Specify these parameters to get all the workloads that have a specific score.

Some examples of using the filters are:

GET api/v2/orgs/:xorg_id/workloads?representation=workload_labels_vulnerabilities&vulnerability_summary.vulnerability_exposure_score%5Blte%5D=50

GET api/v2/orgs/:xorg_id/workloads?representation=workload_labels_vulnerabilities&vulnerability_summary.vulnerability_exposure_score%5Bgte%5D=50&vulnerability_summary.vulnerability_exposure_score%5Blte%5D=999

This API allows you to update information about a workload. To make this call, you need the URI of the workload you want to update, which is returned in the form of an HREF path when you get either a single or a collection of workloads in an organization.

URI to Update an Individual Workload's Information

PUT [api_version][workload_href]

Example Payload

This example shows what the JSON payload looks like for changing the policy state (called mode in the API) of a workload from its current state to enforced.

{"agent":{"config":{"mode":"enforced","log_traffic":true}}}

Curl Command to Update a Workload

This example assumes that you want to update the state of a single workload in an organization. You can obtain an organization ID when you use the Users API to log in a user to Illumio.

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/workloads/043902c883d133fa -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"agent":{"config":{"mode":"enforced","log_traffic":true}}}' 

You can use this API to mark a workload VEN as suspended or unsuspended.

URI to Mark a Workload VEN as Suspended or Unsuspended

PUT [api_version][workload_href]

Example Payload

This example shows what the JSON payload looks like for marking a workload VEN as suspended, with the status property for the agent (the VEN) set to suspended.

To mark a workload VEN as unsuspended, use the same JSON body but replace suspend with unsuspend.

{
  "agent": {    
    "status": {
      "status": "suspended"
    }
  }
}

Curl Command to Mark Workload as Suspended

This example shows how to use curl to mark a workload VEN as suspended.

This example assumes you want to mark a single workload VEN as suspended. You can obtain an organization ID when you use the Users API to log in a user to Illumio.

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/workloads/043902c883d133 -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"agent":{"status":{"status":"suspended"}}}' 

The Unmanaged Workload API enables you to create a workload without installing the VEN on it. This API is commonly used if you are using Kerberos authentication between the VEN and the PCE.

URI to Create an Unmanaged Workload

POST [api_version][org_href]/workloads

Example Payload

For example, to create an unmanaged workload by providing a name, hostname, public IP address, and its Kerberos Service Principal Name, construct the JSON payload as follows:

{ 
     "name":"web_tier1", 
     "hostname":"web_workload1.example.com", 
     "public_ip":"10.10.10.10",     
     "service_principal_name":"my_company-device-auth/web_workload1.example.com", 
}

Curl Command to Create an Unmanaged Workload

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/4/workloads -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"name":"web_tier1", "hostname":"web_workload1.example.com","public_ip": "10.10.10.10","service_principal_name":"my_company-device-auth/web_workload1.example.com"}' 

If you have unpaired a workload, you can use this API to delete the workload's record from the PCE.

URI to Delete a Workload Record

DELETE [api_version][workload_href]

This API allows you to unpair workloads from the PCE by uninstalling the Illumio VEN from each workload. You can unpair up to 1,000 workloads at a time.

Pairing a workload installs the Illumio VEN on a workload. Unpairing a workload uninstalls the VEN from the workload so that the workload no longer reports any information to the PCE and can no longer receive any policy information.

When you unpair workloads with this API, you can set the state for the workloadʼs iptables (Linux) or WFP (Windows) configuration.

URI to Unpair a Workload

PUT [api_version][org_href]/workloads/unpair

Request Parameters

Example Payload for Unpairing Workloads

{
    "workloads": [
      {"href":"/orgs/7/workloads/XXXXXXXx-9611-44aa-ae06-fXXX8903db65"},
      {"href":"/orgs/7/workloads/xxxxxxxx-9611-xxxx-ae06-f7bXXX03db71"}
    ],
    "firewall_restore":"saved"
 }

Curl Command for Unpairing Workload

curl -i -X PUT https://pce.my-company.com/api/v2/orgs/3/workloads/unpair -H "Content-Type:application/json" -u $KEY:$TOKEN -d '{"workloads": [{"href": "/orgs/7/workloads/xxxxxxxx-9611-44aa-ae06-fXXX8903db65", "href": "/orgs/7/workloads/xxxxxxxx-9611-xxxx-ae06-f7bXXX03db71"}], "firewall_restore": "default"}'

Three new properties are now available to describe LOG_INFO level notification, LOG_WARNING level notification, and LOG_ERR level notification for workloads going offline.

When a VEN does not contact the PCE within a set time interval, it is marked as being offline. Previously, before that happened, a notification was created when the VEN was AWOL (missing) for 25% of the offline time.

These three new optional settings generate different levels of notifications at different intervals so the user can customize the timing and levels of notification.

They are described in the schema resource_canonical_representations: