Options section syntax

Supported in:

The options section of a YARA-L query lets you configure the query behavior in rules, such as enabling or disabling live detection and alerting, and controlling the frequency of query execution.

In this 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

  outcome:
   $failed_login_count = count($e)
   $unique_ips = count_distinct($ip)
   $first_fail_time = min($e.metadata.event_timestamp)

  match:
   $user over 10m

  condition:
   #e >= 5

  options:
    allow_zero_values = true
}

The options section specifies that zero values can also be triggered on. In this example, it looks back 2 days:

condition:
   #e >= 5

Define options section

You can specify options using the syntax key = value, where key must be a predefined option name and value must be a valid value for the option:

rule RuleOptionsExample {
  // Other query sections

  options:
    allow_zero_values = true
}

Valid options values

The following values for options are valid:

allow_zero_values option

The valid values for allow_zero_values option are true and false, which determine if the option is enabled or not. The default value is false. The allow_zero_values option is disabled if it is not specified in the query.

To enable the allow_zero_values setting, add the following to the options section of your query: allow_zero_values = true.

This prevents the query from implicitly filtering out the zero values of placeholders that are used in the match section, as described in Zero values in match section.

suppression_window option

The suppression_window option lets you control how often a query triggers a detection. It prevents the same query from generating multiple detections within a specified time window, even if the query's conditions are met multiple times.

Suppression windowing uses a tumbling window approach, which suppresses duplicates over a fixed-size, non-overlapping window.

You can optionally provide a suppression_key to further refine which instances of the query are suppressed within the suppression window. If not specified, all instances of the query are suppressed. This key is defined as an outcome variable.

The default value of suppression_window is 0; that is, the suppression window is disabled by default. This option only works for single event queries that don't have a match section.

Example: suppression window option

In the following example, suppression_window is set to 5m and suppression_key is set to the $hostname variable. After the query triggers a detection for $hostname, any further detections for $hostname are suppressed for the next five minutes. However, if the query triggers on an event with a different hostname, a detection is created.

rule SuppressionWindowExample {
  // Other rule sections

  outcome:
    $suppression_key = $hostname

  options:
    suppression_window = 5m
}

Additional information

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