Cline rules

1# Style Guide for Community Rules
2 
3Detection rules for Google Security Operations are written in the
4[YARA-L](https://cloud.google.com/chronicle/docs/detection/yara-l-2-0-overview)
5language.
6 
7This style guide establishes baseline standards of quality, completeness,
8readability, and extensibility for community rules in this project. This guide
9also sets an example for what high quality rules look like and what components
10detection engineers should include in their own rules.
11 
12## Characteristics of quality community detection rules
13 
14Detection rules in this project should:
15 
16- Provide value out of the box, even if users must tweak them to provide the
17most value. A rule should solve a real problem, meet a specific use case, or
18address a contemporary threat.
19- Serve as a jumping off point or inspiration for detection engineers to create
20their own detections.
21- Highlight capabilities that exist within Google SecOps's detection engine.
22- Be optimized for performance wherever possible.
23 
24## Rule file format
25 
26Each rule file should have a short, descriptive name and a `.yaral` extension.
27Example: `entra_id_add_user_to_admin_role.yaral`.
28 
29The following license must be included at the beginning of each rule file.
30 
31```
32/*
33 * Copyright 2025 Google LLC
34 *
35 * Licensed under the Apache License, Version 2.0 (the "License");
36 * you may not use this file except in compliance with the License.
37 * You may obtain a copy of the License at
38 *
39 *     https://www.apache.org/licenses/LICENSE-2.0
40 *
41 * Unless required by applicable law or agreed to in writing, software
42 * distributed under the License is distributed on an "AS IS" BASIS,
43 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
44 * See the License for the specific language governing permissions and
45 * limitations under the License.
46 */
47```
48 
49Ensure that there are no tabs or trailing whitespaces in your rule.
50 
51## YARA-L rule sections
52 
53### `meta` section
54 
55Guidance on the `meta` section of a rule.
56 
57#### General information
58 
59All rules should have:
60 
61- An author of `Google Cloud Security` or the name of the original author of the
62rule.
63- A description that explains what behavior the rule detects.
64- A `rule_id` that is unique to the rule. The value for this field must be a
65  UUIDv4 value that is unique to the rule with a prefix of `mr_`
66  (e.g. `mr_069a282b-a605-4572-921e-f466b93d0123`)
67- A `rule_name` that is unique to the rule and provides a human friendly,
68  short description for the rule.
69- A severity defined (`Info`, `Low`, `Medium`, `High`, or `Critical`).
70- A priority defined (`Info`, `Low`, `Medium`, `High`, or `Critical`).
71 
72Values that would be helpful in providing additional context around the rule
73include the following and are considered optional:
74 
75- `platform` - The platform(s) that this rule focuses on.
76  - It is possible to specify multiple platforms. For example, a Windows based
77    EDR event that is correlated with events from Google Cloud.
78  - Not all rules will have this field/value, as some rules can be
79    platform-agnostic.
80  - Example: `platform = "Windows, GCP"`
81 
82- `type` - The rule type. Examples include `alert` or `hunt`.
83  - `alert` is used for higher fidelity rules that are candidates for deployment
84    while `hunt` might cause false positives but provide results that could be
85    used as part of a threat hunt.
86  - Example: `type = "hunt"`
87 
88- `data_source` - What data sources were used for testing the rule, i.e., what
89  logs should the rule run against.
90  - While it may not be possible to validate every data source, by providing
91    representative data source(s), authors can provide some level of
92    understanding on the approach being taken in the rule.
93  - Example: `data_source = "microsoft sysmon, custom misp parser"`
94 
95- `assumptions` - What are the things that the author took into account when
96  writing the rule that someone deploying the rule should be aware of.
97    - Example: `assumption = "While it should work for any EDR systems and
98      ingested threat intel, the metadata.product_name for MISP should be
99      modified or commented out based upon event source."`
100 
101- `reference` - If a website has a write-up on this attack technique or the rule
102  is ported from another platform's reference site, it should be cited here.
103  - Example: `reference = "https://mysource.for.this.rule/if-applicable"`
104 
105- `tags` - Used to denote ways to group rules using specific functionality.
106  Example: `tags = “whois, vt”`. Additional
107  example values include:
108  - `asset enrichment`
109  - `threat indicators`
110  - `asset entity`
111  - `safe browsing`
112  - `user enrichment`
113  - `prevalence`
114  - `resource entity`
115  - `benign binaries`
116  - `vt enrichment`
117  - `first last seen`
118  - `user entity`
119  - `tor`
120  - `geoip enrichment`
121  - `list`
122  - `vt`
123  - `whois`
124  - `rat`
125 
126#### MITRE ATT&CK mapping
127 
128All rules that map to
129[MITRE ATT&CK](https://attack.mitre.org/matrices/enterprise/) should include the
130following fields in the meta section:
131  - Tactic
132  - Technique: Sub-Technique (if applicable)
133 
134Example MITRE ATT&CK mapping in the `meta` section of a rule:
135 
136```
137meta:
138  author = "Google Cloud Security"
139  description = "Detects the use of net use for SMB/Windows admin shares"
140  rule_id = "mr_069a282b-a605-4572-921e-f466b93d0123"
141  rule_name = "net use usage for SMB/Windows admin shares"
142  tactic = "TA0008"
143  technique = "T1021.002"
144  type = "alert"
145  data_source = "microsoft sysmon, microsoft windows events"
146  severity = "Low"
147  priority = "Low"
148```
149 
150### `events` section
151 
152Guidance on the `events` section of a rule.
153 
154#### Variables
155 
156All event variables should be descriptive to ensure readability, preferably not
157`$event` and definitely not `$e1`.
158 
159All placeholder variables should be descriptive enough to understand and if it
160concatenates multiple words together should be separated with underscores, i.e.,
161`$my_variable_for_hostname`.
162 
163- A placeholder like `$hostname` is perfectly fine particularly when joining
164  disparate nouns together.
165- Using the same variable name with a different capitalization should be avoided
166  if possible, i.e., `$Host` and `$host`.
167 
168Joins between events and entities should be represented with a placeholder
169variable in each line where possible to ensure readability and ease of
170understanding.
171 
172Joins on full field names are possible and will work, but using placeholder
173variables is preferred and can be used in outcomes fields as well.
174 
175Additional fields and values that improve the performance of the rules should
176be used whenever possible. Examples of this include:
177 
178- Adding a `<hash> != "hash_value"` to narrow down process launch or file
179  creation events except if the field is being used as a match variable (see
180  the `match` section of this guide below).
181- Using `metadata.entity_type` for all entity based rules.
182- Using `metadata.source_type` for all entity based rules.
183- Using `metadata.event_type` where possible for UDM events.
184 
185### `match` section
186 
187Guidance on the `match` section of a rule.
188 
189Most rules should have a `match` section, so that related alerts are grouped
190together into a single detection.
191 
192Match variables automatically exclude `NULL` values (`""` and `0` for strings
193and integers, respectively), unless the
194[`allow_zero_values`](https://cloud.google.com/chronicle/docs/detection/yara-l-2-0-syntax#options_section_syntax)
195option is set. Unless that option is set, do not add conditions in the events
196section that duplicate this logic. The following is NOT correct:
197 
198```
199events:
200  $e.target.ip = "1.1.1.1"
201  $hostname = $e.principal.hostname
202  $e.principal.hostname != "" // unnecessary
203 
204match:
205  $hostname
206```
207 
208### `outcome` section
209 
210Guidance on the `outcome` section of a rule.
211 
212The `outcome` section can contain up to 20 outcome variables and should be
213populated with the below fields where possible.
214 
215Outcome variables and associated names may find their way into 3rd party
216integrations, so descriptive names including the noun are preferred and should
217be separated with underscores, i.e., `$target_process_command_line`.
218 
219- `risk_score`
220  - In the absence of a specific risk score, applying a value that aligns with
221    the rule's severity (specified in the `meta` section) is reasonable.
222 
223    | severity | risk_score |
224    |----------|------------|
225    | Info     | 10         |
226    | Low      | 35         |
227    | Medium   | 65         |
228    | High     | 85         |
229    | Critical | 95         |
230 
231    - Specific criteria do not need to be applied unless the rule author has
232      something in mind. Organizations have different risk scoring metrics and
233      Google SecOps continues to evolve with the introduction of new
234      capabilities.
235 
236- `event_count` - for single-event variable rules.
237  - Example: `$event_count = count_distinct($e.metadata.id)`
238- Any hardcoded values in the condition section, greater than 1.
239  - Given a condition of `#failed_logons > 100`, define a variable of
240    `$failed_logon_threshold = 100`
241 
242- Consider adding the descriptive fields from the noun families:
243  `principal`, `target`, and `src`.
244  - Within these families, the a subset of the following fields are always a good starting point
245    - hostname
246    - ip
247    - mac
248    - asset.hostname
249    - asset.ip
250    - asset.mac
251    - user.userid
252    - user.windows_sid
253    - user.email_addresses
254    - user.employee_id
255    - process.command_line
256    - process.file.full_path
257    - process.product_specific_process_id
258    - process.parent_process.product_specific_process_id
259    - process.pid
260    - process.file.sha256
261    - process.file.sha1
262    - process.file.md5
263    - file.full_path
264    - file.sha256
265    - file.sha1
266    - file.md5
267    - resource.name
268    - url
269    - artifact.ip
270    - domain.name
271 
272  - The names for these outcome variables should be descriptive. Example:
273  `$impacted_host = array_distinct($event.principal.hostname)` or
274  `$impacted_user = array_distinct($event.principal.user.userid)` or
275 
276- Any additional summary values or fields of interest based upon the rule should
277  also be included in the outcome section.
278 
279## Appendix
280 
281### Example outcome variables for use with the alert graph
282 
283These are based on a limited set of data sources during testing. These serve as
284a reference set of fields that will populate the alert graph for additional
285context based upon the `metadata.event_type` in the rule.
286 
287#### Example outcome variables for event type `NETWORK_CONNECTION`
288 
289```
290$principal_ip = array_distinct($network.principal.ip)
291$target_ip = array_distinct($network.target.ip)
292$principal_process_pid = array_distinct($network.principal.process.pid)
293$principal_process_command_line = array_distinct($network.principal.process.command_line)
294$principal_process_file_sha256 = array_distinct($network.principal.process.file.sha256)
295$principal_process_file_full_path = array_distinct($network.principal.process.file.full_path)
296$principal_process_product_specific_process_id = array_distinct($network.principal.process.product_specific_process_id)
297$principal_process_parent_process_product_specific_process_id = array_distinct($network.principal.process.parent_process.product_specific_process_id)
298$target_process_pid = array_distinct($network.target.process.pid)
299$target_process_command_line = array_distinct($network.target.process.command_line)
300$target_process_file_sha256 = array_distinct($network.target.process.file.sha256)
301$target_process_file_full_path = array_distinct($network.target.process.file.full_path)
302$target_process_product_specific_process_id = array_distinct($network.target.process.product_specific_process_id)
303$target_process_parent_process_product_specific_process_id = array_distinct($network.target.process.parent_process.product_specific_process_id)
304$principal_user_userid = array_distinct($network.principal.user.userid)
305$target_user_userid = array_distinct($network.target.user.userid)
306```
307 
308#### Example outcome variables for event type `NETWORK_HTTP`
309 
310```
311$principal_hostname = array_distinct($network.principal.hostname)
312$target_hostname = array_distinct($network.target.hostname)
313$principal_user_userid = array_distinct($network.principal.user.userid)
314$target_url = array_distinct($network.target.url)
315```
316 
317#### Example outcome variables for event type `USER_LOGIN`
318 
319```
320$principal_hostname = array_distinct($login.principal.hostname)
321$principal_ip = array_distinct($login.principal.ip)
322$target_hostname = array_distinct($login.target.hostname)
323$target_ip = array_distinct($login.target.ip)
324$principal_user_userid = array_distinct($login.principal.user.userid)
325$target_user_userid = array_distinct($login.target.user.userid)
326$principal_resource_name = array_distinct($login.principal.resource.name)
327$target_resource_name = array_distinct($login.target.resource.name)
328$target_url = array_distinct($login.target.url)
329```
330 
331#### Example outcome variables for event type `PROCESS_LAUNCH`
332 
333```
334$principal_hostname = array_distinct($execution.principal.hostname)
335$principal_process_pid = array_distinct($execution.principal.process.pid)
336$principal_process_command_line = array_distinct($execution.principal.process.command_line)
337$principal_process_file_sha256 = array_distinct($execution.principal.process.file.sha256)
338$principal_process_file_full_path = array_distinct($execution.principal.process.file.full_path)
339$principal_process_product_specific_process_id = array_distinct($execution.principal.process.product_specific_process_id)
340$principal_process_parent_process_product_specific_process_id = array_distinct($execution.principal.process.parent_process.product_specific_process_id)
341$target_process_pid = array_distinct($execution.target.process.pid)
342$target_process_command_line = array_distinct($execution.target.process.command_line)
343$target_process_file_sha256 = array_distinct($execution.target.process.file.sha256)
344$target_process_file_full_path = array_distinct($execution.target.process.file.full_path)
345$target_process_product_specific_process_id = array_distinct($execution.target.process.product_specific_process_id)
346$principal_user_userid = array_distinct($execution.principal.user.userid)
347```
348 
349#### Example outcome variables for event type `FILE_CREATION`
350 
351```
352$principal_hostname = array_distinct($execution.principal.hostname)
353$principal_process_pid = array_distinct($execution.principal.process.pid)
354$principal_process_command_line = array_distinct($execution.principal.process.command_line)
355$principal_process_file_sha256 = array_distinct($execution.principal.process.file.sha256)
356$principal_process_file_full_path = array_distinct($execution.principal.process.file.full_path)
357$principal_process_product_specific_process_id = array_distinct($execution.principal.process.product_specific_process_id)
358$principal_process_parent_process_product_specific_process_id = array_distinct($execution.principal.process.parent_process.product_specific_process_id)
359$target_process_pid = array_distinct($execution.target.process.pid)
360$target_process_command_line = array_distinct($execution.target.process.command_line)
361$target_process_file_sha256 = array_distinct($execution.target.process.file.sha256)
362$target_process_file_full_path = array_distinct($execution.target.process.file.full_path)
363$target_process_product_specific_process_id = array_distinct($execution.target.process.product_specific_process_id)
364$principal_user_userid = array_distinct($execution.principal.user.userid)
365$target_file_sha256 = array_distinct($execution.target.file.sha256)
366$target_file_full_path = array_distinct($execution.target.file.full_path)
367```
368 
369#### Example outcome variables for event type `NETWORK_DNS`
370 
371```
372$principal_ip = array_distinct($dns.principal.ip)
373$target_ip = array_distinct($dns.target.ip)
374$principal_process_pid = array_distinct($dns.principal.process.pid)
375$principal_process_file_full_path = array_distinct($dns.principal.process.file.full_path)
376$principal_process_product_specific_process_id = array_distinct($dns.principal.process.product_specific_process_id)
377$principal_user_userid = array_distinct($dns.principal.user.userid)
378$principal_process_command_line = array_distinct($dns.principal.process.command_line)
379$principal_process_file_sha256 = array_distinct($dns.principal.process.file.sha256)
380$principal_process_parent_process_product_specific_process_id = array_distinct($dns.principal.process.parent_process.product_specific_process_id)
381$network_dns_questions_name = array_distinct($dns.network.dns.questions.name)
382$network_dns_answers_data = array_distinct($dns.network.dns.answers.data)
383```
384