ipv4_is_match

This page explains how to use the ipv4_is_match function in APL.

The ipv4_is_match function in APL helps you determine whether a given IPv4 address matches a specific IPv4 pattern. This function is especially useful for tasks that involve IP address filtering, including network security analyses, log file inspections, and geo-locational data processing. By specifying patterns that include wildcards or CIDR notations, you can efficiently check if an IP address falls within defined ranges or meets specific conditions.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

Splunk SPL users

The ipv4_is_match function in APL resembles the cidrmatch function in Splunk SPL. Both functions assess whether an IP address falls within a designated CIDR range, but ipv4_is_match also supports wildcard pattern matching, providing additional flexibility.

Splunk example

cidrmatch("192.168.1.0/24", ip)

ANSI SQL users

ANSI SQL lacks a direct equivalent to the ipv4_is_match function, but you can replicate similar functionality with a combination of LIKE and range checking. However, these approaches can be complex and less efficient than ipv4_is_match, which simplifies CIDR and wildcard-based IP matching.

SQL example

ip LIKE '192.168.1.0'

Usage

Syntax

ipv4_is_match(ipaddress1, ipaddress2, prefix)

Parameters

• ipaddress1: A string representing the first IPv4 address you want to evaluate. Use CIDR notation (for example, 192.168.1.0/24).
• ipaddress2: A string representing the second IPv4 address you want to evaluate. Use CIDR notation (for example, 192.168.1.0/24).
• prefix: Optionally, a number between 0 and 32 that specifies the number of most-significant bits taken into account.

Returns

• true if the IPv4 addresses match.
• false otherwise.
• null if the conversion of an IPv4 string wasn’t successful.

Use case example

The ipv4_is_match function allows you to identify traffic based on IP addresses, enabling faster identification of traffic patterns and potential issues.

Query

['sample-http-logs']
| extend is_match = ipv4_is_match('203.0.113.112', '203.0.113.112')

Run in Playground

Output

_time	id	status	method	uri	is_match
2023-11-11T13:20:14	203.0.113.45	403	GET	/admin	true
2023-11-11T13:30:32	203.0.113.101	401	POST	/restricted	true

List of related functions

• has_any_ipv4: Matches any IP address in a string column with a list of IP addresses or ranges.
• has_ipv4_prefix: Checks if an IPv4 address matches a single prefix.
• has_ipv4: Checks if a single IP address is present in a string column.
• ipv4_compare: Compares two IPv4 addresses lexicographically. Use for sorting or range evaluations.