Skip to main content

REST APIs for 24.2.20 and 24.2.10

Workload Operations

This Public Stable API allows you to perform workload operations, such as creating an unmanaged workload, updating workload information, unpairing a workload, and deleting a workload.

Workload Methods

Functionality

HTTP

URI

Get a collection of all workloads.

GET

[api_version][org_href]/workloads

Get a specified workload.

GET

api_version][org_href]/workloads/workload_id

Create an unmanaged workload.

POST

[api_version][org_href]/workloads

Update a workload or mark it as suspended.

PUT

[api_version]/workloads/workload_id

Vulnerability Computation State

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

  • not_applicable (N/A) indicates that the vulnerability exposure score cannot be calculated and happens in the following cases:

    • Unmanaged workloads

    • Idle workloads

    • Vulnerabilities that have no port associated with them.

  • syncing: For managed workloads, when the vulnerability exposure score hasn't been calculated yet, and the value is not available.

  • in_sync: For managed workloads, when the workload with the VES value is calculated and available.

The following APIs have been updated to return vulnerability_computation_state:

  • workloads(get collection) API

  • workloads/detailed_vulnerability

  • workloads (get instance)

  • workloads/:uuid/detected_vulnerabilities

  • aggregated_detected_vulnerabilities

Vulnerability Exposure Score (VES) Filters

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.

Note

To use these new query parameters, you must also include the query parameter representation=workload_labels_vulnerabilities; otherwise, the PCE won't perform any vulnerability calculations.

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
Update Workload Information

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}}}
Mark Workload as Suspended

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]
Create an Unmanaged Workload

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
Delete a Workload Record

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]
Workloads Going Offline

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:

Unpair Workloads

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

Important

The endpoint workloads/unpair is DEPRECATED. Use VEN Unpair instead.

Workload Operations Reference

Learn about parameters, properties, and examples of workload operations.

Workload Operations Parameters

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

agent.active_pce_fqdn

FQDN of the PCE

String

No

container_clusters

List of container cluster URIs, encoded as a JSON string

String

No

enforcement_mode

Enforcement mode of workload(s) to return.

String

No

external_data_set

The data source from which a resource originates

external_data _ reference

A unique identifier within the external data source

String

No

include_deleted

Include deleted workloads

Boolean

No

ip_address

IP address of workload(s) to return. Supports partial matches

String

No

labels

List of lists of label URIs, encoded as a JSON string.

From release 22.3.0, this API is not referencing labels.schema.json and it lists labels associated. with this workload. Required properties are: href, key, and value.

String

No

last_heartbeat_on[gte]

Greater than or equal to value for last heartbeat on timestamp

Integer

No

last_heartbeat_on[lte]

Less than or equal to value for last heartbeat on timestamp

Integer

No

log_traffic

Whether we want to log traffic events from this workload

Boolean

No

max_results

Maximum number of workloads to return.

Integer

No

mode

Management mode of workload(s) to return. DEPRECATED AND REPLACED (Use enforcement_mode)

String

No

name

Name of workload(s) to return. Supports partial matches

String

No

online

Return online/offline workloads using this filter

Boolean

No

os_id

Operating System of workload(s) to return. Supports partial matches

String

No

policy_health

Policy of health of workload(s) to return. Valid values: active, warning, error, suspended

String

No

security_policy_sync_state

Advanced search option for workload based on policy sync state

String

No

security_policy_update_mode

Advanced search option for workload based on security policy update mode

String

No

soft_deleted

DEPRECATED WITH NO REPLACEMENT:

Only soft-deleted workloads

Boolean

No

ven

URI of the VEN to filter by. From release 22.3.0,in addition to providing the VENs HREF, it is required to give its hostname, name, ven_type, and status. The VEN properties are now clearly displayed, without a need to use expanded representations.

The ven_type property is introduced through the reference to a common schema ven_type.schema.json:

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

String

No

visibility_level

Filter by visibility level

No

vulnerability_summary. vulnerability _exposure_score[gte]

Greater than or equal to value for vulnerability_exposure_score

Integer

No

vulnerability_summary. vulnerability _exposure_score[lte]

Less than or equal to value for vulnerability_exposure_score

Integer

No

Workload Operations Properties

Property

Description

Type

Required

deleted

This workload has been deleted

Boolean

Yes

name

Interface name

String

Yes

managed

Return managed or unmanaged workloads using this filter. True if the workload is managed, else false

Boolean

Yes

hostname

Hostname of workload(s) to return. Supports partial matches

String

Yes

service_principal_name

The Kerberos Service Principal Name (SPN)

String

Yes

public_ip

The public IP address of the workload.

String

Null

Yes

interfaces

ref": "workloads_interfaces_get.schema.json

service_provider

Name of the service provider that is hosting the workload.

String

Yes

data_center

The name of the data center where the workload is being hosted.

Yes

data_center_zone

The zone inside the data center hosting the workload.

String

Yes

os_id

Unique OS identifier given by Illumio to the workload.

String

Yes

os_detail

Additional descriptive information about the workload OS

String

Yes

online

Indicates whether the workload is online and can communicate with the PCE.

Boolean.

Yes

labels

Labels that are attached to the workload: href, key, and value

Array.

Yes

services

This field contains the following data:

  • uptime_seconds

  • created_at

  • open_service_ports: with the following data: protocol, address, port, process_name, user, package, win_service_name

Yes

agent

DEPRECATED AND REPLACED (USE 'ven' INSTEAD).

Information about the agent that manages this workload.

Yes

created_at

The time (rfc3339 timestamp) at which this workload was created

String

date/time

Yes

updated_at

The time (rfc3339 timestamp) at which this workload was last updated

String

date/time

Yes

vulnerabilities_summary

Reference to common/vulnerability_summary.schema.json

No

detected_vulnerabilities

Reference to common/workloads_detected_vulnerabilities.schema.json

No

ven

This section of the response returns the following data:

  • href

  • hostname

  • name

  • status

No

container_cluster

Reference to common/compact_container_cluster.schema.json

No

ike_authentication_ certificate

IKE authentication certificate for certificate-based Secure Connect and Machine Auth connections

No

risk_summary

Risk Summary for this workload. These properties have been added to the workload-get API to manage the features of the Ransomware Dashboard introduced in release 23.5.

For risk_summary object , the required object is ransomware. and it has three required properties:

  • workload_exposure_severity: This property is referencing /common/workload_exposure_ severity.schema.json

  • ransomware_protection_percent:

    description: "Ransomware protection percentage for this workload",

    type: number

  • last_updated_at:

    description: "The time at which the ransomware stats are last computed at",

    type: string

    format: date-time

Object

No

Properties for Workload Disconnection

Property

Description

Type

workload_disconnected_ timeout_ second

Disconnected timeout in seconds

Integer

workload_goodbye_timeout_seconds

Goodbye timeout in seconds

Integer

workload_disconnect_ notification_info

Threshold in seconds for LOG_INFO level notification of a workload going offline

Integer

workload_disconnect_ notification_warning

Threshold in seconds for LOG_WARNING level notification of a workload going offline

Integer

workload_disconnect_ notification_error

Threshold in seconds for LOG_ERR level notification of a workload going offline

Integer

Example of Computation States:

syncing: Workload is in 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"
},

Curl Command to Update a Workload

A workload state can be build, test, or enforced. This example shows how to use curl to update a workload policy state from its current state to enforced.

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}}}'

Example Payload for marking a workload as suspended

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 you how to use curl to mark a workload VEN as suspended.

This example assumes that 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"}}}'

Example payload for unmanaged workload

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

Parameters to unpair a workload

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

workloads

Defines the list of workloads you want to unpair. You must specify at least one workload to unpair by defining the workload HREF. You can define up to 1,000 workloads to unpair with this API.

Required property:

href:URI of the workload to unpair.

Array

Yes

ip_table_restore

Important

Use /vens/unpair and the parameter firewall_restore instead.

This property allows you to determine the state of the workload iptables (Linux) or WFP (Windows) configuration after the workload is unpaired.

Options include:

  • saved: Revert the iptables on the workload to the configuration before the VEN was installed. However, depending on how old the iptables or WFP configuration was on the workload, VEN removal could adversely impact security.

  • default: Apply the recommended policy, which is to uninstall the VEN and allow only port 22 SSH connections to the workload. Safest from a security viewpoint, but if this workload is running a production application, it could break because this workload will no longer allow any connections to it.

  • disable: Uninstall the VEN and leave all port connections on the workload open. This is the least safe from a security viewpoint. If iptables or WFP configuration or Illumio were the only security being used for this workload, the workload would be opened up to anyone and become vulnerable to attack.

String

Yes

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"}'
See also: