Match section syntax

The match section provides the necessary parameters to correlate multiple related events into a single detection. It is required only for rules that link two or more distinct events. Use it to define the criteria for this correlation by specifying the following:

• Grouping fields (Keys): The specific fields from the events (defined in the events section) that must share the same value for the events to be logically linked.

• Time constraint: The continuous time window within which the related events must occur to constitute a single, complete match. This is only required for Rules and is not needed for Search and Dashboards.

Define match section

Rules require match variables to be placeholders defined in the event section. You can also specify event fields in Search and Dashboards.

Use the placeholder variables defined in the events section to specify the time window within which events need to occur. Any matching events that occur outside of the specified time window are ignored for that particular detection group.

Use the over keyword and syntax <number><m/h/d> (where m/h/d is minutes, hours, and days) to specify the time window. You can specify a minimum of one minute and a maximum of 48 hours.

This example rule detects failed logins that occur within a 10-minute window. Correlating multiple failed logins over a short period often indicates a brute-force or unauthorized access attempt.

rule failed_logins
{
 meta:
 author = "Security Team"
 description = "Detects multiple failed user logins within 10-minute windows."
 severity = "HIGH"
 events:
 $e.metadata.event_type = "USER_LOGIN"
 $e.security_result.action = "FAIL"
 $user = $e.target.user.userid
 match:
 $user over 10m
 condition:
 #e >= 5
}

The match section finds users with a failed login in a new location over a 10-minute interval:

match:
 $user over 10m

Zero values in match section

Google SecOps implicitly filters out zero values for all placeholders that are used in the match section ("" for string, 0 for numbers, false for booleans, the value in position 0 for enumerated types).

rule ZeroValuePlaceholderExample {
 meta:
 events:
 // Because $host is used in the match section, the query behaves
 // as if the following predicate was added to the events section:
 // $host != ""
 $host = $e.principal.hostname
 // Because $otherPlaceholder was not used in the match,
 // there is no implicit filtering of zero values for $otherPlaceholder.
 $otherPlaceholder = $e.principal.ip
 match:
 $host over 5m
 condition:
 $e
}

However, if a placeholder is assigned to a function, queries don't implicitly filter out the zero values of placeholders that are used in the match section.

To disable the implicit filtering of zero values, you can use the allow_zero_values option in the options section. The allow_zero_values option is only available in Rules.

rule ZeroValueFunctionPlaceholder {
 meta:
 events:
 // Even though $ph is used in the match section, there is no
 // implicit filtering of zero values for $ph, because $ph is assigned to a function.
 $ph = re.capture($e.principal.hostname, "some-regex")
 match:
 $ph over 5m
 condition:
 $e
}

Supported time windows

You can group event fields and placeholders in the match section by a specified time granularity using one of the following supported windows.

• Hop windows (overlapping windows)
• Tumbling windows (non-overlapping windows)
• Sliding windows (windows generated by pivots)

Hop windows

A hop window is a multi-event query type that groups events matching a query's criteria within a specified timeframe, irrespective of the order in which they occur. By default, YARA-L queries with a match section use hop windows to correlate multiple events over time. The time range of the query's execution is divided into a set of overlapping hop windows, each with the duration specified in the match section. Events are then correlated within each hop window.

For example, for a query that is run over the time range [1:00, 2:00], with a match section over 30m, a possible set of overlapping hop windows that could be generated is [1:00, 1:30], [1:03, 1:33] and [1:06, 1:36]. These windows are used to correlate multiple events.

Tumbling windows

A tumbling window segments a stream of data into fixed-size, non-overlapping, and continuous time intervals. Each data event is assigned to only one, window. This is in contrast to a sliding or hop window, which can have overlapping time intervals.

For example, with a 30-minute tumbling window, events that occur between 1:00:00 and 1:29:59 are processed together. Then, the next set of events, from 1:30:00 to 1:59:59, are processed separately.

Sliding windows

When you need to search for events that occur in a specific, relative order (for example, e1occurs up to two minutes after e2), sliding windows are highly effective. Sliding windows are generated when a time constraint begins or ends with a specified pivot event variable. This dynamically tracks event sequence and timing relative to that specific pivot event variable.

Events are then correlated within each sliding window. This makes it possible to search for events that happen in a specific order (for example, e1 happens within 2 minutes of e2). An occurrence of event e1 and an occurrence of event e2 are correlated if event e1 occurs within the sliding window duration after event e2.

• Sliding windows are based on the pivot event variable (pivot-event-var).
• Use the before keyword to generate sliding windows that end with each occurrence of the pivot event.
• Use the after keyword to generate sliding windows that begin with each occurrence of the pivot event.

Specify sliding windows in the match section of a query as follows:

<match-var-1>, <match-var-2>, ... over <duration> before|after <pivot-event-var>

The following examples show valid sliding windows:

$var1, $var2 over 5m after $e1

$user over 1h before $e2

Notes:

• Additional Sliding window example.

• Using sliding windows instead of hop windows has been known to result in slower performance. We recommend using sliding windows only for specific cases, such as when event order is absolutely necessary or when searching for the non-existence of events.

• Because sliding windows are designed to detect multiple events, we recommend that you not use sliding windows for single-event queries. Instead, use one of the following workarounds:

  • Convert the query to use multiple event variables, and update the condition section if the query requires more than one occurrence of the event.
  • Optionally, consider adding timestamp filters instead of using a sliding window. For example: $permission_change.metadata.event_timestamp.seconds < $file_creation.metadata.event_timestamp.seconds
  • Remove the sliding window.

What's next

• Outcome section syntax
• Condition section syntax
• Options section syntax

Additional information

• Expressions, operators, and constructs used in YARA-L 2.0
• Functions in YARA-L 2.0
• Build composite detection rules
• Examples: YARA-L 2.0 queries

Need more help? Get answers from Community members and Google SecOps professionals.