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.
Enabling Rule Hit Count
The Rule Hit Count feature is disabled by default on all the VENs and on the PCE.
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
{
"rule_hit_count_enabled_scopes":[[]]
}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:
{
"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_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:
{
"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
Two properties have been added to this API:
rule_hit_count_enabled_scopes, which enables the feature Rule Hit Count for the workloads that match the scope.
{
"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"
}
}
}ip_forwarding_enabled_scopes, which was added both to the Public Experimental and Public Stable schema in release 23.5.20:ip_forwarding_enabled_scopes": { "description": "Host Workloads that match the scope will have IP forwarding enabled", "$ref": "../common/rule_set_scopes_put.schema.jsonPublic Stable exposure was requested by the customers who intend to programmatically configure which workloads can have
ip-forwardingenabled. This assures that the API will not change or be removed.A reference to the schema
rule_hit_count_report_paramswas added to all following APIs:{ "$ref": "rule_hit_count_report_params.schema.json" }report_schedules_get report_schedules_put report_schedules_post reports_post report_templates_get