matchblackip()

The matchblackip() function checks whether a specific IP address is included in a specified address group.

Syntax

Parameters

STR_GUID

The GUID of the address group. Must be a valid address group identifier. If a non-existent GUID is specified, an error occurs at query parse time.

IP_ADDR_EXPR

The IP address expression. Only IPv4 address type or IPv4-formatted strings are accepted. If the value is of an unsupported type, false is returned.

Description

The matchblackip() function returns true if IP_ADDR_EXPR is included in the specified address group, or false if it is not.

If IP_ADDR_EXPR is null, false is returned. If the value is an IP address type, it is converted to a string before searching the address group. If the value is neither an IPv4 address nor an IPv4-formatted string, false is returned.

Address groups are managed in the Sonar web console under Policies > Address Groups.

Error codes

N/A

Usage examples

1. Check whether the value of the src_ip field is included in the specified address group

   json "{'src_ip': '192.0.2.1'}"
   | eval result = matchblackip("550e8400-e29b-41d4-a716-446655440000", src_ip)
   | # result: false
   

2. IP_ADDR_EXPR value is null

   json "{'src_ip': null}"
   | eval result = matchblackip("550e8400-e29b-41d4-a716-446655440000", null)
   | # result: false
   

3. IP_ADDR_EXPR value is a non-IPv4 type

   json "{'src_ip': 12345}"
   | eval result = matchblackip("550e8400-e29b-41d4-a716-446655440000", src_ip)
   | # result: false
   

Compatibility

matchblackip() has been available since before Sonar 4.0.