Illumio Core REST API in 22.5.0

The Illumio Core REST API v2 has changed in 22.5.0 in the following ways.

New Public Stable APIs

Vulnerability APIs

vulnerability_summary.schema.json

The new vulnerability summary schema looks as follows:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"description": "Vulnerabilities summary associated with the workload",
"additionalProperties": false,
"required": ["num_vulnerabilities", "max_vulnerability_score"],
"properties": {
	"num_vulnerabilities": {
		"description": "Number of associated vulnerabilities",
		"type": "integer"
		},
	"vulnerability_score": {
		"description": "The aggregated vulnerability score of 
                the workload across all the vulnerable ports.",
		"type": "integer"
		},
	"max_vulnerability_score": {
		"description": "The maximum of all the vulnerability 
                scores with the detected_vulnerabilities on the workload.",
		"type": "integer"
		},
	"vulnerable_port_exposure" : {
		"description" : "The aggregated vulnerability port exposure 
                score of the workload across all the vulnerable ports",
		"type" : ["integer", "null"]
		},
	"vulnerable_port_wide_exposure" : {
		"additionalProperties" : false,
		"properties" : {
		"any" : {
			"description" : "The boolean value representing if at least 
                        one port is exposed to internet (any rule) on the workload",
			"type" : ["boolean", "null"]
		},
		"ip_list" : {
			"description" : "The boolean value representing if at least 
                        one port is exposed to ip_list(s) on the workload",
			"type" : ["boolean", "null"]
		}
	    }
       },
	"vulnerability_exposure_score": {
		"description": "The aggregated vulnerability exposure score of 
                the workload across all the vulnerable ports.",
		"type": ["integer", "null"]
		},
	"vulnerability_computation_state": {
		"description": "Indicates the computation state for the 
                vulnerability exposure score for the workload.",
		"type": "string",
		"enum": ["not_applicable", "syncing", "in_sync"]
		}
	}
}

where

vulnerability_computation_state

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

not_applicable: N/A (not applicable) ndicates 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)
workloads/detailed_vulnerability
workloads (get instance)
workloads/:uuid/detected_vulnerabilities
aggregated_detected_vulnerabilities

Examples 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"
},

not_applicable:Unmanaged workload with applied vulnerabilities

"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": "not_applicable"
},

in_sync:Managed (non-idle) workload with applied vulnerabilities and computed vulnerability exposure score

"vulnerability_summary": {
	"num_vulnerabilities": 30,
	"max_vulnerability_score": 88,
	"vulnerability_score": 768,
	"vulnerable_port_exposure": 6,
	"vulnerable_port_wide_exposure": {
		"any": true,
		"ip_list": true
	},
	"vulnerability_exposure_score": 52,
	"vulnerability_computation_state": "in_sync"
},

common/aggregated_detected_vulnerability.schema.json

The new schema aggregated_detected_vulnerability applies to multiple workloads. The rules for resolving the aggregated computation state are as follows:

If any of the workloads referencing the label(s) in the request is in the state syncing, the aggregated state is syncing.
For the aggregated value to be in the N/A state ALL workloads must be in the state N/A.
For all the other cases, the aggregated state is in_sync.
For example:
- all workloads are managed and are not idle (eliminating N/A)
- all workloads have at least one valid vulnerable port (the port is not NULL and the prototype is not NULL for vulnerability)

{
"$schema":"http://json-schema.org/draft-04/schema#",
"type": "object",
"required": [ "aggregated_detected_vulnerabilities", 
            "aggregated_detected_vulnerability_summary"],
"properties": {
	"aggregated_detected_vulnerability_summary": {
		"$ref": "vulnerability_summary.schema.json"
	},
	"aggregated_detected_vulnerabilities": {
	    "type":"array",
	     "items":{
	     "type" : "object",
	     "required" : [
		"vulnerability_exposure_score",
		"num_workloads",
		vulnerability"
	     ],
		"additionalProperties" : false,
		"properties" : {
		   "port" : {
		      "description" : "The port which is associated with 
                                     the vulnerability",
		       "type" : "integer"
		  },
		   "proto" : {
			 "description" : "The protocol which is associated 
                                          with the vulnerability",
			 "type" : "integer"
		    },
		    "vulnerable_port_exposure" : {
			  "description" : "The aggregated exposure of the port 
                                          across all the requested workloads 
                                          based on the current policy",
			  "type" : ["integer", "null"]
		    },
		    "vulnerable_port_wide_exposure" : {
		    "additionalProperties" : false,
		    "properties" : {
			   "any" : {
			   "description" : "The boolean value representing if the 
                           port is exposed to internet (any rule) on at least one of 
                           the workloads in the requested group",
			   "type" : ["boolean", "null"]
		    },
		    "ip_list" : {
			   "description" : "The boolean value representing if the port 
                           is exposed to ip_list(s) on at least one of the workloads 
                           in the requested group",
			   "type" : ["boolean", "null"]
		        }
	          }
                 },
		  "vulnerability_exposure_score" : {
			   "description" : "The aggregated vulnerability exposure score 
                           of the port across all the requested workloads based on the 
                           current policy",
			   "type" : ["integer", "null"]
		   },
		   "num_workloads" : {
			   "description" : "The number of workloads within the requested 
                           group where the vulnerability exists on the specified port 
                           and protocol",
			   "type" : "integer"
		   },
		   "vulnerability" : {
	           "type": "object",
		   "additionalProperties": false,
	               "required": ["href", "score", "name"],
			   "properties": {
			   "href": {
			   "description": "The URI of the vulnerability class 
                            to which this vulnerability belongs to",
			   "type": "string"
		   },
		   "score": {
			   "description": "The normalized score of the vulnerability 
                            within the range of 0 to 100",
			   "type": "integer",
			      "minimum": 0,
			      "maximum": 100
			   },
		   "name": {
			   "description": "The title/name of the vulnerability",
			   "type": "string"
		   },
		   "cve_ids": {
			   "description": "The cve_ids for the vulnerability",
			   "type": "array",
			   "items": {
			   "type": "string"
		   }
	     }
	 }
   }
}

common/workloads_detected_vulnerabilities.schema.json

This schema specifies workload detected vulnerability, references the vulnerability_summary.schema.json for the summary information, and specifies the collection of the workload_detected_vulnerabilities. It is referenced by the following schema files:

workloads_detected_vulnerabilities_get.schema.json
v1/workloads_get.schema.json
v2/workloads_get.schema.json

{
"$schema":"http://json-schema.org/draft-04/schema#",
"type": "object",
"required": ["detected_vulnerability_summary", "workload_detected_vulnerabilities"],
"properties": {
	"detected_vulnerability_summary": {
		"$ref": "vulnerability_summary.schema.json"
	},
	"workload_detected_vulnerabilities": {
		"type":"array",
		"description": "Collection of the detected vulnerabilities 
                 associated with the workload",
		"items":{
			"type" : "object",
			"required" : [
			"ip_address",
			"vulnerability"
			],
		"additionalProperties" : false,
			"properties" : {
			"ip_address" : {
			   "description" : "The ip address of the host where 
                            the vulnerability is found",
			   "type" : "string"
			},
		"port" : {
			   "description" : "The port which is associated 
                            with the vulnerability",
			   "type" : "integer"
			},
		"proto" : {
			   "description" : "The protocol which is associated 
                            with the vulnerability",
			   "type" : "integer"
			},
		"port_exposure" : {
			   "description" : "The exposure of the port based 
                            on the current policy",
			   "type" : ["integer", "null"]
			},
		 "port_vulnerability_exposure_score" : {
			   "description" : "The vulnerability exposure score 
				calculated for the port, based on the port				
				 exposure and vulnerability",
			   "type" : ["integer", "null"]
			},
		"port_wide_exposure" : {
			   "additionalProperties" : false,
			   "properties" : {
			   "any" : {
			   "description" : "The boolean value representing 
				if the port is exposed to internet (any rule).",
			   "type" : ["boolean", "null"]
			},
		"ip_list" : {
			   "description" : "The boolean value representing if the 
				port is exposed to ip_list(s)",
			   "type" : ["boolean", "null"]
		      }
		    }
		},
		"workload" : {
	 	  "type": "object",
		  "additionalProperties": false,
		  "required": ["href"],
		  "properties": {
			"href": {
			"description": "The URI of the workload to which this 
				vulnerability belongs to",
			"type": "string"
		       }
	           }
	         },
	         "vulnerability" : {
		  "type": "object",
		  "additionalProperties": false,
		  "required": ["href"],
		  "properties": {
			"href": {
			"description": "The URI of the vulnerability class to
			 which this vulnerability belongs to",
			"type": "string"
			},
	         "score": {
		  "description": "The normalized score of the vulnerability 
			within the range of 0 to 100",
		  "type": "integer",
			   "minimum": 0,
			   "maximum": 100
		         },
			"name": {
			    "description": "The title/name of the vulnerability",
			    "type": "string"
			  }
		     }
	          },
	           "vulnerability_report" : {
		  "type": "object",
		  "additionalProperties": false,
		  "required": ["href"],
		  "properties": {
     
	          "href": {
		     "description": "The URI of the report to which this 
			vulnerability belongs to",
		     "type": "string"
		}
	  }  
     }
}

Other Common Schemas

These are the other new schemas in the common directory:

common/sec_policy_update_type.schema.json

common/label_optional_key_value.schema.json

common/nfc_dvs_service_checks.schema.json

```
common/nullable_href_object.schema.json
```

They are referenced by other schemas and have been added to this directory to eliminate duplication in the schema definitions.

New Public Experimental APIs

Security Policy

sec_policy_impact_post.schema.json

This API contains the name of the method on existing resources, which is impact. It is used to see the policy impact before provisioning.

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"properties": {
		"change_subset": {
		"$ref": "sec_policy_change_subset.schema.json"
		}
	}
}

This new schema is referencing sec_policy_change_subset.schema.json, which contains the property change_subset:

If change_subset is provided, the impact will be calculated only on change_subset.
If change_subset is missing, the impact will be calculated on all of the pending items.

sec_policy_impact_post_response.schema.json

The new API endpoint POST /api/v2/orgs/1/sec_policy/impact requires a schema to define it.

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"items": {
	"type": "object",
	"properties": {
	"dependency": {
		"type": "object",
		"properties": {
		"label_groups": {
		"$ref": "../common/href_object.schema.json"
		},
	"services": {
		"$ref": "../common/href_object.schema.json"
		},
	"rule_sets": {
		"$ref": "../common/href_object.schema.json"
		},
	"ip_lists": {
		"$ref": "../common/href_object.schema.json"
		},
	"virtual_services": {
		"$ref": "../common/href_object.schema.json"
		},
	"firewall_settings": {
		"$ref": "../common/href_object.schema.json"
		},
	"secure_connect_gateways": {
		"$ref": "../common/href_object.schema.json"
		},
	"virtual_servers": {
		"$ref": "../common/href_object.schema.json"
		},
	"enforcement_boundaries": {
		"$ref": "../common/href_object.schema.json"
		}
	}
	},
	"required_by": {
		"type": "object",
		"properties": {
			"label_groups": {
			"type": "array",
			"items": {
			"$ref": "../common/href_object.schema.json"
		}
	},
	"services": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"
		}
	},
	"rule_sets": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"
		}
	},
	"ip_lists": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"
		}
	},
	"virtual_services": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"
		}
	},
	"firewall_settings": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"
		}
	},
	"secure_connect_gateways": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"
		}
	},
	"virtual_servers": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"
		}
	},
	"enforcement_boundaries": {
		"type": "array",
		"items": {
		"$ref": "../common/href_object.schema.json"
		}
	  }
    }
}

Each of the allowed properties such as ip_lists, label_groups, and services can be included in the request body of the POST API endpoint call but the new schema defines the format and values of this API request for the example in the request body.

The response schema of that endpoint is sec_policy_impact_post_response.schema.json and if defines what the endpoint returns, such as the count of affected workloads, affected sets, and so on.

The response schema looks as follows:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"required": ["num_sets", "num_managed_workloads", "num_container_workloads",
		 "num_unmanaged_workloads"],
	"properties": {
	"num_sets": {
		"description": "number of affected sets",
		"type": "integer"
		},
	"num_virtual_servers": {
		"description": "number of affected virtual servers",
		"type": "integer"
		},
	"num_managed_workloads": {
		"description": "number of affected workloads of type Workload",
		"type": "integer"
		},
	"num_container_workloads": {
		"description": "number of affected workloads of type ContainerWorkload",
		"type": "integer"
		},
	"num_unmanaged_workloads": {
		"description": "number of affected unmanaged workloads",
		"type": "integer"
		},
	"all_workloads_optimization": {
		"description": "flag to indicate if all-workloads-optimization 
			has been used",
		"type": "boolean"
		}
	}
}

RBAC Permissions

rbac_permission_types.schema.json

This common schema rbac_permission_types.schema.json is referenced from other APIs to indicate the RBAC permission that is used: write or provision.

{  
	"$schema":"http://json-schema.org/draft-04/schema#",
	"type": "string",
		"description": "RBAC Permission types",
		"enum": ["write", "provision"]
	}

In the case of Illumination Plus and with the new property caps, the type provision is not used to avoid additional delays when checking the permissions of each flow. Therefore, only permission write is used and further verification is handled on the UI side.

Example

GET /api/v2/orgs/:xorg_id/traffic_flows/async_queries/:uuid/download

{
"dst": {
	"ip": "10.244.0.1",
	"workload": {
		"href": "/orgs/1/workloads/35d8efea-f230-4027-a8ee-5f20626c4d21",
		"name": "wl3",
		"labels": [
		{
			"key": "env",
			"href": "/orgs/1/labels/7",
			"value": "Production"
		},
		{
			"key": "loc",
			"href": "/orgs/1/labels/11",
			"value": "Amazon"
		},
		{
			"key": "role",
			"href": "/orgs/1/labels/3",
			"value": "API"
		},
		{
			"key": "B-label",
			"href": "/orgs/1/labels/15",
			"value": "b_label_2"
		}
	],
	"managed": false,
		"os_type": "linux",
		"endpoint": false,
		"hostname": "",
		"enforcement_mode": "visibility_only"
		}
	},
"src": {
	"ip": "10.0.2.15",
	"workload": {
		"href": "/orgs/1/workloads/fc3801b8-05ec-4954-a957-7f5673123389",
		"name": "wl2",
		"labels": [
		{
			"key": "env",
			"href": "/orgs/1/labels/7",
			"value": "Production"
		},
		{
			"key": "loc",
			"href": "/orgs/1/labels/11",
			"value": "Amazon"
		},
		{
			"key": "role",
			"href": "/orgs/1/labels/3",
			"value": "API"
		}
		],
	"managed": false,
		"os_type": "linux",
		"endpoint": false,
		"hostname": "",
		"enforcement_mode": "visibility_only"
		}
	},
	"caps": [],
		"state": "snapshot",
		"dst_bi": 0,
		"dst_bo": 0,
		"seq_id": 2,
		"network": {
			"href": "/orgs/1/networks/fbeeb98d-4ed6-428d-9f71-69f542bfd8fd",
			"name": "Corporate"
		},
		"service": {
			"port": 3306,
			"proto": 6
		},
		"flow_direction": "outbound",
		"num_connections": 1,
		"policy_decision": "unknown",
		"timestamp_range": {
		"last_detected": "2022-09-01T20:35:22Z",
		"first_detected": "2022-09-01T20:35:22Z"
		}
	}

Report Schedules APIs

report_schedules_post_response.schema.json

This new schema is referencing report_schedules_get, which is used to return the user's choice to send by mail.

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"$ref": "report_schedules_get.schema.json"
}

Deleted Public Stable APIs

detected_vulnerability_get.schema.json

workloads_detected_vulnerabilities_get.schema.json

For information where the functionality fro these deleted APIs was transferred, see common/workloads_detected_vulnerabilities.schema.json.

Changed Public Stable APIs

Workloads

workloads_get

In this schema:

The whole section on vulnerabilities_summary was replaced with a reference to the new schema common/vulnerability_summary.schema.json.

The reference to workloads_detected_vulnerabilities_get.schema.json was replaced with a reference to common/workloads_detected_vulnerabilities.schema.json, or the same schema that was moved to the common directory.

Settings Traffic Collector

For the settings_traffic_collectorAPIs:

settings_traffic_collector_get
settings_traffic_collector_post
settings_traffic_collector_put

there are two IP addresses that are defined for search:

The new single-source IP address (src_ip), which was added to all three APIs
The updated single destination IP address (dst_ip), which is now renamed from "single IP address or CIDR" to "single destination IP address or CIDR".

Oracle flows are currently filtered via a runtime src_ip/dst_ip (CIDR) setting and this feature is not available in SaaS. Runtime changes also require a PCE restart, while API settings do not.

The collector filters now support src_ip (CIDR) so that various filters can be created per organization without restarting the PCE.

"properties": {
	"target": {
	"properties": {
		"src_ip": {
			"type": "string",
			"description": "single source ip address or CIDR"
		},
		"dst_ip": {
			"description": {
			"single destination ip address or CIDR"
		}
	}
};

The collector filters now support src_ip (CIDR) so that various filters can be created per organization without restarting the PCE.

Example POST Curl command:

curl -i -u api_10415cd5bcc0e14cc:'2ac31cbee8cd3e8fa7ca79d32d39a0249636624ada675965dd2ec239e3ea8af0' --request POST --data '{"action":"drop","transmission":"unicast","target":{"proto":6,"src_ip":"10.1.2.3"}}' https://2x2testvc360.ilabs.io:8443/api/v2/orgs/2/settings/traffic_collector --header "Content-Type: application/json"

Virtual Services

sec_policy_virtual_services_get

The Properties section was updated with new references to the common schemas:

for the property created_by, the reference to common/href_object.schema.json is replaced with a reference to common/nullable_href_object.schema.json.
for the property updated_by, the reference to common/href_object.schema.json is replaced with a reference to common/nullable_href_object.schema.json.
for the property deleted_by, a new reference was added: common/nullable_href_object.schema.json.
for the property update_type, a new reference was added: common/sec_policy_update_type.schema.json.
for labels, a reference to common/labels.schema.json is replaced with a reference to common/label_optional_key_value.schema.json.

virtual_service_service_ports

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"description": "Service ports",
	-----------------
	"proto": {

		"$ref": "../common/service_ports_protocol_numeric.schema.json",
		"type": "integer",
		"enum": [
		6,
		17
		]
	    }
	}
}

For this schema, a reference to common/service_ports_protocol_numeric.schema.json was deleted.

Changed Public Experimental APIs

Virtual Servers and Virtual Services

discovered_virtual_servers_get

Two properties have been deleted:

snat_type: SNAT source IP type

snat_pool_ips: NAT source IPs of virtual server in ipv4 format

For the property service_checks, the reference to common/service_ports_protocol_numeric.schema.json was removed
For the property virtual_server, the reference to common/sec_policy_update_type.schema.jsonwas added.

sec_policy_virtual_servers_get

For this API:

For the property labels, the reference to labels.schema.json was replaced with a reference to common/label_optional_key_value.schema.json.
For the property providers, the reference to common/href_object.schema.json was replaced with a reference to common/label_optional_key_value.schema.json.
Properties mode, discovered_virtual_server, and deleted_at the additional type NULL.
For the property deleted_by, the reference to common/href_object.schema.json was replaced by the reference to common/nullable_href_object.schema.json.

Settings

For this API, both for the GET and PUT methods a new property was added:

ven_maintenance_token: This token identifies if the tampering protection for the VEN and endpoints is enabled. The default is not enabled.

settings_get

settings_put

{
	"properties": {
	"ven_maintenance_token_required": {
		"description": "Identifies if the tampering protection for 
			the VEN and endpoints is enabled or not.",
		"type": "boolean",
		"default": false
		}
	}
}

Traffic Flows

traffic_flows_async_queries_download_get

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"description": "The list of traffic flows matching the query",
	"type": "array",
	"items": {
		"type": "object",
		"required": [
			"src",
			"dst",
			"service",
			"num_connections",
			"policy_decision",
			"flow_direction",
			"timestamp_range",
			"caps"
		],
		"properties": {
		------------------------------------
	},
	"caps": {
		"description": "Array of permissions for the 
			flow for the current user",
		"type": "array",
		"items": {
		"$ref": "rbac_permission_types.schema.json"
	}
    }
}

The new required property caps was added, which represents an array of permissions for the current user's flow.

The caps info is added to support UI for the Illumination Plus feature. It shows whether a user has read and/or write access to the individual flow.

traffic_flows_traffic_analysis_queries_post

traffic_flows_traffic_analysis_queries_post_response

These two synchronous traffic query APIs have been deprecated and replaced with an async version.

Rather than removing the API entirely in release 22.5.0, they return a 410 error.

Other Changed Experimental APIs

slb_device_config.schema.json

},
	"credential": {
	"description": "credential",
	"type": [
		"string",
		"null"
	]
},

This schema provides management configuration information for SLB devices and the credential property was changed so that it can also be NULL.

optional_features_put

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"items": {
	"oneOf": [
	{
		"type": "object",
		"additionalProperties": false,
		"required": [
			"name",
			"enabled"
		],
		"properties": {
			"name": {
			"description": "Name of the feature",
			"type": "string",
			"enum": [
			"ip_forwarding_firewall_setting",
			"ui_analytics",
			"illumination_classic"
		]
	},

The property illumination_classic was added to PUT /api/v2/orgs/:xorg_id/optional_features, which is used to manage user analytics.

To set or clear the optional feature, use

{ 
name: "illumination_classic", enabled: false|true 
}

Illumio Core What's New and Release Notes 22.5