Overview of YARA-L 2.0

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 how YARA-L works and its syntax can be used to express everything from a basic filter query to a query that looks for complex patterns. As your query becomes more complex, you can use the sections in a YARA-L query to support things like aggregated functions and condition logic, and add context through joins, pattern matching, and more.

YARA-L 2.0 syntax overview

When you create a query using YARA-L, you must understand the structure and syntax used for specifying variable declarations, definitions, and usage.

Query structure

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

The following example illustrates the generic structure of a query:

query <query Name>
{
    meta:
    // Stores arbitrary key-value pairs of query 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 query 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 query.
}

As you create queries, Google SecOps performs type checking against your YARA-L syntax and displays the errors to help you revise the query 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"

In this example query, 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:
   detection_window=2d
}

The query rule is defined as follows:

• The meta section defines the query author (Security team), description (Detects multiple failed logins for a user from a new, never-before-seen IP address within 10 minutes.), and severity (High).
• The events section defines the events that must be tracked: user logins, failed user logins (event variables), and links to userid and ip match variables (placeholder variables).
• The outcome section defines the calculations to perform on the event and placeholder variables: count the failed logins, count the distinct IPs, time the 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 failed logins in a new location.
• The options section specifies when the query first runs: it looks back two days.

What's next

• Meta section syntax
• Events section syntax
• Match section syntax
• 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.