flowsearch

Matches network traffic records against flow rules defined in a subquery. Compares source/destination IP, port, and protocol information from input records against the flow rules in the subquery result, and assigns the list of matching rules to the _flow field.

Command properties

Syntax

Options

timeout=INT{s|m|h|d|mon}

Subquery execution time limit. If the subquery does not complete within the specified time, it is canceled and an error message is assigned to the _flowsearch_error field.

Target

[ SUBQUERY ]

Subquery enclosed in square brackets ([]). The subquery result is used as flow rules. The subquery result must contain the following fields:

• src_ip (ipaddr, required): Source network address
• dst_ip (ipaddr, required): Destination network address
• src_cidr (integer, required): Source CIDR prefix length (0–32)
• dst_cidr (integer, required): Destination CIDR prefix length (0–32)
• src_port (integer, optional): Source port number (0–65535). Matches all ports if not specified.
• dst_port (integer, optional): Destination port number (0–65535). Matches all ports if not specified.
• protocol (string, optional): Protocol name. Matches all protocols if not specified (case-insensitive).
• flow (any, required): Rule identifier. This value is included in the matching result. If null, the rule is ignored.

Input fields

Output fields

Error codes

Parse errors

Runtime errors

N/A

Description

The flowsearch command loads the subquery result as a flow rule table, then compares the network address information of each input record against the rules. The subquery runs before the main query, and loads up to 10,000 rules.

The matching process is as follows:

1. The src_ip and dst_ip of the input record are masked with the CIDR prefix length of each rule to calculate the network address.
2. The rule's network address is compared against the input record's network address.
3. If the network addresses match, port and protocol conditions are additionally checked.
4. The flow values of all matching rules are added to the _flow array.

Rules from the subquery result that are missing required fields (src_ip, dst_ip, src_cidr, dst_cidr, flow) or have incorrect types are ignored.

If the src_ip or dst_ip of the input record is not an IP address type, or if port fields are not numeric, an error message is assigned to the _flowsearch_error field and the _flow field is not assigned.

Examples

1. Match with inline flow rules

   json "[{'src_ip': ip('192.0.2.1'), 'dst_ip': ip('198.51.100.1'), 'src_port': 12345, 'dst_port': 80, 'protocol': 'TCP'}]"
   | flowsearch [
       json "[{'src_ip': ip('192.0.2.0'), 'dst_ip': ip('198.51.100.0'), 'src_cidr': 24, 'dst_cidr': 24, 'dst_port': 80, 'protocol': 'TCP', 'flow': 'web-traffic'}]"
     ]
   

   Matches against a rule where the source is in the 192.0.2.0/24 range, destination is in the 198.51.100.0/24 range, destination port is 80, and protocol is TCP. ["web-traffic"] is assigned to the _flow field.

2. Set a subquery time limit

   table duration=1h netflow_logs
   | flowsearch timeout=10s [
       table duration=1d flow_rules
     ]
   

   Loads flow rules from the flow_rules table, but cancels the subquery if it does not complete within 10 seconds. If the subquery times out, sub query timeout is assigned to the _flowsearch_error field of all input records.

3. Match without port and protocol conditions

   json "[{'src_ip': ip('192.0.2.10'), 'dst_ip': ip('203.0.113.5')}]"
   | flowsearch [
       json "[{'src_ip': ip('192.0.2.0'), 'dst_ip': ip('203.0.113.0'), 'src_cidr': 24, 'dst_cidr': 24, 'flow': 'internal-to-external'}]"
     ]
   

   Matches based on network ranges only, without port and protocol conditions. If src_port, dst_port, and protocol fields are not specified in the rule, those conditions are not checked.