How to write detection rules in YARA-L for Google Chronicle

At the end of last year I ran a series of post describing the syntax of Sigma rules (used for threat detection).

If you missed any posts in that series, they are available here.

This week I’m going to take a look at Google’s threat detection language, YARA-L, built for their Chronicle product.

YARA-L was named after, and inspired by YARA (invented by VirusTotal, now a Google company) for malware analysis. The L stands for “logs”.

Google describe it as a threat detection language, and not a data query language (shots fired at other SIEM’s).

YARA-L is arguably the most well suited to detection language found natively in a SIEM product. Though with power comes complexity.

In this post I want to jump deeper into YARA-L rules, specifically version 2, to make sense of them.

Rule construction

For YARA-L 2, you must specify variable declarations, definitions, and usages in the following order:

meta
events
match
condition
rule

Breaking each of these down…

1. meta

This part of the rule stores arbitrary key-value pairs of rule details, such as who wrote it, what it detects on, version control, etc.

meta:
  author = "Analyst #2112"
  date = "08/09/2020"
  description = "suspicious logins detected"

2. events

Defines the conditions to filter events and the relationship between events. Here you need to specify the logic of what you want the rule to detect.

Here’s a simple example,

events:
  $udm.metadata.event_type = "USER_LOGIN"

This searches for a user login event and would return the ones it encounters within Chronicle. Simple, but not very useful for hunting.

We can make the events part of the rule useful for later sections of the rule by declaring variables taken from the matching events.

events:
  $udm.metadata.event_type = "USER_LOGIN"
  $udm.principal.user.userid = $user
  $udm.principal.location.city = $city

Note the variables declared using the $ symbol.

Here we’re grabbing the returned userid (mapped as $user) and the login city (mapped as $city).

This section normally includes a significant number of different conditions and variables.

3. match:

The match section is useful when you want to search for events in a specific time period.

match:
    $user over 10m

In this example we take the $user variable declared in the events section.

The match is saying the $user variable should have values that only occur in a defined time period (10 minute time period).

If this doesn’t quite make sense yet, wait until we put the entire rule together and all will become clear.

4. condition

In the condition section, you can specify the match condition over events and variables defined in the events section.

condition:
    #city > 1

In this example condition, a match will only be found if the distinct number of $city values is greater than 1 over a 10 minute period for a user.

5. rule

This is simple. It’s a wrapper for the other content you’ve created, as you’ll see below.

Putting it all together

Taking each of the examples used above we get the following rule…

rule suspicious_logins_detected
{
  meta:
    author = "Analyst 2112"
    date = "08/09/2020"
    description = "suspicious logins detected"
  events:
    $udm.metadata.event_type = "USER_LOGIN"
    $udm.principal.user.userid = $user
    $udm.principal.location.city = $city
  match:
      $user over 10m
  condition:
      #city > 1
}

This rule aims to identify suspicious logins by users attempting access from multiple cities in an impossibly short time window by:

first filtering events by metadata.event_type = "USER_LOGIN"
then defining $user and $city variables from fields in these events
then it looks over a 10 minute time windows for events with each unique $user variable
if in these 10 minute windows more than one city is detected for a unique $user, a detection is triggered