Illumio Core REST API in 23.5.10
The Illumio Core REST API v2 has changed in 23.5.10 in the following ways.
The most important API changes for release 23.5.10 are connected to the following:
Rule Hit Count
The Rule Hit Count feature is configured so that only certain VENs can compute the rule hit counts and send the rule ID info over to the PCE.
This feature is disabled by default on all the VENs and on the PCE.
Enabling Rule Hit Count
To use the Rule Hit Count feature, you first need to enable it on the PCE and the relevant VENs.
Enable Rule Hit Count on a VEN
Use the following API to enable the feature on a VEN on all scopes:
PUT api/v2/orgs/:xorg_id/sec_policy/draft/firewall_settings
The existing schema was changed so that the property rule_hit_count_enabled_scopes was added.
{
"properties": {
"rule_hit_count_enabled_scopes": {
"description": "Workloads that match the scope will have rule hit \
count enabled",
"$ref": "../common/rule_set_scopes_put.schema.json"
}
}
}This is a sample API that can be used to enable the feature on specific scopes. In this example, it enables the features on all VENs with labels 7 and 12.
{
"rule_hit_count_enabled_scopes": [
[
{
"label": {
"href": "/orgs/1/labels/7"
}
},
{
"label": {
"href": "/orgs/1/labels/12"
}
}
]
]
}Commit or provision these DRAFT changes.
POST /api/v2/orgs/:xorg_id/sec_policy
{
"update_description":"Enable rule hit count",
"change_subset": {
"firewall_settings":
[
{
"href":"/orgs/1/sec_policy/draft/firewall_settings"
}
]
}
}Disable the feature Rule Hit Count on all VENs:
PUT api/v2/orgs/:xorg_id/sec_policy/draft/firewall_settings
The property rule_hit_count_enabled_scopes was added to this API:
{
"properties": {
"rule_hit_count_enabled_scopes": {
"description": "Workloads that match the scope will have \
rule hit count enabled",
"$ref": "../common/rule_set_scopes_put.schema.json"
}
}
} Enable Rule Hit Count on a PCE
Use the following API to enable the feature on a PCE:
PUT /api/v2/orgs/:xorg_id/report_templates/rule_hit_count_report
{
"enabled": true
}Generating Rule Hit Count Reports
A Rule Hit Count report can be either a scheduled report generated on a recurrent basis or an ad-hoc report.
To generate the Rule Hit Count report, two new schemas have been introduced: rule_hit_count_report_params and rule_set_lists:
rule_hit_count_report_params
The new schema returns the rule hit count statistics for all the rules in a ruleset during the specified time-range.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Returns the rule hit count stats for all the rules in a \
ruleset during the specified time-range",
"type": "object",
"additionalProperties": false,
"required": [
"report_time_range",
"rule_sets"
],
"properties": {
"report_time_range": {
"description": "Time range the report is built across",
"type": "object",
"oneOf": [
{
"$ref": "report_time_range_definitions.schema.json#/definitions/\
custom_date_range"
},
{
"$ref": "report_time_range_definitions.schema.json#/definitions/\
last_num_days"
}
]
},
"rule_sets": {
"$ref": "rule_set_lists.schema.json"
},
"max_results": {
"description": "maximum number of rules to return in the specified \
time-range in descending order of rule creation time",
"minimum": 0,
"maximum": 200000,
"type": "integer"
}
}
}rule_set_lists
This schema returns the rule hit count statistics for all the rules in a ruleset during the specified time-range.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Returns the rule hit count stats for all the rules in a ruleset
during the specified time-range",
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"href"
],
"properties": {
"href": {
"description": "HREF of the ruleset",
"type": "string"
}
}
}
}Generate an Ad-hoc Report
The following API can be used to create a report for the last x number of days. In the example, It generates a rule hit count report for the last 30 days for all rule sets.
POST /api/v2/orgs/:xorg_id/reports
{
"report_template": {
"href": "/orgs/1/report_templates/rule_hit_count_report"
},
"description": "My first rule hit count report",
"report_parameters": {
"report_time_range": {
"last_num_days": 30
},
"rule_sets": []
},
"send_by_email": true
}The example response is such as the following:
{
"href": "/orgs/1/reports/d1b80240-ffa5-4e99-b2a0-c3d4946efe03",
"report_template": {
"href": "/orgs/1/report_templates/rule_hit_count_report",
"name": "Rule Hit Count Report"
},
"description": "My first rule hit count report",
"created_at": "2023-11-03T07:52:04.018Z",
"updated_at": "2023-11-03T07:52:04.018Z",
"progress_percentage": 0,
"generated_at": null,
"status": "pending",
"report_parameters": {
"report_time_range": {
"last_num_days": 30
},
"rule_sets": []
},
"send_by_email": true,
"created_by": {
"href": "/users/1"
},
"updated_by": {
"href": "/users/1"
}
}To create a report for a custom date range, use the following API:
{
"report_template": {
"href": "/orgs/1/report_templates/rule_hit_count_report"
},
"description": "My first rule hit count report",
"report_parameters": {
"report_time_range": {
"start_date": "2023-10-03T00:00:00Z",
"end_date": "2023-11-03T23:59:59Z"
},
"rule_sets": []
},
"send_by_email": true
}Check the Status of the Report
Use a GET API and the HREF from the POST response to check the status of the report:
GET /api/v2/orgs/:xorg_id/reports/:report_uuid
{
"href": "/orgs/1/reports/d1b80240-ffa5-4e99-b2a0-c3d4946efe03",
"report_template": {
"href": "/orgs/1/report_templates/rule_hit_count_report",
"name": "Rule Hit Count Report"
},
"description": "My first rule hit count report",
"created_at": "2023-11-03T07:52:04.018Z",
"updated_at": "2023-11-03T07:52:05.233Z",
"progress_percentage": 100,
"generated_at": "2023-11-03T07:52:05.233Z",
"status": "done",
"report_parameters": {
"rule_sets": [],
"report_time_range": {
"last_num_days": 30
}
},
"send_by_email": true,
"created_by": {
"href": "/users/1"
},
"updated_by": {
"href": "/users/1"
}
}Download the Report
When the status of the report is completed, it is emailed to the user who created the report if the option send_by_email is set.
Once the status of the report is set to "done", the report can be downloaded using the download API as follows.
GET /api/v2/orgs/:xorg_id/reports/:report_uuid/download
Here's a sample response that can be saved as CSV:
Rule HREF,Rule Name,Rule Set HREF,Rule Set Name,Rule Hit Count,Days Since Last Hit,\
Last Updated Timestamp,Last Updated By,Start Date,End Date
/orgs/1/sec_policy/active/rule_sets/1/sec_rules/23,"",/orgs/1/sec_policy/active/\
rule_sets/1,Default,0,-1,2023-08-07T22:55:37-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00Z
/orgs/1/sec_policy/active/rule_sets/1/sec_rules/21,"",/orgs/1/sec_policy/active/\
rule_sets/1,Default,0,-1,2023-07-25T04:48:09-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00Z
/orgs/1/sec_policy/active/rule_sets/1/sec_rules/19,"",/orgs/1/sec_policy/active/\
rule_sets/1,Default,0,1,2023-07-25T04:35:31-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00Z
/orgs/1/sec_policy/active/rule_sets/1/sec_rules/8,"",/orgs/1/sec_policy/active/\
rule_sets/1,Default,0,-1,2023-07-21T16:34:08-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00Z
/orgs/1/sec_policy/active/rule_sets/1/sec_rules/3,"",/orgs/1/sec_policy/active/\
rule_sets/1,Default,0,1,2023-07-20T04:22:23-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00Z
/orgs/1/sec_policy/active/rule_sets/1/sec_rules/1,Allow outbound connections,/\
orgs/1/sec_policy/active/rule_sets/1,Default,0,1,2023-07-25T04:52:39-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00Z
/orgs/1/sec_policy/active/enforcement_boundaries/5,my test deny rule with iplists,"",\
"",0,-1,2023-07-20T03:00:05-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00Z
/orgs/1/sec_policy/active/enforcement_boundaries/3,ransomware_deny_rule2,"","",0,1,\
2023-06-30T17:16:38-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00Z
/orgs/1/sec_policy/active/enforcement_boundaries/1,ransomware deny rule,"","",0,-1,\
2023-06-07T23:32:07-07:00,
/users/1,2023-10-04T00:00:00Z,2023-11-02T23:59:00ZSchedule a Recurrent Report
To create a recurring report, you need to create a report schedule. In this example, the report named "Monthly Rule Hit Count Report" is generated for the last 30 days, and will be sent via email to the person who requested the report.
Create a Report Schedule
{
"report_template": {
"href": "/orgs/1/report_templates/rule_hit_count_report"
},
"report_parameters": {
"report_time_range": {
"last_num_days": 30
},
"rule_sets": []
},
"send_by_email": true,
"report_generation_frequency": "monthly",
"name": "Monthly Rule Hit Count Report",
}Other API Changes to Support the Rule Hit Count Feature
sec_policy_label_groups_get
The property rule_hit_count_enabled_scopes was added.
"properties": {
"rule_hit_count_enabled_scopes": {
"description": "Label Group is referenced by Rule Hit Count Enabled Scopes",
"type": "boolean"
}sec_policy_firewall_settings_get
The property rule_hit_count_enabled_scopes was added.
{
"properties": {
"rule_hit_count_enabled_scopes": {
"description": "Workloads that match the scope will have rule hit count \
enabled",
"$ref": "../common/rule_set_scopes_get.schema.json"
}
}
}report_schedules_get report_schedules_put report_schedules_post reports_post report_templates_get
{
"$ref": "rule_hit_count_report_params.schema.json"
}In all these listed APIs, a reference to the schema rule_hit_count_report_params was added:
Organization Access
Changes to the organization access introduced a new common schema:
common ipv4_ipv6_subnet
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"oneOf": [
{ "format": "ipv4" },
{ "format": "ipv6" }
]
}This common schema is replacing the one that is now deleted: common ipv4_subnet
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "string",
"pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|
[01]?[0-9][0-9]?)(\\/(3[0-2]|[0-2]?[0-9]))?$"
}Three organization access APIs have been changed to substitute common/ipv4_subnet.schema with common/ipv4_ipv6_subnet.schema:
orgs_access_restrictions_post orgs_access_restrictions_put
{
"properties": {
"ips": {
"items": {
"$ref": {
"__old": "../common/ipv4_subnet.schema.json",
"__new": "../common/ipv4_ipv6_subnet.schema.json"
}
}
}
}
}settings_trusted_proxy_ips_put
{
"properties": {
"trusted_proxy_ips": {
"items": {
"properties": {
"ip": {
"$ref": {
"__old": "../common/ipv4_subnet.schema.json",
"__new": "../common/ipv4_ipv6_subnet.schema.json"
}
}
}
}
}Cluster Mode for Container Cluster
The new property cluster_mode was added to describe the cluster mode for container cluster:
container_clusters_get
{
"properties": {
"cluster_mode__added": {
"description": "Cluster mode of Container Cluster",
"type": "string",
"default": "legacy"
}
}
}