THREAT-395 Correlation Rule Style Guide in repo - updated

CORRELATION_RULES_STYLE_GUIDE.md → style_guides/CORRELATION_RULES_STYLE_GUIDE.md

@@ -1,39 +1,40 @@
-# panther-analysis Correlation Rule (CR) Style Guide and Best Practices
+# panther-analysis Correlation Rule Style Guide and Best Practices
 
-This style guide highlights essential best practices for writing correlation rules. For a more detailed guide, visit [Correlation Rules](https://docs.panther.com/detections/correlation-rules) in the Panther documentation.
+This style guide highlights essential best practices for writing correlation rules (CRs). For a more detailed guide, visit [Correlation Rules](https://docs.panther.com/detections/correlation-rules) in the Panther documentation.
+This guide provides specialized guidelines on writing CRs, which build upon the general detection writing best practices outlined in [STYLE_GUIDE](https://github.com/panther-labs/panther-analysis/style_guides/STYLE_GUIDE.md)
 
-## General advises
+## General guidelines
 
-- Transition names in rule IDs, and transition IDs should be all caps.
+- In a rule ID or transition ID, when describing a transition, put that portion of the ID in all-caps
     - e.g. `"GitHub Advanced Security Change NOT FOLLOWED BY repo archived"`
-- Boilerplate comments from the CR template in the UI should be removed before committing to PA.
+- Boilerplate comments from the CR template in the UI should be removed before committing to PA
     - e.g. remove `# Create a list of rules to correlate`
-- Sequence, Group, and Transition IDs should have meaningful names.
+- Sequence, group, and transition IDs should have meaningful names
     - e.g. `- ID: GHASChange` instead of `- ID: TR.1`
-  - Check for Signal rules that already exist.
+- Check for Signal rules that already exist
     - e.g. we do not want duplicates of `AWS Console Login` rules for every CR that relies on that signal
     - for the guide on Signal rules, please visit [How to create a rule that only produces signals](https://docs.panther.com/detections/correlation-rules/signals#signal-use-cases:~:text=Data%20Explorer.-,How%20to%20create%20a%20rule%20that%20only%20produces%20signals,-To%20create%20a)
-- Correlation rules go in `correlation_rules` directory, sub-rules and signals go in the appropriate logtype directory
+- Correlation rules go in `correlation_rules` directory, subrules and signals go in the appropriate logtype directory
 
 ## Correlation rule fields
 
 ### MinMatchCount
 
-`MinMatchCount: 1` is the default value, this can be omitted.
+- If you are setting `MinMatchCount` to `1`, you can omit it completely, as `1` is the default value.
 
 ### LookbackWindowMinutes
 
-- `LookbackWindowMinutes: 15` is the default value, but this feels valuable to keep.
-- `LookbackWindowMinutes` should be *at least* 1.5x `RateMinutes`.
+- For ease of understanding, it's valuable to include `LookbackWindowMinutes` even if you are setting it to `15`, which is the default value.
+- `LookbackWindowMinutes` should be *at least* 1.5x `RateMinutes`
 
 ### WithinTimeFrameMinutes
 
-- `WithinTimeFrameMinutes` is not required and defaults to `LookbackWindowMinutes`.
-- Omit `WithinTimeFrameMinutes` in Sequences with only 2 rules
+- `WithinTimeFrameMinutes` is not required and defaults to `LookbackWindowMinutes`
+- Omit `WithinTimeFrameMinutes` in sequences with only two rules
 
 ### Match On
 
-- `Match On` fields are not required to be `p_` fields. Especially for CRs where each subrule is for the same LogType, use the regular field instead of the alert context field.
+- `Match On` fields are not required to be `p_` fields. Especially for CRs where each subrule is for the same LogType, use the regular field instead of the alert context field
     - e.g. `- On: repo` instead of `- On: p_alert_context.repo`
 - You cannot match on fields that are JSON objects
   - For rules that span multiple LogTypes, where fields must be transformed, add the transformed fields to `p_alert_context`
@@ -57,14 +58,12 @@ This style guide highlights essential best practices for writing correlation rul
 
 ### Testing
 
-You must run `pat validate` against a live Panther instance to test, `pat test` is not sufficient.
+To test your correlation rules before uploading them, run `pat validate` against a live Panther instance. Running `pat test` is not sufficient.
 
 ### Placing CRs in packs
 
-- If a CR only references 1 LogType it can go in that LogType’s pack
+- If a CR only references one LogType store it in that LogType’s pack
     - If a CR spans multiple LogTypes, put it in the multi-logtype pack
-        - Guidance for multi-logtype pack is do not enable the pack, just enable the individual detections you have logs for
-    - A pack with CRs should also contain the sub-rules referenced by those CRs
-        - AND any globals, data models, etc. that the sub-rules reference
-        - can the pack-checker be updated to check for these dependencies?
-
+        - Customers are advised not to enable multi-LogType packs, and to instead enable the individual detections within them that they have log sources set up for
+    - A pack with CRs should also contain the subrules referenced by those CRs
+        - AND any globals, data models, etc. that the subrules reference

STYLE_GUIDE.md → style_guides/STYLE_GUIDE.md

@@ -1,6 +1,7 @@
 # panther-analysis Style Guide
 
 This style guide highlights essential best practices for writing python rules and alert metadata. For a more detailed guide, visit [Writing Python Detections](https://docs.panther.com/detections/rules/python) in the Panther documentation.
+For specialized guidelines on writing correlation rules, see [CORRELATION_RULES_STYLE_GUIDE](https://github.com/panther-labs/panther-analysis/blob/style_guides/CORRELATION_RULES_STYLE_GUIDE.md)
 
 ## Metadata best practices