matchsig

Checks whether the string value of a field is included in the specified pattern group, and filters records based on the match result.

Command properties

Syntax

In the syntax above, name is available starting with 4.0.2609.0.

Options

guid=STR

GUID of the pattern group to use for matching. In the 5.0 series (through 5.0.2605.2), this is the only way to specify the target. In the 4.0 series (4.0.2609.0 and later), this option cannot be used together with name, and you must specify either guid or name.

name=STR

Name of the pattern group to use for matching (cannot be used together with guid). You must specify either the guid or name option. This option is available starting with 4.0.2609.0.

field=STR

Name of the string field to match against the pattern group.

invert=BOOL

When set to t, outputs only records that do not match the pattern group. (Default: f)

verify=BOOL

When set to f, skips pattern group validation at the parse stage. (Default: t)

Input fields

Output fields

The fields of the input record are passed through unchanged. The following field is added to records where the pattern matches.

If invert=t is specified, the output records are the non-matching ones, so this field is not added.

Error codes

Parse errors

Runtime errors

Description

The matchsig command checks whether the string value of the specified field in input records matches the patterns defined in the pattern group. Only matching records are output. When invert=t is specified, only non-matching records are output.

Use the guid option to specify the pattern group to use for matching. In the 4.0 series (4.0.2609.0 and later), you can also use the name option; the command looks up the group by that name to resolve its GUID, and specifying both guid and name, or omitting both, causes an error, as does specifying a name that does not exist or that matches more than one group.

If the field value is null, the record is treated as non-matching. Non-null values are converted to strings before pattern matching.

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

Examples

1. Filter using a pattern group

   json "[{'line': 'GET /login HTTP/1.1'}, {'line': 'POST /api/data HTTP/1.1'}, {'line': 'hello world'}]"
   | matchsig guid=550e8400-e29b-41d4-a716-446655440000 field=line
   

   Outputs only records where the line field value matches the specified pattern group.

2. Extract records not matching a pattern group

   json "[{'line': 'GET /login HTTP/1.1'}, {'line': 'POST /api/data HTTP/1.1'}, {'line': 'hello world'}]"
   | matchsig guid=550e8400-e29b-41d4-a716-446655440000 field=line invert=t
   

   Uses the invert=t option to output only records that do not match the pattern group.

3. Specifying a pattern group by name (4.0 series, 4.0.2609.0 and later)

   table limit=1000 WEB_APACHE_SAMPLE
   | matchsig name=sql_injection field=uri
   

   Matches using a pattern group specified by name instead of GUID.

Change history