IP functions

Learn how to use and combine different ip functions in APL

IP functions

Function Name	Description
format_ipv4()	Parses input with a netmask and returns string representing IPv4 address.
parse_ipv4()	Converts input to long (signed 64-bit) number representation.
parse_ipv4_mask()	Converts input string and IP-prefix mask to long (signed 64-bit) number representation.
ipv4_is_in_range()	Checks if IPv4 string address is in IPv4-prefix notation range.
ipv4_is_private()	Checks if IPv4 string address belongs to a set of private network IPs.
ipv4_netmask_suffix()	Returns the value of the IPv4 netmask suffix from IPv4 string address.
geo_info_from_ip_address()	Extracts geographical, geolocation, and network information from IP addresses. It supports both IPv4 and IPv6 addresses.

IP-prefix notation

IP addresses can be defined with IP-prefix notation using a slash (/) character. The IP address to the LEFT of the slash (/*) is the base IP address. The number (1 to 32) to the RIGHT of the slash (/) is the number of contiguous 1 bit in the netmask.

For example, 192.168.2.0/24 will have an associated net/subnetmask containing 24 contiguous bits or 255.255.255.0 in dotted decimal format.

format_ipv4()

Parses input with a netmask and returns string representing IPv4 address.

Arguments

• Expr(IP): A string or number representation of the IPv4 address.

Returns

If conversion is successful, the result will be a string representing IPv4 address. If conversion isn’t successful, the result will be an empty string.

Example

format_ipv4(ip)

['sample-http-logs']
| project str_ipv4 = format_ipv4("192.168.2.0")

Run in Playground

• Result

{
  "str_ipv4": "192.168.2.0"
}

parse_ipv4()

Converts IPv4 string to long (signed 64-bit) number representation.

Arguments

• Expr: String expression representing IPv4 that will be converted to long. String may include net-mask using IP-prefix notation.

Returns

If conversion is successful, the result will be a long number. If conversion isn’t successful, the result will be null.

Example

parse_ipv4(Expr)

['sample-http-logs']
| project parsed_ipv4 = parse_ipv4("192.168.2.0")

Run in Playground

• Result

{
  "parsed_ipv4": 3232236032
}

parse_ipv4_mask()

Converts the input string of IPv4 and netmask to long number representation (signed 64-bit).

Arguments

• Expr: A string representation of the IPv4 address that will be converted to long.
• PrefixMask: An integer from 0 to 32 representing the number of most-significant bits that are taken into account.

Returns

If conversion is successful, the result will be a long number. If conversion isn’t successful, the result will be null.

Example

parse_ipv4_mask(Expr, PrefixMask)

['sample-http-logs']
| project parsed_ipv4 = parse_ipv4_mask("192.5.1.4", 24)

Run in Playground

• Result

{
  "parsed_ipv4": 3221553408
}

ipv4_is_in_range()

Checks if IPv4 string address is in IPv4-prefix notation range.

Arguments

• Ipv4Address: A string expression representing an IPv4 address.
• Ipv4Range: A string expression representing an IPv4 range using IP-prefix notation.

Returns

• true: If the long representation of the first IPv4 string argument is in range of the second IPv4 string argument.
• false: Otherwise.
• null: If conversion for one of the two IPv4 strings wasn’t successful.

Examples

ipv4_is_in_range('192.168.1.5', '192.168.1.2/24') 

Run in Playground

• Result

{
  "ipv4_in_range": true
}

ipv4_is_in_range("127.2.3.1", "127.2.3.1") == true 

Run in Playground

• Result

{
  "ipv4_range": true
}

ipv4_is_in_range('192.168.1.5', '192.168.1.5/24') == true

ipv4_is_in_range('192.168.1.5', '192.168.2.1/24') == false 

Run in Playground

• Result

{
  "ipv4_range": false
}

ipv4_is_private()

Checks if IPv4 string address belongs to a set of private network IPs.

Private IPv4 addresses

The private IPv4 addresses reserved for private networks by the Internet Assigned Numbers Authority (IANA) are:

IP address range	Number of addresses	Largest CIDR block (subnet mask)
10.0.0.0 – 10.255.255.255	16777216	10.0.0.0/8 (255.0.0.0)
172.16.0.0 – 172.31.255.255	1048576	172.16.0.0/12 (255.240.0.0)
192.168.0.0 – 192.168.255.255	65536	192.168.0.0/16 (255.255.0.0)

Arguments

• Expr: A string expression representing an IPv4 address. IPv4 strings can be masked using IP-prefix notation.

Returns

• true: If the IPv4 address belongs to any of the private network ranges.
• false: Otherwise.
• null: If parsing of the input as IPv4 address string wasn’t successful.

Example

ipv4_is_private('192.168.2.1') == true

Run in Playground

• Result

{
  "ipv4_private": true
}

ipv4_is_private('208.1.2.3') == false

Run in Playground

• Result

{
  "ipv4_private": false
}

ipv4_netmask_suffix()

Returns the value of the IPv4 netmask suffix from IPv4 string address.

Arguments

Expr: A string expression representing an IPv4 address. IPv4 strings can be masked using IP-prefix notation.

Returns

• The value of the netmask suffix the IPv4 address. If suffix is not present in the input, a value of 32 (full netmask suffix) is returned.

• null: If parsing of the input as IPv4 address string wasn’t successful.

Example

ipv4_netmask_suffix('192.164.2.2/24') == 24

Run in Playground

• Result

{
  "netmask_suffix": 24
}

ipv4_netmask_suffix('192.166.1.2') == 32

Run in Playground

• Result

{
  "netmask_suffix": 32
}

geo_info_from_ip_address()

Extracts geographical, geolocation, and network information from IP addresses. It supports both IPv4 and IPv6 addresses.

Arguments

Name	Type	Required	Description
ipAddress	String	Yes	The IP address to extract information from. Can be IPv4 or IPv6

Returns

A dynamic object containing the information on the IP address’s whereabouts (if the information is available). The object contains the following fields:

Name	Type	Description
country	string	Country name
state	string	State (subdivision) name
city	string	City name
latitude	real	Latitude coordinate
longitude	real	Longitude coordinate
country_iso	string	ISO code of the country
time_zone	string	Time zone in which the IP address is located

Examples

geo_info_from_ip_address(IpAddress)

IPv4 Examples

Extracting geolocation information from IPv4 address

['sample-http-logs']
| extend ip_location = geo_info_from_ip_address('172.217.11.4')

Run in Playground

Projecting geolocation information from IPv4 address

['sample-http-logs']
| project ip_location=geo_info_from_ip_address('20.53.203.50')

Run in Playground

Filtering geolocation information from IPv4 address

['sample-http-logs']
| extend ip_location = geo_info_from_ip_address('20.53.203.50')
| where ip_location.country == "Australia" and ip_location.country_iso == "AU" and ip_location.state == "New South Wales"

Run in Playground

Grouping geolocation information from IPv4 address

['sample-http-logs']
| extend ip_location = geo_info_from_ip_address('20.53.203.50')
| summarize Count=count() by ip_location.state, ip_location.city, ip_location.latitude, ip_location.longitude

Run in Playground

IPv6 Examples

Extracting geolocation information from IPv6 address

['sample-http-logs']
| extend ip_location = geo_info_from_ip_address('2607:f8b0:4005:805::200e')

Run in Playground

Projecting geolocation information from IPv6 address

['sample-http-logs']
| project ip_location=geo_info_from_ip_address('2a03:2880:f12c:83:face:b00c::25de')

Run in Playground

Filtering geolocation information from IPv6 address

['sample-http-logs']
| extend ip_location = geo_info_from_ip_address('2a03:2880:f12c:83:face:b00c::25de')
| where ip_location.country == "United States" and ip_location.country_iso == "US" and ip_location.state == "Florida"

Run in Playground

Grouping geolocation information from IPv6 address

['sample-http-logs']
| extend ip_location = geo_info_from_ip_address('2a03:2880:f12c:83:face:b00c::25de')
| summarize Count=count() by ip_location.state, ip_location.city, ip_location.latitude, ip_location.longitude

Run in Playground