Retrieve a list of rules according to the search query provided by user. This endpoint returns a full response.
This API searches fields based on device type as documented in AFA search rule fields
By default, search results are limited to 5,000 rules for full search. To configure the limit, see ADV_SEARCH_MAX_RESULTS.
The query for this search must be written in the following format:
Advanced search query format
The format for a simple query is:
[column name][Basic Operator][value]
You can make complex queries by combining Basic queries separated by a Composite Operator:
[Basic Query][Composite Operator][Basic Query]
Tips:
-
Brackets are optional.
-
You can use wild cards (*) except for contained objects (object/ IP Address definition of object content).
-
< and > symbols are not supported. Use the wild card (*) (except for contained objects).
-
For internal quotation marks, use \" instead of ".
-
Wrap values or column names in \".
-
To search for empty fields, use [EMPTY] as Rule column value.
-
To search across all fields, use ALL_FIELDS as the rule column name.
-
Entered search string must be an exact match.
You can use the following operators:
| Basic Operators | Composite Operators | ||
| == | Equal To | and | Logical AND |
| != | Not Equal To | or | Logical OR |
For example:
(\"Source Address\" == \"170.251.44.93\") or (\"Service\" != \"tcp\")
Equals to:
(Source equals to "1.2.3.4") or (Service object not equal to "tcp udp" )
Resource Name:
Request Method: POST
Request Parameters:|
Element |
Type |
Description |
|---|---|---|
| ruleSearchQuery Mandatory |
String |
Search query. Use query format as shown above. |
| treeName
Mandatory |
String |
Can refer to a device, group or ALL_FIREWALLS. To get the tree name, use GET /devices method from the Devices Setup Resource Group. |
|
exactMatch optional |
Boolean |
For results that only list objects that contain the exact IP address(es) or service(s) you are searching for, select true.
|
|
includeAny Optional |
Boolean |
In addition to the search query, also find rules that contain 'Any' in any of the fields queried.
|
|
includeContainment Optional |
Boolean |
Enhance the query to search additionally for objects that contain the searched object/IP address.
|
Response parameters
Includes these basic parameters and more (see response example):
|
Element |
Type |
Description |
|---|---|---|
| totalFoundRulesCount |
number |
Total number of rules found across all devices. |
| devicesFoundBySearch |
array |
array of results per device. |
| deviceFoundRulesCount | number | Total number of rules found for the device. |
| deviceInfo | object | object containing device info. |
| treeName | string | Tree name of device. |
| displayName | string | Display name of the device. |
| brand | string | Brand name code. |
| foundRules | array | Array of rules found. |
| criteriaMatch | Array of objects | Array of objects that match query and rule |
| field | string | The ruleColumn found. |
| values | array of strings | Value of the ruleColumn found contents. |
| ruleId | string | Rule ID. |
| ruleNum | string | Rule number. |
The search also returns additional information about the rule specific to the device.
Response:
|
Code |
Description |
|---|---|
| 200 |
Successfully retrieved requested rules |
|
400 |
Request is invalid |
|
401 |
Unauthorized session |
| 403 | Access Forbidden |
| 404 | Not Found |
| 500 | Query rules operation has failed |
Request cURL examples
curl -X POST "https://localhost/afa/api/v1/rule/advancedsearch/full/device1?includeAny=true&includeContainment=true" -H 'Cookie: PHPSESSID=<sessionId>' -H "accept: */*" -H "Content-Type: application/json" -d "{ "searchQuery": "(\"Source Address\" == \"170.251.44.93\") or (\"Service\" != \"tcp\")" }
Request examples
{
"searchQuery": "(\"Source Address\" == \"170.251.44.93\") or (\"Service\" != \"tcp\")"
}
Response 200 example
{
"totalFoundRulesCount": 2,
"devicesFoundBySearch": [
{
"deviceFoundRulesCount": 2,
"deviceInfo": {
"treeName": "Anemone_Meraki",
"displayName": "Anemone1_Meraki",
"brand": "ciscomeraki"
},
"foundRules": [
{
"criteriaMatch": [
{
"field": "Src. Address",
"values": [
"Any"
]
}
],
"rule": {
"deviceId": 60400,
"deviceDisplayName": "Anemone1_Meraki",
"ruleId": "l3_inbound_rule_default",
"ruleNum": "17",
"source": [
{
"canonizedName": "Any",
"invalidNamedObject": true
}
],
"isNegateSource": false,
"destination": [
{
"canonizedName": "Any",
"invalidNamedObject": true
}
],
"urlCategories": [
{
"canonizedName": "",
"invalidNamedObject": true
}
],
"isNegateDestination": false,
"service": [
{
"canonizedName": "Any",
"invalidNamedObject": true
}
],
"isNegateService": false,
"action": "",
"comment": [
"Default rule"
],
"enable": "",
"log": "",
"link": "rule_l3_inbound_rule_default",
"documentation": {
"business criticality": "",
"business partner": "",
"documentation": "",
"business applications": ""
},
"additionalData": {
"group_policy_name": [
{
"value": ""
}
],
"src_port": [
{
"value": ""
}
],
"protocol": [
{
"value": ""
}
],
"group_rulenum": [
{
"value": ""
}
],
"dst_port": [
{
"value": ""
}
],
"policy": [
{
"value": "Deny"
}
]
},
"isValidUserSourceModel": true
}
},
{
"criteriaMatch": [
{
"field": "Src. Address",
"values": [
"GroupPolicy_Public_GP_Clients"
]
}
],
"rule": {
"deviceId": 40900,
"deviceDisplayName": "Anemone1_Meraki",
"ruleId": "Public_rule_1",
"ruleNum": "8",
"source": [
{
"canonizedName": "GroupPolicy_Public_GP_Clients",
"invalidNamedObject": true
}
],
"isNegateSource": false,
"destination": [
{
"canonizedName": "10.60.17.88/32",
"invalidNamedObject": true
}
],
"urlCategories": [
{
"canonizedName": "",
"invalidNamedObject": true
}
],
"isNegateDestination": false,
"service": [
{
"canonizedName": "tcp/*/*",
"invalidNamedObject": true
}
],
"isNegateService": false,
"action": "",
"comment": [
"test drop"
],
"enable": "",
"log": "",
"link": "rule_Public_rule_1",
"documentation": {
"business criticality": "",
"business partner": "",
"documentation": "",
"business applications": ""
},
"additionalData": {
"group_policy_name": [
{
"value": "Public_GP"
}
],
"src_port": [
{
"value": "Any"
}
],
"protocol": [
{
"value": "TCP"
}
],
"group_rulenum": [
{
"value": "1"
}
],
"dst_port": [
{
"value": "Any"
}
],
"policy": [
{
"value": "Deny"
}
]
},
"isValidUserSourceModel": true
}
},
{
"criteriaMatch": [
{
"field": "Src. Address",
"values": [
"Any"
]
}
],
"rule": {
"deviceId": 40900,
"deviceDisplayName": "Anemone1_Meraki",
"ruleId": "l3_outbound_rule_default",
"ruleNum": "16",
"source": [
{
"canonizedName": "Any",
"invalidNamedObject": true
}
],
"isNegateSource": false,
"destination": [
{
"canonizedName": "Any",
"invalidNamedObject": true
}
],
"urlCategories": [
{
"canonizedName": "",
"invalidNamedObject": true
}
],
"isNegateDestination": false,
"service": [
{
"canonizedName": "Any",
"invalidNamedObject": true
}
],
"isNegateService": false,
"action": "",
"comment": [
"Default rule"
],
"enable": "",
"log": "",
"link": "rule_l3_outbound_rule_default",
"documentation": {
"business criticality": "",
"business partner": "",
"documentation": "",
"business applications": ""
},
"additionalData": {
"group_policy_name": [
{
"value": ""
}
],
"src_port": [
{
"value": "Any"
}
],
"protocol": [
{
"value": "Any"
}
],
"group_rulenum": [
{
"value": ""
}
],
"dst_port": [
{
"value": "Any"
}
],
"policy": [
{
"value": "Allow"
}
]
},
"isValidUserSourceModel": true
}
},
]
}
]
}
