Cannot understand the difference between $event for event fields and $entity for entity fields

[mountaincode2]

I have a query in relation to the following document:

https://cloud.google.com/chronicle/docs/reference/udm-field-list

The docs says the following:

When writing rules for Detect Engine, use the <prefix> pattern $event for Event fields and $entity for Entity fields. For example:

• $event.metadata.event_type
• $event.network.dhcp.opcode
• $event.principal.user.location.city
• $entity.graph.entity.hostname
• $entity.graph.metadata.product_name

Now i can't understand why is `principal.user.location.city` prefixed with `$event`.

`principal` is a noun in UDM. So why is `principal.user.location.city` prefixed with `$event`.

Can you please help me fill the gap in my understanding.

[jstoner · Accepted solution]

In YARA-L every field needs to be mapped. For a rule that only is looking at a single event, this may seem like overkill but as we get into rules that contain multiple events (or entities), we need a way to identify that event1 pertains to process launch events and event2 is network http events and entity1 is a safebrowsing entity and so forth.

The $event or $entity in the example above are referred to as event variables. These are seen all over rules and are sometimes shortened to $e and $u in the documentation. I personally prefer using something more descriptive, ie $process or $network as these event variables can also be seen in the detection and make it simpler to read and see which events pertain to the process portion of a detect versus the network portion, for example. 

Here is a short video I put together on YARA-L variables as well:

https://www.googlecloudcommunity.com/gc/Chronicle-Best-Practices/Getting-to-know-Chronicle-SIEM-YARA...

Hope this helps!

[mountaincode2]

Thank you for pointing me to that excellent post.

A quick follow up. What does the following mean:

"event variables are used to organize like criteria together"

What does it mean to say: organize like criteria together

Is there a different way to say this.

[jstoner]

In the example below, in a single same data set, Microsoft Windows Event Logs. However, there are 2 types of events I am looking for, failed logins and successful logins. The failed logins have their own set of criteria, that is, user_login event type, security_result.action of block and product_event_type of 4625. The success criteria has some similar values and some different values.

However, I am left with a bucket of events that match the fail criteria and a different bucket of events that match the success criteria. By using the event variables of $fail and $success, I can characterize each and then use placeholder variables like the ones seen in line 4 and 5 and 13 and 14 to join. I can also use statements like the one in line 9 to say that the failed events need to occur before the successful events by comparing the timestamps of the success and failed events.

Hope that helps

events:
    $fail.metadata.event_type = "USER_LOGIN"
    $fail.metadata.vendor_name = "Microsoft"
    $fail.principal.hostname = $hostname
    $fail.target.user.userid = $user
    $fail.security_result.action = "BLOCK"
    $fail.metadata.product_event_type = "4625"
   
    $fail.metadata.event_timestamp.seconds < $success.metadata.event_timestamp.seconds
   
    $success.metadata.event_type = "USER_LOGIN"
    $success.metadata.vendor_name = "Microsoft"
    $success.target.user.userid = $user
    $success.principal.hostname = $hostname
    $success.security_result.action = "ALLOW"
    $success.metadata.product_event_type = "4624"

[mountaincode2]

Thank you. The "Getting to Know Chronicle" series is amazing!