Match section syntax

Supported in:

Google secops SIEM

The match section is optional in a YARA-L query and it's where you define how related events are grouped. Within this section, you specify:

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 time window within which related events must occur to constitute a single, complete match.

Define match section

Use match variables defined in the events section to specify the time duration within which events need to occur to be considered part of the same group in the match section. Events outside the time duration are ignored.

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

In this example query rule, we want to find failed logins from a new location:

rule failed_logins_from_new_location
{
  meta:
   author = "Security Team"
   description = "Detects multiple failed logins for a user from a new, never-before-seen IP address within 10 minutes."
   severity = "HIGH"

  events:
   $e.metadata.event_type = "USER_LOGIN"
   $e.security_result.action = "FAIL"
   $user = $e.target.user.userid
   $ip = $e.principal.ip

  match:
   $user over 10m
}

The match section defines what the output should match. In this case, it matches users with a failed login in a new location that occurs in a 10 minutes time period:

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).

Example: filter out zero values

The following example illustrates queries that filter out the zero values.

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.

Example: allow zero values

The following example illustrates queries that don't implicitly filter out the zero values of placeholders that are used in the match section:

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 one, and only one, window. This is in contrast to a sliding or hopping 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

If you want to search for events that occcur in a specific order (for example, e1 occurs up to 2 minutes after e2), using sliding windows may be more effective. Sliding windows are generated when beginning or ending with a specified 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

Additional information

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