Cline rules

1# Overview of the YARA-L 2.0 language
2 
3Supported in:
4 
5Google secops
6[Siem](/chronicle/docs/secops/google-secops-siem-toc)
7 
8YARA-L 2.0 is a computer language used to create rules for searching through your enterprise log data as it is ingested into your Google Security Operations instance. The YARA-L syntax is derived from the YARA language developed by VirusTotal.
9The language works in conjunction with the Google SecOps Detection Engine and enables you to hunt for threats and other events across large volumes of data.
10 
11For more information, see the following:
12 
13* [YARA-L 2.0 language syntax](/chronicle/docs/detection/yara-l-2-0-syntax)
14* [Best practices](/chronicle/docs/detection/yara-l-best-practices)
15 
16**Note:** YARA-L 2.0 is incompatible with previous versions of the YARA-L language. Rules written in older versions of YARA-L will not work with the current version of the Detection Engine and need to be revised to use the new syntax.
17 
18## YARA-L 2.0 example rules
19 
20The following examples show rules written in YARA-L 2.0. Each demonstrates how to correlate events within the rule language.
21 
22### Rules and tuning
23 
24The following rule checks for specific patterns in event data and creates a detection
25if it finds the patterns. This rule includes a variable `$e1` for tracking event
26type and `metadata.event_type` UDM field. The rule checks for specific occurrences
27of regular expression matches with `e1`. When the event `$e1` takes place, a detection is created.
28A `not` condition is included in the rule to exclude certain non-malicious paths.
29You can add `not` conditions to prevent false positives.
30 
31```
32rule suspicious_unusual_location_svchost_execution
33{
34 
35 meta:
36   author = "Google Cloud Security"
37   description = "Windows 'svchost' executed from an unusual location"
38   yara_version = "YL2.0"
39   rule_version = "1.0"
40 
41 events:
42 
43   $e1.metadata.event_type = "PROCESS_LAUNCH"
44   re.regex($e1.principal.process.command_line, `\bsvchost(\.exe)?\b`) nocase
45   not re.regex($e1.principal.process.command_line, `\\Windows\\System32\\`) nocase
46 
47condition:
48 
49   $e1
50}
51 
52 
53```
54 
55### Logins from different cities
56 
57The following rule searches for users that have logged in to your enterprise from two or more cities in less than 5 minutes:
58 
59```
60rule DifferentCityLogin {
61  meta:
62 
63  events:
64    $udm.metadata.event_type = "USER_LOGIN"
65    $udm.principal.user.userid = $user
66    $udm.principal.location.city = $city
67 
68  match:
69    $user over 5m
70 
71  condition:
72    $udm and #city > 1
73}
74 
75```
76 
77**Match variable**: `$user`
78 
79**Event variable**:`$udm`
80 
81**Placeholder variable**: `$city` and `$user`
82 
83The following describes how this rule works:
84 
85* Groups events with username (`$user`) and returns it (`$user`) when a match is found.
86* Timespan is 5 minutes, meaning only events that are less than 5 minutes apart are correlated.
87* Searching for an event group (`$udm`) whose event type is *USER\_LOGIN*.
88* For that event group, the rule calls the user ID as `$user` and the login city as `$city.`
89* Returns a match if the distinct number of `city` values (denoted by `#city`) is greater than 1 in the event group (`$udm`) within the 5 minute time range.
90 
91### Rapid user creation and deletion
92 
93The following rule searches for users that have been created and then deleted within 4 hours:
94 
95```
96rule UserCreationThenDeletion {
97  meta:
98 
99  events:
100    $create.target.user.userid = $user
101    $create.metadata.event_type = "USER_CREATION"
102 
103    $delete.target.user.userid = $user
104    $delete.metadata.event_type = "USER_DELETION"
105 
106    $create.metadata.event_timestamp.seconds <=
107       $delete.metadata.event_timestamp.seconds
108 
109  match:
110    $user over 4h
111 
112  condition:
113    $create and $delete
114}
115 
116```
117 
118**Event variables**:`$create` and `$delete`
119 
120**Match variable**: `$user`
121 
122**Placeholder variable**: N/A
123 
124The following describes how this rule works:
125 
126* Groups events with username (`$user`) and returns it (`$user`) when a match is found.
127* Time window is 4 hours, meaning only events separated by less than 4 hours are correlated.
128* Searches for two event groups (`$create` and `$delete`, where `$create` is equivalent to `#create >= 1`).
129* `$create` corresponds to `USER_CREATION` events and calls the user ID as `$user`.
130* `$user` is used to join the two groups of events together.
131* `$delete` corresponds to `USER_DELETION` events and calls the user ID as `$user`. This rule looks for a match where the user identifier in the two event groups is the same.
132* This rule looks for cases where the event from `$delete` happens later than the event from `$create`, returning a match when discovered.
133 
134### Single event rule
135 
136Single event rules are rules that correlate over a single event. A single event rule can be:
137 
138* Any rule without a match section.
139* Rule with a `match` section and a `condition` section only checking for the existence of 1 event (for example, "$e", "#e > 0", "#e >= 1", "1 <= #e", "0 < #e").
140 
141For example, the following rule searches for a user login event and would return the first one it encounters within the enterprise data stored within your Google SecOps account:
142 
143```
144rule SingleEventRule {
145  meta:
146    author = "noone@altostrat.com"
147 
148  events:
149    $e.metadata.event_type = "USER_LOGIN"
150 
151  condition:
152    $e
153}
154 
155```
156 
157Here is another example of a single event rule with a match section. This rule searches for a user who has logged in at least once in less than 5 minutes. It checks for the simple existence of a user login event.
158 
159```
160rule SingleEventRule {
161  meta:
162    author = "alice@example.com"
163    description = "windowed single event example rule"
164 
165  events:
166    $e.metadata.event_type = "USER_LOGIN"
167    $e.principal.user.userid = $user
168 
169  match:
170    $user over 5m
171 
172  condition:
173    #e > 0
174}
175 
176```
177 
178**Note:** Rules with a `match` section and a `condition` section that includes outcome variables in addition to simple existence on 1 event are classified as [multi-event rules](#multiple_event_rule). In these rules, detection generation logic depends on all events in a match window (for example, many events), rather than any event in a match window (for example, single event). The following example of such rules generates the same detections as the first multi-event rule example in the next section.
179 
180```
181rule MultiEventRule{
182  meta:
183    author = "alice@example.com"
184    description = "Rule with outcome condition and simple existence condition on one event variable"
185 
186  events:
187    $e.metadata.event_type = "USER_LOGIN"
188    $e.principal.user.userid = $user
189 
190  match:
191    $user over 10m
192 
193  outcome:
194    $num_events_in_match_window = count($e.metadata.id)
195 
196  condition:
197    #e > 0 and $num_events_in_match_window >= 10 // Could be rewritten as #e >= 10
198}
199 
200```
201 
202### Multiple event rule
203 
204Use multiple event rules to group many events over a specified time window and try to find correlations between events. A typical multiple event rule will have the following:
205 
206* A `match` section which specifies the time range over which events need to be grouped.
207* A `condition` section specifying what condition should trigger the detection and checking for the existence of multiple events.
208 
209For example, the following rule searches for a user who has logged in at least 10 times in less than 10 minutes:
210 
211```
212rule MultiEventRule {
213  meta:
214    author = "noone@altostrat.com"
215 
216  events:
217    $e.metadata.event_type = "USER_LOGIN"
218    $e.principal.user.userid = $user
219 
220  match:
221    $user over 10m
222 
223  condition:
224    #e >= 10
225}
226 
227```
228 
229### Single event within range of IP addresses
230 
231The following example shows a single event rule searching for a match between two specific users and a specific range of IP addresses:
232 
233```
234rule OrsAndNetworkRange {
235  meta:
236    author = "noone@altostrat.com"
237 
238  events:
239    // Checks CIDR ranges.
240    net.ip_in_range_cidr($e.principal.ip, "203.0.113.0/24")
241 
242    // Detection when the hostname field matches either value using or.
243    $e.principal.hostname = /pbateman/ or $e.principal.hostname = /sspade/
244 
245  condition:
246    $e
247}
248 
249```
250 
251### any and all rule example
252 
253The following rule searches for login events where all source IP addresses do not match an IP address known to be secure within a timespan of 5 minutes.
254 
255```
256rule SuspiciousIPLogins {
257  meta:
258    author = "alice@example.com"
259 
260  events:
261    $e.metadata.event_type = "USER_LOGIN"
262 
263    // Detects if all source IP addresses in an event do not match "100.97.16.0"
264    // For example, if an event has source IP addresses
265    // ["100.97.16.1", "100.97.16.2", "100.97.16.3"],
266    // it will be detected since "100.97.16.1", "100.97.16.2",
267    // and "100.97.16.3" all do not match "100.97.16.0".
268 
269    all $e.principal.ip != "100.97.16.0"
270 
271    // Assigns placeholder variable $ip to the $e.principal.ip repeated field.
272    // There will be one detection per source IP address.
273    // For example, if an event has source IP addresses
274    // ["100.97.16.1", "100.97.16.2", "100.97.16.3"],
275    // there will be one detection per address.
276 
277    $e.principal.ip = $ip
278 
279  match:
280    $ip over 5m
281 
282  condition:
283    $e
284}
285 
286```
287 
288### Regular expressions in a rule
289 
290The following YARA-L 2.0 regular expression example searches for events with emails received from the altostrat.com domain. Since `nocase` has been added to the `$host` variable `regex` comparison and the `regex` function, both these comparisons are case insensitive.
291 
292```
293rule RegexRuleExample {
294  meta:
295    author = "noone@altostrat.com"
296 
297  events:
298    $e.principal.hostname = $host
299    $host = /.*HoSt.*/ nocase
300    re.regex($e.network.email.from, `.*altostrat\.com`) nocase
301 
302  match:
303    $host over 10m
304 
305  condition:
306    #e > 10
307}
308 
309```
310 
311### Composite rule examples
312 
313**Note:** This feature is covered by [Pre-GA Offerings Terms](https://chronicle.security/legal/service-terms/) of the Google Security Operations Service
314Specific Terms. Pre-GA features might have limited support, and changes to pre-GA features might not be compatible with other pre-GA versions.
315For more information, see the [Google SecOps Technical Support Service guidelines](https://chronicle.security/legal/technical-support-services-guidelines/)
316and the [Google SecOps Service Specific Terms](https://chronicle.security/legal/service-terms/).
317 
318Composite detections enhance threat detection by using composite rules.
319These composite rules use detections from other rules as their input. This enables
320the detection of complex threats that individual rules might not detect. For
321more information, see [Overview of composite detections](/chronicle/docs/detection/composite-detections).
322 
323#### Tripwire detections
324 
325Tripwire composite detections are the simplest form of a composite detection
326that operates on fields within detection findings, such as outcome variables or
327rule metadata. They help filter detections for conditions that may indicate
328higher risk, such as an administrator user or a production environment.
329 
330```
331rule composite_admin_detection {
332  meta:
333    rule_name = "Detection with Admin User"
334    author = "Google Cloud Security"
335    description = "Composite rule that looks for any detections where the actor is an admin user"
336    severity = "Medium"
337 
338  events:
339    $rule_name = $d.detection.detection.rule_name
340    $principal_user = $d.detection.detection.outcomes["principal_users"]
341    $principal_user = /admin|root/ nocase
342 
343  match:
344    $principal_user over 1h
345 
346  outcome:
347    $risk_score = 75
348    $upstream_rules = array_distinct($rule_name)
349 
350  condition:
351    $d
352}
353 
354```
355 
356#### Threshold and Aggregation detections
357 
358Aggregation composite detection rules let you group detection findings based
359on shared attributes, such as a hostname or username, and analyze the aggregated
360data. The following are common use cases:
361 
362* Identifying users who generate a high volume of security alerts or aggregated risk.
363* Detecting hosts with unusual activity patterns by aggregating related detections.
364 
365Risk aggregation example:
366 
367```
368rule composite_risk_aggregation {
369  meta:
370    rule_name = "Risk Aggregation Composite"
371    author = "Google Cloud Security"
372    description = "Composite detection that aggregates risk of a user over 48 hours"
373    severity = "High"
374 
375  events:
376    $rule_name = $d.detection.detection.rule_name
377    $principal_user = $d.detection.detection.outcomes["principal_users"]
378    $risk = $d.detection.detection.risk_score
379 
380  match:
381    $principal_user over 48h
382 
383  outcome:
384    $risk_score = 90
385    $cumulative_risk = sum($risk)
386    $principal_users = array_distinct($principal_users)
387    $upstream_rules = array_distinct($rule_name)
388 
389  condition:
390    $d and $cumulative_risk > 500
391}
392 
393```
394 
395Tactic aggregation example:
396 
397```
398rule composite_tactic_aggregation {
399  meta:
400    rule_name = "MITRE Tactic Aggregation Composite"
401    author = "Google Cloud Security"
402    description = "Composite detection that detects if a user has triggered detections over multiple mitre tactics."
403    severity = "Medium"
404 
405  events:
406    $principal_user = $d.detection.detection.outcomes["principal_users"]
407    $tactic = $d.detection.detection.rule_labels["tactic"]
408    $rule_name = $d.detection.detection.rule_name
409 
410  match:
411    $principal_user over 48h
412 
413  outcome:
414    $mitre_tactics_count = count_distinct($tactic)
415    $mitre_tactics = array_distinct($d.detection.rule_labels["tactic"])
416    $risk_score = min(100, (50+15*$mitre_tactics_count))
417    $upstream_rules = array_distinct($rule_name)
418 
419  condition:
420    $d and $mitre_tactics_count > 1
421}
422 
423```
424 
425### Sequential composite detections
426 
427Sequential composite detections identify patterns of related events where the
428sequence of detections is important, such as a brute-force login attempt
429detection, followed by a successful login. These patterns can involve multiple
430base detections or a combination of base detections and events.
431 
432```
433rule composite_bruteforce_login {
434  meta:
435    rule_name = "Bruteforce Login Composite"
436    author = "Google Cloud Security"
437    description = "Detects when an IP address associated with a Workspace brute force attempt successfully logs in"
438    severity = "High"
439 
440  events:
441    $bruteforce_detection.detection.detection.rule_name = /Workspace Anomalous Failed Logins/
442    $bruteforce_ip = $d.detection.detection.outcomes["principal_ips"]
443 
444    $login_event.metadata.product_name = "login"
445    $login_event.metadata.product_event_type = "login_success"
446    $login_event.metadata.vendor_name = "Google Workspace"
447    $login_ip = $login_event.principal.ip
448 
449    // Ensure the brute force detection and successful login occurred from the same IP
450    $login_ip = $bruteforce_ip
451 
452    $target_account = $login_event.target.user.email_addresses
453 
454    // Ensure the brute force detection occurred before the successful login
455    $bruteforce_detection.detection.detection_time.seconds < $login_event.metadata.event_timestamp.seconds
456 
457  match:
458    $bruteforce_ip over 24h
459 
460  outcome:
461    $risk_score = 90
462    $principal_users = array_distinct($target_account)
463 
464  condition:
465    $bruteforce_detection and $login_event
466}
467 
468 
469```
470 
471#### Context-aware detections
472 
473Context-aware composite detections enrich detections with additional context,
474such as IP addresses found in threat feeds.
475 
476```
477rule composite_tor_enrichment {
478  meta:
479    rule_name = "Detection with IP from TOR Feed"
480    author = "Google Cloud Security"
481    description = "Adds additional context from the TOR intel feed to detections"
482    severity = "High"
483 
484  events:
485    $detection_ip = $d.detection.detection.outcomes["principal_ips"]
486    $gcti.graph.metadata.entity_type = "IP_ADDRESS"
487    $gcti.graph.metadata.vendor_name = "Google Cloud Threat Intelligence"
488    $gcti_feed.graph.metadata.source_type = "GLOBAL_CONTEXT"
489    $gcti.graph.metadata.product_name = "GCTI Feed"
490    $gcti.graph.metadata.threat.threat_feed_name = "Tor Exit Nodes"
491 
492    $detection_ip = $gcti.graph.entity.ip
493 
494    $rule_name = $d.detection.detection.rule_name
495    $risk = $d.detection.detection.outcomes["risk_score"]
496 
497  match:
498    $detection_ip, $rule_name over 1h
499 
500  outcome:
501    $risk_score = 80
502    $upstream_rule = array_distinct($rule_name)
503 
504  condition:
505    $d and $gcti
506}
507 
508```
509 
510#### Co-occurrence detections
511 
512Co-occurrence composite detections are a form of aggregation that can detect a
513combination of related events, such as a combination of privilege escalation
514and data exfiltration detections triggered by a user.
515 
516```
517rule composite_privesc_exfil_sequential {
518  meta:
519    rule_name = "Privilege Escalation and Exfiltration Composite"
520    author = "Google Cloud Security"
521    description = "Looks for a detection sequence of privilege escalation followed by exfiltration."
522    severity = "High"
523 
524  events:
525    $privilege_escalation.detection.detection.rule_labels["tactic"] = "TA0004"
526    $exfiltration.detection.detection.rule_labels["tactic"] = "TA0010"
527 
528    $pe_user = $privilege_escalation.detection.detection.outcomes["principal_users"]
529    $ex_user = $exfiltration.detection.detection.outcomes["principal_users"]
530 
531    $pe_user = $ex_user
532 
533  match:
534    $pe_user over 48h
535 
536  outcome:
537    $risk_score = 75
538    $privesc_rules = array_distinct($privilege_escalation.detection.detection.rule_name)
539    $exfil_rules = array_distinct($exfiltration.detection.detection.rule_name)
540 
541  condition:
542    $privilege_escalation and $exfiltration
543}
544 
545```
546 
547### Sliding window rule example
548 
549The following YARA-L 2.0 sliding window example searches for the absence of
550`firewall_2` events after `firewall_1` events. The `after` keyword is used with
551the pivot event variable `$e1` to specify that only 10 minute windows after each
552`firewall_1` event should be checked when correlating events.
553 
554```
555rule SlidingWindowRuleExample {
556  meta:
557    author = "alice@example.com"
558 
559  events:
560    $e1.metadata.product_name = "firewall_1"
561    $e1.principal.hostname = $host
562 
563    $e2.metadata.product_name = "firewall_2"
564    $e2.principal.hostname = $host
565 
566  match:
567    $host over 10m after $e1
568 
569  condition:
570    $e1 and !$e2
571}
572 
573```
574 
575### Zero value exclusion example
576 
577Rules Engine implicitly filters out the zero values for all placeholders
578that are used in the `match` section.
579For more information, see [zero value handling in the `match` section](/chronicle/docs/detection/yara-l-2-0-syntax#zero_value_handling_in_the_match_section).
580This can be disabled by using the `allow_zero_values` option as
581described in [allow\_zero\_values](/chronicle/docs/detection/yara-l-2-0-syntax#allow_zero_values).
582 
583However, for other referenced event fields,
584zero values are not excluded unless you explicitly specify such conditions.
585 
586```
587rule ExcludeZeroValues {
588  meta:
589    author = "alice@example.com"
590 
591  events:
592    $e1.metadata.event_type = "NETWORK_DNS"
593    $e1.principal.hostname = $hostname
594 
595    // $e1.principal.user.userid may be empty string.
596    $e1.principal.user.userid != "Guest"
597 
598    $e2.metadata.event_type = "NETWORK_HTTP"
599    $e2.principal.hostname = $hostname
600 
601    // $e2.target.asset_id cannot be empty string as explicitly specified.
602    $e2.target.asset_id != ""
603 
604  match:
605    // $hostname cannot be empty string. The rule behaves as if the
606    // predicate, `$hostname != ""` was added to the events section, because
607    // `$hostname` is used in the match section.
608    $hostname over 1h
609 
610  condition:
611    $e1 and $e2
612}
613 
614```
615 
616### Rule with `outcome` section example
617 
618You can add the optional `outcome` section in a YARA-L 2.0 rule to extract
619additional information of each detection. In the condition section, you can also specify
620conditionals on outcome variables. You can use the `outcome` section of a detection
621rule to set variables for downstream consumption. For example, you can set a
622severity score based on data from the events being analyzed.
623 
624For more information, see the following:
625 
626* [Outcome section syntax](/chronicle/docs/detection/yara-l-2-0-syntax#outcome_section_syntax)
627* [Outcome conditionals syntax](/chronicle/docs/detection/yara-l-2-0-syntax#outcome_conditionals)
628* [Overview of the `outcome` section](/chronicle/docs/detection/context-aware-analytics#outcome_section)
629 
630#### Multi-event rule with outcome section:
631 
632The following rule looks at two events to get the value of
633`$hostname`. If the value of `$hostname` matches over a 5-minute period,
634then a severity score is applied. When including a time period in the `match` section,
635the rule checks within the specified time period.
636 
637```
638rule OutcomeRuleMultiEvent {
639    meta:
640      author = "Google Cloud Security"
641    events:
642      $u.udm.principal.hostname = $hostname
643      $asset_context.graph.entity.hostname = $hostname
644 
645      $severity = $asset_context.graph.entity.asset.vulnerabilities.severity
646 
647    match:
648      $hostname over 5m
649 
650    outcome:
651      $risk_score =
652        max(
653            100
654          + if($hostname = "my-hostname", 100, 50)
655          + if($severity = "HIGH", 10)
656          + if($severity = "MEDIUM", 5)
657          + if($severity = "LOW", 1)
658        )
659 
660      $asset_id_list =
661        array(
662          if($u.principal.asset_id = "",
663             "Empty asset id",
664             $u.principal.asset_id
665          )
666        )
667 
668      $asset_id_distinct_list = array_distinct($u.principal.asset_id)
669 
670      $asset_id_count = count($u.principal.asset_id)
671 
672      $asset_id_distinct_count = count_distinct($u.principal.asset_id)
673 
674    condition:
675      $u and $asset_context and $risk_score > 50 and not arrays.contains($asset_id_list, "id_1234")
676}
677 
678 
679```
680 
681```
682rule OutcomeRuleMultiEvent {
683    meta:
684      author = "alice@example.com"
685    events:
686      $u.udm.principal.hostname = $hostname
687      $asset_context.graph.entity.hostname = $hostname
688 
689      $severity = $asset_context.graph.entity.asset.vulnerabilities.severity
690 
691    match:
692      $hostname over 5m
693 
694    outcome:
695      $total_network_bytes = sum($u.network.sent_bytes) + sum($u.network.received_bytes)
696 
697      $risk_score = if(total_network_bytes > 1024, 100, 50) + 
698        max(
699          if($severity = "HIGH", 10)
700          + if($severity = "MEDIUM", 5)
701          + if($severity = "LOW", 1)
702        )
703 
704      $asset_id_list =
705        array(
706          if($u.principal.asset_id = "",
707             "Empty asset id",
708             $u.principal.asset_id
709          )
710        )
711 
712      $asset_id_distinct_list = array_distinct($u.principal.asset_id)
713 
714      $asset_id_count = count($u.principal.asset_id)
715 
716      $asset_id_distinct_count = count_distinct($u.principal.asset_id)
717 
718    condition:
719      $u and $asset_context and $risk_score > 50 and not arrays.contains($asset_id_list, "id_1234")
720}
721 
722```
723 
724#### Single-event rule with outcome section:
725 
726```
727rule OutcomeRuleSingleEvent {
728    meta:
729        author = "alice@example.com"
730    events:
731        $u.metadata.event_type = "FILE_COPY"
732        $u.principal.file.size = $file_size
733        $u.principal.hostname = $hostname
734 
735    outcome:
736        $suspicious_host = $hostname
737        $admin_severity = if($u.principal.userid in %admin_users, "SEVERE", "MODERATE")
738        $severity_tag = if($file_size > 1024, $admin_severity, "LOW")
739 
740    condition:
741        $u
742}
743 
744```
745 
746#### Refactoring a multi-event outcome rule into a single-event outcome rule.
747 
748You can use the `outcome` section for both single-event rules (rules without a
749`match` section), and multi-event rules (rules with a `match` section).
750If you previously designed a rule to be multi-event just so you could
751use the outcome section, you can optionally refactor those rules by deleting
752the `match` section to improve performance. Be aware that because your rule no
753longer has a `match` section that applies grouping,
754you might receive more detections. This refactor is only
755possible for rules that use one event variable as shown in the
756following example.
757 
758Multi-event outcome rule which uses only one event variable (a
759good candidate for a refactor):
760 
761```
762rule OutcomeMultiEventPreRefactor {
763    meta:
764      author = "alice@example.com"
765      description = "Outcome refactor rule, before the refactor"
766 
767    events:
768      $u.udm.principal.hostname = $hostname
769 
770    match:
771      $hostname over 5m
772 
773    outcome:
774      $risk_score = max(if($hostname = "my-hostname", 100, 50))
775 
776    condition:
777      $u
778}
779 
780```
781 
782You can refactor the rule by deleting the `match` section. Note that you
783must also remove the aggregate in the `outcome` section since the rule will now be
784single-event. For more information on aggregations, see [outcome aggregations](/chronicle/docs/detection/yara-l-2-0-syntax#aggregations).
785 
786```
787rule OutcomeSingleEventPostRefactor {
788    meta:
789      author = "alice@example.com"
790      description = "Outcome refactor rule, after the refactor"
791 
792    events:
793      $u.udm.principal.hostname = $hostname
794 
795    // We deleted the match section.
796 
797    outcome:
798      // We removed the max() aggregate.
799      $risk_score = if($hostname = "my-hostname", 100, 50)
800 
801    condition:
802      $u
803}
804 
805```
806 
807### Function to placeholder rule example
808 
809You can assign a placeholder variable to the result of a function call and
810can use the placeholder variable in other sections of the rule, such as the
811`match` section, `outcome` section, or `condition` section. See the following example:
812 
813```
814rule FunctionToPlaceholderRule {
815    meta:
816      author = "alice@example.com"
817      description = "Rule that uses function to placeholder assignments"
818 
819    events:
820        $u.metadata.event_type = "EMAIL_TRANSACTION"
821 
822        // Use function-placeholder assignment to extract the
823        // address from an email.
824        // address@website.com -> address
825        $email_to_address_only = re.capture($u.network.email.from , "(.*)@")
826 
827        // Use function-placeholder assignment to normalize an email:
828        // uid@??? -> uid@company.com
829        $email_from_normalized = strings.concat(
830            re.capture($u.network.email.from , "(.*)@"),
831            "@company.com"
832        )
833 
834        // Use function-placeholder assignment to get the day of the week of the event.
835        // 1 = Sunday, 7 = Saturday.
836        $dayofweek = timestamp.get_day_of_week($u.metadata.event_timestamp.seconds)
837 
838    match:
839        // Use placeholder (from function-placeholder assignment) in match section.
840        // Group by the normalized from email, and expose it in the detection.
841        $email_from_normalized over 5m
842 
843    outcome:
844        // Use placeholder (from function-placeholder assignment) in outcome section.
845        // Assign more risk if the event happened on weekend.
846        $risk_score = max(
847            if($dayofweek = 1, 10, 0) +
848            if($dayofweek = 7, 10, 0)
849        )
850 
851    condition:
852        // Use placeholder (from function-placeholder assignment) in condition section.
853        // Match if an email was sent to multiple addresses.
854        #email_to_address_only > 1
855}
856 
857```
858 
859### Outcome conditionals example rule
860 
861In the `condition` section, you can use outcome variables that were defined
862in the `outcome` section. The following example demonstrates how to filter on
863risk scores to reduce noise in detections by using outcome conditionals.
864 
865```
866rule OutcomeConditionalRule {
867    meta:
868        author = "alice@example.com"
869        description = "Rule that uses outcome conditionals"
870 
871    events:
872        $u.metadata.event_type = "FILE_COPY"
873        $u.principal.file.size = $file_size
874        $u.principal.hostname = $hostname
875 
876        // 1 = Sunday, 7 = Saturday.
877        $dayofweek = timestamp.get_day_of_week($u.metadata.collected_timestamp.seconds)
878 
879    outcome:
880        $risk_score =
881            if($file_size > 500*1024*1024, 2) + // Files 500MB are moderately risky
882            if($file_size > 1024*1024*1024, 3) + // Files over 1G get assigned extra risk
883            if($dayofweek=1 or $dayofweek=7, 4) + // Events from the weekend are suspicious
884            if($hostname = /highly-privileged/, 5) // Check for files from highly privileged devices
885 
886    condition:
887        $u and $risk_score >= 10
888}
889 
890 
891```
892 
893Last updated 2025-06-05 UTC.
894 
895