REST APIs for 24.2.20 and 24.2.10

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:

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 as 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 a workload's policy state (called mode in the API) from its current state to enforced.

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

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

URI to Create an Unmanaged Workload

POST [api_version][org_href]/workloads

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]

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 offline. 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 to varying intervals so the user can customize the timing and levels of notification.

They are described in the schema resource_canonical_representations:

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