Rule Hit Count
The Rule Hit Count feature is configured so only certain VENs can compute the rule hit counts and send the rule ID to the PCE.
Enabling Rule Hit Count
The Rule Hit Count feature is disabled by default on all the VENs and the PCE.
To use the Rule Hit Count feature, you must first 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
{
"rule_hit_count_enabled_scopes":[[]]
}This sample API can be used to enable features in specific scopes. This example 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:
{
"rule_hit_count_enabled_scopes": []
} 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 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 create a report for the last x number of days. The example generates a rule hit count report for all rule sets for the last 30 days.
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:
{
"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:
{
"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"
}
}Map the Ruleset HREF to the Ruleset
When you map the ruleset HREf to the ruleset, the response contains the HREF of the user:
{
"href": "/orgs/2293773/sec_policy/active/rule_sets/9851624184900724",
"created_at": "2024-07-24T18:24:31.400Z",
"updated_at": "2024-07-31T21:46:43.166Z",
"deleted_at": null,
"created_by": {
"href": "/users/9851624184872975"
},
"updated_by": {
"href": "/users/9851624184872975"
},
"deleted_by": null,
"name": "App19492 | Env19492",
"description": null,
"external_data_set": "illumio_policy_generator",
"external_data_reference": "9851624185012145 | 9851624185012146",
"enabled": true,
"scopes": [
[{
"label": {
"href": "/orgs/2293773/labels/9851624185012145"
},
"exclusion": false
}, {
"label": {
"href": "/orgs/2293773/labels/9851624185012146"
},
"exclusion": false
}]
],
"rules": [{
"href": "/orgs/2293773/sec_policy/active/rule_sets/9851624184900724/sec_rules/9851624184910709",
"created_at": "2024-07-24T18:24:31.548Z",
"updated_at": "2024-07-24T18:24:31.589Z",
"deleted_at": null,
"created_by": {
"href": "/users/9851624184872975"
},
"updated_by": {
"href": "/users/9851624184872975"
},
"deleted_by": null,
"description": "",
"enabled": true,
"providers": [{
"label": {
"href": "/orgs/2293773/labels/9851624185012147"
},
"exclusion": false
}, {
"label": {
"href": "/orgs/2293773/labels/9851624185012144"
},
"exclusion": false
}],
"destinations": [{
"label": {
"href": "/orgs/2293773/labels/9851624185012147"
},
"exclusion": false
}, {
"label": {
"href": "/orgs/2293773/labels/9851624185012144"
},
"exclusion": false
}],
"consuming_security_principals": [],
"sec_connect": false,
"stateless": false,
"machine_auth": false,
"unscoped_destinations": false,
"network_type": "brn",
"use_workload_subnets": [],
"ingress_services": [{
"port": 8080,
"proto": 17
}],
"egress_services": [],
"resolve_labels_as": {
"providers": ["workloads"],
"destinations": ["workloads"]
}
}],
"ip_tables_rules": [],
"deny_rules": [],
"caps": ["write", "provision"]
}Download the Report
When the report's status 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
The 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
You need to create a report schedule to create a recurring report. In this example, the "Monthly Rule Hit Count Report" has been generated for the last 30 days and will be emailed to the person who requested it.
To 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"
}
}
}For the following APIs, a reference to the schema rule_hit_count_report_params was added.
report_schedules_get
report_schedules_put
report_schedules_post
reports_post
report_templates_get