matchfeed

Checks whether the specified field values of input records are included in threat intelligence feed data, and outputs matched records.

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

matchfeed [name=STR] [type={URL|DOMAIN|EMAIL|IP|REGISTRY|MD5|SHA1|SHA256}] fields=STR [invert=BOOL]

Options

name=STR: Threat intelligence feed identifier. You must specify either name or type.
type={URL|DOMAIN|EMAIL|IP|REGISTRY|MD5|SHA1|SHA256}: Threat intelligence feed type. You must specify either name or type.

URL: URL
DOMAIN: Domain
EMAIL: Email
IP: IP address
REGISTRY: Registry
MD5: MD5 hash
SHA1: SHA1 hash
SHA256: SHA256 hash

fields=STR: List of fields to match against. Separate multiple fields with commas (,). Field values must be of string or IP address type.
invert=BOOL: Inverts the match result. When set to t, outputs records not included in the threat intelligence feed. (Default: f)

Input fields

Field	Type	Required	Description
Fields specified by `fields`	string or IP address	Required	Value to compare against the threat intelligence feed. Fields with null values or values that are not string or IP address type are skipped.

Output fields

When a specific feed is specified using the name option:

Field	Type	Description
`feed_name`	string	Identifier of the matched threat intelligence feed
`feed_invert`	boolean	Whether inversion is enabled
`feed_field`	string	Name of the matched field (output only when `invert=f`)

When a feed type is specified using the type option:

Field	Type	Description
`feed_type`	string	Threat intelligence feed type
`feed_names`	array	List of matched threat intelligence feed identifiers (output only when `invert=f`)
`feed_invert`	boolean	Whether inversion is enabled
`feed_field`	string	Name of the matched field (output only when `invert=f`)

Error codes

Parse errors

Error code	Message	Description
300020	You must specify either the name or type option for the matchfeed command.	Both `name` and `type` options were omitted.
300021	Specify the fields option for the matchfeed command.	The `fields` option was not specified.
300022	Invalid threat intelligence feed identifier.	A non-existent feed identifier was specified for the `name` option.
300023	Invalid threat intelligence feed type. Specify one of: URL, DOMAIN, EMAIL, IP, REGISTRY, MD5, SHA1, SHA256.	An invalid type was specified for the `type` option.
300024	Failed to initialize the threat intelligence feed matcher.	Feed matcher initialization failed.

Runtime errors

None

Description

The matchfeed command compares the values of the fields specified by the fields option against threat intelligence feed data, filtering records based on whether a match is found. Fields are checked in order; when a match is found in the first matching field, the command stops checking and outputs that record.

When name is specified, matching is performed against only that feed. When type is specified, matching is performed against all feeds of the same type. You must specify one of the two options.

When invert=t is specified, only records where no field matched are output after all fields are checked. In this case, the feed_field field is not output.

If a field value is null or is not a string or IP address type, that field is skipped and the next field is checked.

Examples

Match IP addresses against a specific feed name

json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}, {'src_ip': '203.0.113.10'}]"
| matchfeed name=malware_ip fields=src_ip

Filters records with IP addresses included in the malware_ip feed.

Match domains by feed type
```
json "[{'domain': 'example.com'}, {'domain': 'test.org'}]"
| matchfeed type=DOMAIN fields=domain
```
Matches the domain field against all threat intelligence feeds of DOMAIN type.
Match against multiple fields
```
json "[{'src_ip': '192.0.2.1', 'dst_ip': '198.51.100.5'}]"
| matchfeed type=IP fields=src_ip,dst_ip
```
Checks src_ip and dst_ip fields in order and filters records included in IP-type feeds.

Invert the match result

json "[{'src_ip': '192.0.2.1'}, {'src_ip': '198.51.100.5'}]"
| matchfeed name=malware_ip fields=src_ip invert=t

Outputs only records with IP addresses not included in the malware_ip feed.