matchport()

The matchport() function checks whether a specific port number and protocol combination is included in a specified port group.

Syntax

matchport(STR_GUID, PORT_EXPR[, PROTO_EXPR])

Parameters

STR_GUID
The GUID of the port group. Must be a valid port group identifier. If a non-existent GUID is specified, an error occurs at query parse time.
PORT_EXPR
The port number expression. The evaluated value must be a numeric type. If the value is not numeric, false is returned.
PROTO_EXPR
(Optional) The protocol expression. Only the strings TCP or UDP are accepted. If this parameter is omitted or is null, true is returned if the port is included in the port group for either TCP or UDP. If the value is ICMP or an unrecognized string, false is returned.

Description

The matchport() function returns true if the port and protocol combination specified by PORT_EXPR and PROTO_EXPR is included in the specified port group, or false if it is not.

If PORT_EXPR is not a numeric type, false is returned. If PROTO_EXPR is not specified or is null, the search is performed by port number alone without distinguishing by protocol. If PROTO_EXPR is ICMP or an unrecognized string, false is returned.

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

Error codes

N/A

Usage examples

  1. Check whether the value of the dst_port field is included in the specified port group

    json "{'dst_port': 443}"
| eval result = matchport("550e8400-e29b-41d4-a716-446655440000", dst_port)
| # result: false

  2. Specify the TCP protocol for the check

    json "{'dst_port': 443, 'protocol': 'TCP'}"
| eval result = matchport("550e8400-e29b-41d4-a716-446655440000", dst_port, protocol)
| # result: false

  3. PROTO_EXPR value is null (returns true if the port is included for either TCP or UDP)

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

Compatibility

matchport() has been available since before Sonar 4.0.