matchblackip

Compares IP address field values of input records against a specified address group (IP blocklist) and filters records that match.

Command properties

Property	Description
Command type	Transforming
Required permission	None
License usage	N/A
Parallel execution	Supported
Distributed execution	Runs on Data Node (mapper)

Syntax

matchblackip guid=STR fields=FIELD, ... [invert=BOOL] [verify=BOOL]

Options

guid=STR: GUID of the address group to compare against.
fields=FIELD, ...: List of IP address field names to compare. Separate multiple fields with commas (,).
invert=BOOL: Whether to invert the comparison result. (Default: f)

t: Outputs records not included in the address group
f: Outputs records included in the address group

verify=BOOL: Whether to validate the existence of the address group. (Default: t)

t: Validates that the address group exists at parse time
f: Skips address group validation

Input fields

Field	Type	Required	Description
Value specified by `fields`	string or IP address	Required	IP address to compare. Must be a string or `InetAddress` type; null values or other types are skipped.

Output fields

When invert=f (default), the following fields are appended to records that match the address group:

Field	Type	Description
blackip_guid	string	GUID of the matched address group
blackip_name	string	Name of the matched address group
blackip_reason	string	Description of the matched IP address
blackip_invert	boolean	Value of the `invert` option (`false`)
blackip_field	string	Name of the field where the match was found

When invert=t, the following fields are appended to records that do not match the address group:

Field	Type	Description
blackip_guid	string	GUID of the address group
blackip_name	string	Name of the address group
blackip_invert	boolean	Value of the `invert` option (`true`)

Error codes

Parse errors

Error code	Message	Description
300034	Specify the guid option for the matchblackip command.	The `guid` option was not specified.
300035	The guid option for the matchblackip command must be in GUID format.	The `guid` option value is not a valid GUID.
300036	Specify the fields option for the matchblackip command.	The `fields` option was not specified.
300037	The specified IP blocklist does not exist.	No address group exists for the specified GUID.

Runtime errors

None

Description

The matchblackip command compares IP address values from the fields specified by the fields option against an address group. When multiple fields are specified in fields, they are checked in order; when a match is found in the first matching field, the record is immediately output and the remaining fields are not checked.

If a field value is null or is not a string or InetAddress type, that field is skipped. If no match is found across all fields, the record is discarded.

When invert=t is specified, only records with no match across all fields are output.

When verify=f is specified, the existence of the address group is not validated at parse time. Use this option in real-time stream queries where the address group is synchronized at a later time.

In distributed environments, filtering runs on Data Nodes.

Examples

Filter records that match the address group

json "[{'src_ip': '192.0.2.1'}, {'src_ip': '192.0.2.2'}, {'src_ip': '198.51.100.5'}]"
| matchblackip guid=550e8400-e29b-41d4-a716-446655440000 fields=src_ip

Outputs only records where the src_ip field matches the specified address group.

Specify multiple fields to compare

json "[{'src_ip': '192.0.2.1', 'dst_ip': '198.51.100.10'}]"
| matchblackip guid=550e8400-e29b-41d4-a716-446655440000 fields=src_ip,dst_ip

Compares src_ip and dst_ip fields in order; outputs the record if either matches the address group.

Filter records not in the address group

json "[{'src_ip': '192.0.2.1'}, {'src_ip': '203.0.113.50'}]"
| matchblackip guid=550e8400-e29b-41d4-a716-446655440000 fields=src_ip invert=t

Outputs only records where the src_ip field is not included in the address group.

Skip address group validation

json "[{'src_ip': '192.0.2.1'}]"
| matchblackip guid=550e8400-e29b-41d4-a716-446655440000 fields=src_ip verify=f

Runs without validating the existence of the address group at parse time.