matchport

Filters input records using a port group. Records where the port or protocol value is null or the type does not match are discarded.

Command properties

Property	Description
Command type	Transforming
Required permission	None
License usage	N/A
Parallel execution	Supported
Distributed execution	Runs on Data Node (mapper)

Syntax

matchport guid=STR [port=STR] [protocol=STR] [invert=BOOL] [verify=BOOL]

Options

guid=STR: GUID of the port group to use for matching.
port=STR: Name of the field containing the port number. (Default: port)
protocol=STR: Name of the field containing the protocol. Recognizes tcp, udp, and icmp values. (Default: protocol)
invert=BOOL: When set to t, discards records that match the port group and outputs only non-matching records. (Default: f)
verify=BOOL: When set to f, skips port group validation at the parse stage. (Default: t)

Input fields

Field	Type	Required	Description
`port`	integer	Required	Port number. You can specify a different field name using the `port` option. Records where the value is not a numeric type are discarded.
`protocol`	string	Required	Protocol name. You can specify a different field name using the `protocol` option. Records where the value is not a string are discarded.

Error codes

Parse errors

Error code	Message	Description
300010	The matchport command cannot use the field and port options simultaneously.	Both the `field` and `port` options were specified at the same time.
300011	The matchport command cannot use the field and protocol options simultaneously.	Both the `field` and `protocol` options were specified at the same time.
300012	Specify the guid option for the matchport command.	The `guid` option is missing.
300013	No port group found for the guid specified in the matchport command.	No port group exists for the specified GUID.
300014	Failed to load the port group data.	An error occurred while loading port group data.

Runtime errors

None

Description

The matchport command checks whether the port number and protocol value of input records are included in the specified port group, and outputs only matching records. When invert=t is specified, only non-matching records are output.

If the port field value is not a numeric type or the protocol field value is not a string, the record is discarded regardless of the invert option.

In a distributed environment, filtering runs on the Data Node.

Examples

Filter using a port group

json "[{'port': 80, 'protocol': 'tcp'}, {'port': 53, 'protocol': 'udp'}, {'port': 8080, 'protocol': 'tcp'}]"
| matchport guid=550e8400-e29b-41d4-a716-446655440000

Outputs only records included in the specified port group.

Extract records not matching a port group

json "[{'port': 80, 'protocol': 'tcp'}, {'port': 53, 'protocol': 'udp'}, {'port': 8080, 'protocol': 'tcp'}]"
| matchport guid=550e8400-e29b-41d4-a716-446655440000 invert=t

Uses the invert=t option to output only records not included in the port group.

Specify custom field names

json "[{'dst_port': 443, 'proto': 'tcp'}, {'dst_port': 53, 'proto': 'udp'}]"
| matchport guid=550e8400-e29b-41d4-a716-446655440000 port=dst_port protocol=proto

Specifies the port number field and protocol field names using the port and protocol options.