matchblackip

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

Command properties

Syntax

In the syntax above, name is available starting with 4.0.2609.0.

Options

guid=STR

GUID of the address group to compare against. In the 5.0 series (through 5.0.2605.2), this is the only way to specify the target. In the 4.0 series (4.0.2609.0 and later), this option cannot be used together with name, and you must specify either guid or name.

name=STR

Name of the address group to compare against (cannot be used together with guid). You must specify either the guid or name option. This option is available starting with 4.0.2609.0.

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

Output fields

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

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

Error codes

Parse errors

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.

Use the guid option to specify the address group to compare against. In the 4.0 series (4.0.2609.0 and later), you can also use the name option; the command looks up the group by that name to resolve its GUID, and specifying both guid and name, or omitting both, causes an error, as does specifying a name that does not exist or that matches more than one group.

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

1. 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.

2. 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.

3. 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.

4. 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.

5. Specifying an address group by name (4.0 series, 4.0.2609.0 and later)

   table limit=1000 WEB_APACHE_SAMPLE
   | matchblackip name=known_attackers fields=src_ip
   

   Compares using an address group specified by name instead of GUID.

Change history