Rules hit count

Count the number of times a specific rule or rules were triggered on a specific device.

Resource Name:

/api/v1/rules/hit-count

Request Method: POST

Request URL Header:

Element Type Description

Cookie

Mandatory

String Cookie obtained from the connect method.

Request URL Parameters:

Element Type Description

invertSorting

Optional

Boolean

If true, sorts the rules with the least hits first.

Default = False

Request body parameters

Element Type Description

deviceTreeName

Mandatory

String

Tree name of the device.

(To get the entity name for a device or group, see Device names in the ASMS APIs).

ruleIds

Optional

String

The Rule IDs for which to collect hit counts. If more than one Rule ID, separate with commas.

For example: [ruleid1, ruleid2, ruleid3]

startTime

endTime

Mandatory, when latestReport is set to false, or left blank

Integer (Epoch/Unix
Timestamp)

Count the number of hits that occurred between startTime and endTime.

latestReport

Mandatory, when startTime and endTime are left blank

Boolean If true, uses the startTime and endTime defined in the latest report.

pageSize

Optional

Integer

The number of rows to display per page in the output JSON file.

Tip: By default, rules with zero hits are not shown in the results, although the user is notified that these rules exist.

To include rules with zero hit counts in the response, increase the pageSize parameter in the API enough to fit all the rules onto a single page.

page

Optional

Integer

The page to display in the output JSON file.

Response:

Code

Description
200

OK. The response includes a set of JSON code based on the data included in the request.

400

Request is invalid

403

Unauthorized

404

Device not found

500

Policy Optimization failed

Example request

The following example sorts the rules included in the response by least hit counts to most.

curl -X POST -H "Content-Type: application/json"

"https://<server>:<port>/ms-policy-optimizations/api/v1/rules/hit-count"

--cookie "PHPSESSID=<sessionID>" -d '{

"deviceTreeName": "<device-name>",

"ruleIds":[],

"startTime": <epoch-time>,

"endTime": <epoch-time>,

}'

Example response

The following is a truncated response showing a few rules on the device, and the number of times each rule was used.

Note: We've formatted the following example to make it easier to read. Real responses for the hit-count API are formatted as a single line.

{
"status":"OK",
"data":
{
 "deviceTreeName":"MyDevice",
"ruleIds":
 {"content":
  [
   {"ruleId":"from_dmz_to_untrust_name_119","count":11937},
   {"ruleId":"from_untrust_to_dmz_name_153","count":10371},
   {"ruleId":"from_untrust_to_dmz_name_166","count":8942},
   {"ruleId":"from_dmz_to_untrust_name_154","count":6513},
   ....
   ....
   {"ruleId":"from_untrust_to_dmz_name_150","count":73}],"number":0,"size":900,"totalElements":35,"pageable":   
   {"sort":  
    {"sorted":false,"unsorted":true,"empty":true},
   "pageNumber":0,"pageSize":900,"offset":0,"paged":true,"unpaged":false
     },
    "last":true,"totalPages":1,"sort":  
    {"sorted":false,"unsorted":true,"empty":true},
    "first":true,"numberOfElements":35,"empty":false
    },
   "startTime":1,"endTime":1974667654000},"additionalInfo":{}
 }