Retrieve a list of rules according to the search query provided by user. This endpoint returns a full response.
By default, search results are limited to 5,000 rules for full search. To configure the limit, see ADV_SEARCH_MAX_RESULTS.
This APIs searches the following fields:
-
Source
-
Destination
-
Source or Destination
-
Service
-
Action
-
From Zone
-
To Zone
-
User
-
Application
-
Name
-
Comment
-
Log
-
lslPv6
-
Time
-
Enable
-
Profile
-
Install On
-
URL_Category
-
Documentation
-
Business Partner
-
Business Criticality
-
Business Applications
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
}
},
]
}
]
}
