Illumio Core What's New and Release Notes 23.2

Security administrators use this API to view how many workloads are ransomware protection ready and then assess the degree of protection in their whole system. This schema supplies the required information to run the Ransomware Dashboard:

Sample Response for reports/risk_summary_get

{
   "ransomware":{
	"num_total_workloads":98,
	"num_protected_workloads":22,
	"workload_protection_by_severity":{
	  "low":{
		"protected_workload_count":2,
		"unprotected_workload_count":8
	   },
	   "medium":{
		"protected_workload_count":3,
		"unprotected_workload_count":6
	   },
	  "high":{
		"protected_workload_count":2,
		"unprotected_workload_count":8
	   },
	   "critical":{
		"protected_workload_count":3,
		"unprotected_workload_count":6
	   }
			},
   "workload_protection_by_port_type":{
	"admin":{
	   "protected_workload_count":2,
	   "unprotected_workload_count":8
	},
	"legacy":{
	   "protected_workload_count":3,
	   "unprotected_workload_count":6
	}
   },
   "ransomware_protection_coverage_percent":56,
   "last_updated_at":"2023-01-21 23:32:42.679673"
   }
}

This schema is referenced from reports_risk_summary_get.schema.json to supply the number of protected and unprotected ports for a specified risk level:

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "required": [
	"num_protected_ports",
	"num_unprotected_ports"
  ],
   "properties": {
	"num_protected_ports": {
	   "description": "Number of protected ports for this risk 
            level, across all protection ready workloads",
	   "type": "integer"
	   },
	"num_unprotected_ports": {
	   "description": "Number of unprotected ports for this risk 
                level, across all protection ready workloads",
	   "type": "integer"
	}
   }
}

This schema supplies the granularity of the time series data.

The API reports_time_series_statistics_post includes the property num_managed_workloads, which is requested by the payload. The resolution might be day, week, month, and quarter, which defines what the UI will show.

The default value is "day".

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "array",
   items": {
	"type": "object",
	"required": [
	   "property"
	],
	"properties": {
	   "property": {
		"description": "The property for which time series data 
                   is requested.",
		"type": "string",
		"enum": [
		   "num_managed_workloads"
		]
	},
	"resolution": {
		"type": "string",
		"description": "The granularity for the time series data. 
                   E.g. day, week, month, quarter",
		"enum": [
		   "day",
		   "week",
		   "month",
		   "quarter"
		],
	   "default": "day"
	},
	"max_results": {
	   "type": "integer",
	   "default": 5
	}
    }
  }
}

This API specifies the time series data about the protected workloads, such as the start and end date of the protection period.

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "array",
   "items": {
	"type": "object",
	"required": [
	   "property",
	   "time_series"
	],
	"properties": {
	   "property": {
		"description": "The property for which data has been 
                  requested.",
		   "type": "string"
		},
	   "time_series": {
		"type": "array",
		"items": {
		"type": "object",
		"required": [
		   "start_date",
		   "end_date"
	   ],
		"properties": {
		   "start_date": {
		      "description": "The start date of the time period.",
			"type": "string",
			"format": "date-time"
		   },
		  "end_date": {
		      "description": "The end date of the time period.",
		      "type": "string",
		      "format": "date-time"
		  },
		  "count": {
		      "description": "The integer count on the end date 
                       of this period.",
		      "type": "integer"
		  },
		  "unit": {
		      "description": "The unit of the value returned.",
		      "type": "string"
		}
	   }
      }
}

Sample Requst Body for reports_time_series_statistics_post_response

[
    {
	"property": "num_managed_workloads",
	"resolution": "week",
	"max_results": 4
    }
]

Response for reports_time_series_statistics_post_response

A week starts Monday and ends Sunday and the VEN count is from Sunday of that week. The last week could be a partial week hence the count will be of the last day.

The last month could be a partial month, and hence the count will be from the last day.

This Public Stable API was changed to support the Ransomware Dashboard in the following way:

{
 "properties": {
   "risk_summary": {
	"description": "Risk Summary for this workload",
	"type": "object",
	"required": [
	   "ransomware"
	],
	"properties": {
	   "ransomware": {
		"type": [
		   "object",
		   "null"
		],
		"required": [
		   "workload_exposure_severity",
		   "ransomware_protection_percent",
		   "last_updated_at"
		],
		"properties": {
		   "workload_exposure_severity": {
			"description": "Exposure severity of the workload",
			"type": "string"
			},
		   "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"
			}
		}
	}
}

This API, which supplies the risk details, you can see in action on the Workloads page, tab Ransomware Protection.

In addition to the organization admin, the users who have access to the workload can view the ransomware protection details for that workload, or how many risky ports are protected and how many risky ports are not protected.

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
	"risk_details": {
	"type": "object",
	"required": [
	   "ransomware"
	],
	"ransomware": {
	   "type": [
		"object",
		"null"
	   ],
	   "properties": {
	      "details": {
		"type": "array",
		"items": {
		   "$ref": "workload_ransomware_services.schema.json"
		}
	   },
	   "last_updated_at": {
		"description": "The time at which the protection stats 
                     were last computed at",
		"type": "string",
		"format": "date-time"
	   }
      }
}

Sample Response for workloads_risk_details_get

{
   "risk_details":{
	"ransomware":{
	   "services":[
	      {
		"href":"/api/v2/orgs/8/workloads/23131cf5-1d70-42de-9242-39055338d0ef",
		"name":"SSH",
		"port":22,
		"protocol":17,
		"severity":"low",
		"port_status":"listening",
		"protection_state":"unprotected",
		"active_policy":"allowed",
		"draft_policy":"blocked",
		"recommendation":"add_boundary"
	   },
	   {
		"href":"/api/v2/orgs/8/workloads/23131cf5-1d70-42de-9242-39055338d0ef",
		"name":"SSH",
		"port":22,
		"protocol":6,
		"severity":"high",
		"port_status":"listening",
		"protection_state":"protected",
		"active_policy":"allowed",
		"draft_policy":"blocked",
		"recommendation":"has_draft_policy_needs_provisioning"
	   }
	],
	"last_updated_at":"2023-01-21 23:32:42.679673"
	}
   }
}

The full response looks as follows:

[
   {
	"property":"num_managed_workloads",
	"time_series":[
	   {
		"start_date":"2022-10-31",
		"end_date":"2022-11-2",
		"count":120
	   },
	   {
		"start_date":"2022-10-24",
		"end_date":"2022-10-30",
		"count":115
	   },
	   {
		"start_date":"2022-10-17",
		"end_date":"2022-10-23",
		"count":110
	   },
	   {
		"start_date":"2022-10-10",
		"end_date":"2022-10-16",
		"count":100
	   }
	]
   }
]

This schema is referenced from workloads_risk_details_get to supply the required service data:

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "required": [
	 "href",
	  "port",
	  "protocol",
	  "severity",
	  "port_status",
	  "protection_state",
	  "active_policy",
	  "draft_policy"
	],
   "properties": {
      "href": {
	   "description": "Reference of the service",
	   "type": "string"
	},
      "name": {
	   "description": "Name of the service",
	   "type": "string"
	},
	"port": {
	   "description": "Port Number",
	   "type": "integer",
	   "minimum": 0,
	   "maximum": 65535
	},
	"proto": {
	   "description": "Protocol Number",
	   "type": "integer"
	},
	"severity": {
	   "description": "Severity of this service",
	   "type": "string",
	   "enum": [
	      "low",
	      "medium",
	      "high",
	      "critical"
	   ]
	},
       "category": {
	   "description": "Category of this service",
	   "type": "string",
	   "enum": [
	      "admin",
	      "legacy"
	   ]
      },
	"port_status": {
	   "description": "Status of the port on the workload",
	   "type": "string",
	   "enum": 	
             "listening",
	      "inactive"
	      ]
	   },
	"protection_state": {
	   "description": "Protection state of this service",
	   "type": "string",
	   "enum": [
	       "unprotected",
	       "protected_open",
	       "protected_closed"
	      ]
	},
	"active_policy": {
	      "description": "Active Policy that applies to this port",
	      "type": "string",
	      "enum": [
		  "allowed",
		  "allowed_across_boundary",
		  "blocked_by_boundary",
		 "blocked_no_rule"
	      ]
	   },
	  "draft_policy": {
	      "description": "Draft Policy that applies to this port",
	      "type": "string", 
             "enum": [
		   "allowed",
		   "allowed_across_boundary",
		   "blocked_by_boundary",
		   "blocked_no_rule"
		]
	   },
	   "recommendation": {
		"description": "Recommendation for this port based on enforcement 
                     state, allow and deny rules and active/draft rule",
		"type": "string",
		"enum": [
		   "add_boundary",
		   "has_draft_policy_needs_provisioning"
		]
	    }
      }
}

This Public Stable API was changed to include a new property num_assets_requiring_ransomware_protection.

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "properties": {
	"href": {
	   "description": "Org Setting URI",
	   "type": "string",
	   "format": "uri"
	},
	"num_assets_requiring_ransomware_protection": {
	   "description": "number of assets that need ransomware 
                 protection for this org",
	   "type": [
		 "integer",
		  "null"
	   ]
	},
		======================================

This Public Stable API was changed to include a new property num_assets_requiring_ransomware_protection, which provides a number of assets that need ransomware protection in a specific organization. Number of assets is between one and 9999999 .

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "additionalProperties": false,
   "properties": {
	  "num_assets_requiring_ransomware_protection": {
		"description": "number of assets that need 
                    ransomware protection for this org",
		"type": "integer",
		"minimum": 1,
		"maximum": 9999999
		===================================

These APIs have been changed as follows:

The new object risk_details was added and supplies the same data as the previously deleted three properties: ransomware_category, ransomware_severity, and ransomware_os_platforms.

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"additionalProperties": false,
	"required": [
	   "name"
	   ],
	"properties": {
	   "name": {
		"description": "Name (does not need to be unique)",
		"type": "string"
		},
	   "description": {
		"description": "Description",
		"type": "string"
		},
	   "risk_details": {
		"type": "object",
		"properties": {
		   "ransomware": {
			"type": "object",
			"properties": {
			   "category": {
				"description": "Categorization based on Admin 
                                   or Legacy port used in the service",
				"type": "string",
				"enum": [
				   "admin",
				   "legacy"
			      ]
			},
			"severity": {
				"description": "Severity of this service",
				"type": "string",
				"enum": [
				   "low",
				   "medium",
				   "high",
				   "critical"
				   ]
				},
			"os_platforms": {
				"description": "Operating system for this 
                                   ransomware service",
				"type": "array",
				"minItems": 1,
				"items": {
				   "type": "string",
				   "enum": [
					"windows",
					"linux"
				      ]
				  }
			     }
			}
		}
	}
},
		==============================================

These Security Policy APIs are explained in the topic Services

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"description": "Supported ven types in this release",
		"type": "array",
		"items": {
		"type": "string",
		"enum": ["server", "endpoint"]
	}
}

The schema release_ven_types is referenced from the APIs software_ven_releases_get and software_ven_releases_images_get, which have been updated and changed for this release:

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

The API software_ven_releases_get shows the VEN releases available to the org, one per VEN version, along with some metadata such as whether it is the default version, whether that release supports servers and/or endpoints, and so on. The list of images is longer than the list of releases, and multiple images belong to the same release version.

One new property was added:

{
   "properties": {
	"default_release_ven_types": {
	   "type": "array",
	   "items": {
		"type": "string",
		"description": "The type of the release marked as default"
	   }
	}
   }
}

{
	"items": {
	"properties": {
	"ven_types": {
		"$ref": "../common/release_ven_types.schema.json"
		}
	}
    }
}

The API software_ven_releases_images_get shows the full list of VEN images. There is one image for each supported Linux distribution (such as RHEL, Ubuntu), plus images for Windows and macOS.

This API has several changes:

These two new properties were added:

{
   "properties": {
	"upgrade_expires_at": {
	   "description": "The time (rfc3339 timestamp) at which the 
                PCE stops attempting VEN upgrade",
	   "type": [
		"string",
		"null"
	   ],
	   "format": "date-time"
	   },
	"upgrade_target_version": {
	   "description": "The software release to upgrade to.",
	   "type": [
		"string",
		"null"
	   ]
	 }
    }
}

One new property was added:

{
	"properties": {
	"upgrade_timeout_seconds": {
	   "description": "Number of seconds during which the PCE 
                   tries to trigger the agent upgrade.",
	   "type": "integer",
	   "minimum": 900,
	   "maximum": 15552000
	}
   }
}

This is a new API that supplies the VEN bundle release, including the VEN UTI associated with the release and the VEN type property (type of the release marked as default).

{
   "$schema": "http://json-schema.org/draft-04/schema#",
   "type": "object",
   "required": [ 
	  "href",
	 "ven_type" ],
   "description": "The ven bundle release with the ven type property",
   "additionalProperties": false,
   "properties": {
	"href": {
		"description": "URI associated to this release",
		"type": "string"
	},
	"ven_type": {
	   "type": "string",
	   "description": "The type of the release marked as default",
	   "enum": [
               "server", 
               "endpoint"
	   ]
      }
   }
}

Two new properties have been added to all of them:

For settings_traffic_collector_put and settings_traffic_collector_post, these properties contain additional definitions for their type.

Fot these API, a new property can be listed or created: ven_type.

For this API, the following changes have been made:

For this API, a new property name was added to describe the name of the network.

For this API, the property type null was added.