Overview of YARA-L 2.0

Supported in:

YARA-L 2.0 is a specialized language in Google Security Operations that operates on enterprise log data to enable security professionals to explore that data, investigate threats, and build detection rules.

This document explains YARA-L and its syntax, showing how you can use it to express everything from a basic filter query to a rule that looks for complex patterns. Use the sections in a YARA-L query to support aggregated functions, condition logic, and add context through joins, pattern matching, and more.

YARA-L 2.0 syntax overview

To create a YARA-L rule or query, we recommend that you familiarize yourself with and understand the structure and syntax for specifying variable declarations, definitions, and usage.

Rule structure

YARA-L rules contain the following sections and must be specified in the following order:

Order Section Rules Search/Dashboards Description
1 meta Required N/A Describes the rule, can include values such as author, severity, description, and priority. See Meta section syntax.
2 events Required Required Defines how to filter and join events. See Events section syntax.
3 match Optional Optional Specifies which fields to group by when aggregating results. See Match section syntax.

Note: If you exclude a match section, the rule can match against a single event.
4 outcome Optional Optional Defines what data to output when a rule is run or when a rule is triggered. See Outcome section syntax.
5 condition Required Optional Contains logic that determines if a rule is triggered. See Condition section syntax.
6 options Optional Optional Allows enabling or disabling specific rule behavior. See Options section syntax.

The following example illustrates the generic structure of a rule:

rule <rule name>
{
    meta:
    // Stores arbitrary key-value pairs of the rule details, such as who wrote
    // it, what it detects on, version control, etc.

  events:
    // Defines which events to filter and the relationship between events.

  match:
    // Values to return when matches are found.

  outcome:
    // Define the output of each rule and security alert.

  condition:
    // Condition to check events and the variables used to find matches.

  options:
    // Options to turn on or off while executing this rule. The `options` syntax is only valid for rules.
}

As you create rules, Google SecOps performs type checking against your YARA-L syntax and displays the errors to help you revise the rule so that it functions correctly. The following examples show the errors that are presented when invalid syntax is used:

// $e.target.port is of type integer which cannot be compared to a string.
$e.target.port = "80"

// "LOGIN" is not a valid event_type enum value.
$e.metadata.event_type = "LOGIN"

This example rule finds 5 consecutive failed logins per user within 10 minute windows.

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

  outcome:
   $failed_login_count = count($e.metadata.id)
   $first_fail_time = min($e.metadata.event_timestamp.seconds)

  condition:
    #e >= 5
}

The rule is defined as follows:

  • The meta section defines the rule author (Security team), description (Detects multiple failed user logins within 10-minute windows.), and severity (High).

Detects multiple failed user logins within 10-minute windows

  • The events section defines the events that must be tracked: user logins, failed user logins (event variables), and links to the user match variable (placeholder variables).

  • The outcome section defines the calculations to perform on the event and placeholder variables: count the failed logins and the time the first failure occurred.

  • The match section defines the variable to group the events by ($user) and the time period (10m) over which those events must occur to be considered a match.

  • The condition section specifies to only return users that have over five or more failed logins.

What's next

Additional information

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