Merge pull request #211157 from yelevin/yelevin/advanced-conditions

Advanced conditions for automation rules

Author: JamesJBarnett

articles/sentinel/TOC.yml

@@ -386,6 +386,8 @@
     items:
     - name: Create automation rules
       href: create-manage-use-automation-rules.md
+    - name: Add advanced conditions to automation rules
+      href: add-advanced-conditions-to-automation-rules.md
     - name: Authenticate playbooks to Microsoft Sentinel
       href: authenticate-playbooks-to-sentinel.md
     - name: Use triggers and actions in playbooks

articles/sentinel/add-advanced-conditions-to-automation-rules.md

@@ -0,0 +1,131 @@
+---
+title: Add advanced conditions to Microsoft Sentinel automation rules
+description: This article explains how to add complex, advanced "Or" conditions to automation rules in Microsoft Sentinel, for more effective triage of incidents.
+author: yelevin
+ms.topic: how-to
+ms.date: 09/13/2022
+ms.author: yelevin
+---
+
+# Add advanced conditions to Microsoft Sentinel automation rules
+
+> [!IMPORTANT]
+>
+> The advanced conditions capability for automation rules is currently in **PREVIEW**. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+
+This article explains how to add advanced "Or" conditions to automation rules in Microsoft Sentinel, for more effective triage of incidents.
+
+Add "Or" conditions in the form of *condition groups* in the Conditions section of your automation rule.
+
+Condition groups can contain two levels of conditions:
+
+- [**Simple**](#example-1-simple-conditions): At least two conditions, each separated by an `OR` operator: 
+
+    - **A `OR` B**
+    - **A `OR` B `OR` C** ([See Example 1B below](#example-1b-add-more-or-conditions).)
+    - and so on.
+
+- [**Compound**](#example-2-compound-conditions): More than two conditions, with at least two conditions on at least one side of an `OR` operator:
+
+    - **(A `and` B) `OR` C**
+    - **(A `and` B) `OR` (C `and` D)**
+    - **(A `and` B) `OR` (C `and` D `and` E)**
+    - **(A `and` B) `OR` (C `and` D) `OR` (E `and` F)**
+    - and so on.
+
+You can see that this capability affords you great power and flexibility in determining when rules will run. It can also greatly increase your efficiency by enabling you to combine many old automation rules into one new rule.
+
+## Add a condition group
+
+Since condition groups offer a lot more power and flexibility in creating automation rules, the best way to explain how to do this is by presenting some examples.
+
+Let's create a rule that will change the severity of an incoming incident from whatever it is to High, assuming it meets the conditions we'll set.
+
+1. From the **Automation** page, select **Create > Automation rule** from the button bar at the top.
+
+    See the [general instructions for creating an automation rule](create-manage-use-automation-rules.md) for details.
+
+1. Give the rule a name: "Triage: Change Severity to High"
+
+1. Select the trigger **When incident is created**.
+
+1. Under **Conditions**, leave the **Analytics rule name** condition as is. We'll add more conditions below.
+
+1. Under **Actions**, select **Change severity** from the drop-down list.
+
+1. Select **High** from the drop-down list that appears below **Change severity**.
+
+:::image type="content" source="media/add-advanced-conditions-to-automation-rules/create-automation-rule-no-conditions.png" alt-text="Screenshot of creating new automation rule without adding conditions.":::
+
+## Example 1: simple conditions
+
+In this first example, we'll create a simple condition group: If either condition A **or** condition B is true, the rule will run and the incident's severity will be set to *High*.
+
+1. Select the **+ Add** expander and choose **Condition group (Or) (Preview)** from the drop-down list.
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/add-condition-group.png" alt-text="Screenshot of adding a condition group to an automation rule's condition set.":::
+
+1. See that two sets of condition fields are displayed, separated by an `OR` operator. These are the "A" and "B" conditions we mentioned above: If A or B is true, the rule will run.  
+    (Don't be confused by all the different layers of "Add" links - these will all be explained.)
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/empty-condition-group.png" alt-text="Screenshot of empty condition group fields.":::
+
+1. Let's decide what these conditions will be. That is, what two *different* conditions will cause the incident severity to be changed to *High*? Let's suggest the following:
+
+    - If the incident's associated MITRE ATT&CK **Tactics** include any of the four we've selected from the drop-down (see the image below), the severity should be raised to High.
+
+    - If the incident contains a **Host name** entity named "SUPER_SECURE_STATION", the severity should be raised to High.
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/add-simple-or-condition.png" alt-text="Screenshot of adding simple OR conditions to an automation rule.":::
+
+    As long as at least ONE of these conditions is true, the actions we define in the rule will run, changing the severity of the incident to High. 
+
+### Example 1A: Add an OR value within a single condition
+
+Let's say we have not one, but two super-sensitive workstations whose incidents we want to make high-severity.
+We can add another value to an existing condition (for any conditions based on entity properties) by selecting the dice icon to the right of the existing value and adding the new value below.
+
+:::image type="content" source="media/add-advanced-conditions-to-automation-rules/add-value-to-condition.png" alt-text="Screenshot of adding more values to a single condition.":::
+
+### Example 1B: Add more OR conditions
+
+Let's say we want to have this rule run if one of THREE (or more) conditions is true. If A *or* B *or* C is true, the rule will run.
+
+1. Remember all those "Add" links? To add another OR condition, select the **+ Add** connected by a line to the `OR` operator.
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/add-another-or-condition.png" alt-text="Screenshot of adding another OR condition to an automation rule.":::
+
+1. Now, fill in the parameters and values of this condition the same way you did the first two.
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/added-another-or-condition.png" alt-text="Screenshot of another OR condition added to an automation rule.":::
+
+## Example 2: compound conditions
+
+Now we decide we're going to be a little more picky. We want to add more conditions to each side of our original OR condition. That is, we want the rule to run if A *and* B are true, *OR* if C *and* D are true.
+
+1. To add a condition to one side of an OR condition group, select the **+ Add** link immediately below the existing condition, on the same side of the `OR` operator (in the same blue-shaded area) to which you want to add the new condition.
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/add-a-compound-condition.png" alt-text="Screenshot of adding a compound condition to an automation rule.":::
+
+    You'll see a new row added where the **+ Add** link was, separated by an `AND` operator. 
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/empty-new-condition.png" alt-text="Screenshot of empty new condition row in automation rules.":::
+
+1. Fill in the parameters and values of this condition the same way you did the others.
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/fill-in-new-condition.png" alt-text="Screenshot of new condition fields to fill in to add to automation rules.":::
+
+1. Repeat the previous two steps to add an AND condition to the other side of the OR condition group.
+
+    :::image type="content" source="media/add-advanced-conditions-to-automation-rules/add-compound-conditions.png" alt-text="Screenshot of adding multiple compound conditions to an automation rule.":::
+
+That's it! You can use what you've learned here to add more conditions and condition groups, using different combinations of `AND` and `OR` operators, to create powerful, flexible, and efficient automation rules to really help your SOC run smoothly and lower your response and resolution times.
+
+## Next steps
+
+In this document, you learned how to add condition groups using `OR` operators to automation rules.
+
+- For instructions on creating basic automation rules, see [Create and use Microsoft Sentinel automation rules to manage response](create-manage-use-automation-rules.md).
+- To learn more about automation rules, see [Automate incident handling in Microsoft Sentinel with automation rules](automate-incident-handling-with-automation-rules.md)
+- To learn more about advanced automation options, see [Automate threat response with playbooks in Microsoft Sentinel](automate-responses-with-playbooks.md).
+- For help with implementing automation rules and playbooks, see [Tutorial: Use playbooks to automate threat responses in Microsoft Sentinel](tutorial-respond-threats-playbook.md).

articles/sentinel/create-manage-use-automation-rules.md

@@ -1,15 +1,19 @@
 ---
-title: Create and use Microsoft Sentinel automation rules to manage response | Microsoft Docs
+title: Create and use Microsoft Sentinel automation rules to manage response
 description: This article explains how to create and use automation rules in Microsoft Sentinel to manage and handle incidents, in order to maximize your SOC's efficiency and effectiveness in response to security threats.
 author: yelevin
 ms.topic: how-to
-ms.date: 05/23/2022
+ms.date: 09/13/2022
 ms.author: yelevin
 ---
 
 # Create and use Microsoft Sentinel automation rules to manage response
 
-[!INCLUDE [Banner for top of topics](./includes/banner.md)]
+> [!IMPORTANT]
+>
+> Some features of automation rules are currently in **PREVIEW**. See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+>
+> Features in preview will be so indicated when they are mentioned throughout this article.
 
 This article explains how to create and use automation rules in Microsoft Sentinel to manage and orchestrate threat response, in order to maximize your SOC's efficiency and effectiveness.
 
@@ -70,7 +74,16 @@ From the **Trigger** drop-down, select **When incident is created**, **When inci
 
 ### Add conditions (incidents only)
 
-Add any other conditions you want this automation rule's activation to depend on. Select **+ Add condition** and choose conditions from the drop-down list. The list of conditions is populated by incident property and [entity property](entities-reference.md) fields.
+Add any other conditions you want this automation rule's activation to depend on. You now have two ways to add conditions:
+
+- **AND conditions**: individual conditions that will be evaluated as a group. The rule will execute if *all* the conditions of this type are met. This type of condition will be explained below.
+
+- **OR conditions** (also known as *condition groups*, **now in Preview**): groups of conditions, each of which will be evaluated independently. The rule will execute if one or more groups of conditions are true. To learn how to work with these complex types of conditions, see [Add advanced conditions to automation rules](add-advanced-conditions-to-automation-rules.md).
+
+Select the **+ Add** expander and choose **Condition (And)** from the drop-down list. The list of conditions is populated by incident property and [entity property](entities-reference.md) fields.
+
+:::image type="content" source="media/create-manage-use-automation-rules/add-condition-to-rule.png" alt-text="Screenshot of conditions section of automation rule wizard.":::
+:::image type="content" source="media/create-manage-use-automation-rules/condition-groups.png" alt-text="Screenshot of menu with types of conditions to add to automation rules.":::
 
 1. Select a property from the first drop-down box on the left. You can begin typing any part of a property name in the search box to dynamically filter the list, so you can find what you're looking for quickly.
     :::image type="content" source="media/create-manage-use-automation-rules/filter-list.png" alt-text="Screenshot of typing in a search box to filter the list of choices.":::
@@ -85,8 +98,8 @@ Add any other conditions you want this automation rule's activation to depend on
     | Property | Operator set |
     | -------- | -------- |
     | - Title<br>- Description<br>- Tag<br>- All listed entity properties | - Equals/Does not equal<br>- Contains/Does not contain<br>- Starts with/Does not start with<br>- Ends with/Does not end with |
-    | - Severity<br>- Status<br>- Incident provider | - Equals/Does not equal |
-    | - Tactics<br>- Alert product names | - Contains/Does not contain |
+    | - Severity<br>- Status<br>- Incident provider<br>- Custom details key (Preview) | - Equals/Does not equal |
+    | - Tactics<br>- Alert product names<br>- Custom details value (Preview) | - Contains/Does not contain |
 
     #### Conditions available with the update trigger
 
@@ -96,14 +109,47 @@ Add any other conditions you want this automation rule's activation to depend on
     | - Tag (in addition to above)<br>- Alerts<br>- Comments | - Added |
     | - Severity<br>- Status | - Equals/Does not equal<br>- Changed<br>- Changed from<br>- Changed to |
     | - Owner | - Changed |
-    | - Incident provider<br>- Updated by | - Equals/Does not equal |
+    | - Incident provider<br>- Updated by<br>- Custom details key (Preview) | - Equals/Does not equal |
     | - Tactics | - Contains/Does not contain<br>- Added |
-    | - Alert product names | - Contains/Does not contain |
+    | - Alert product names<br>- Custom details value (Preview) | - Contains/Does not contain |
 
 1. Enter a value in the text box on the right. Depending on the property you chose, this might be a drop-down list from which you would select the values you choose. You might also be able to add several values by selecting the icon to the right of the text box (highlighted by the red arrow below).
 
     :::image type="content" source="media/create-manage-use-automation-rules/add-values-to-condition.png" alt-text="Screenshot of adding values to your condition in automation rules.":::
 
+Again, for setting complex **Or** conditions with different fields, see [Add advanced conditions to automation rules](add-advanced-conditions-to-automation-rules.md).
+
+#### Conditions based on custom details (Preview)
+
+You can set the value of a [custom detail surfaced in an incident](surface-custom-details-in-alerts.md) as a condition of an automation rule. Recall that custom details are data points in raw event log records that can be surfaced and displayed in alerts and the incidents generated from them. Through custom details you can get to the actual relevant content in your alerts without having to dig through query results.
+
+To add a condition based on a custom detail, take the following steps:
+
+1. Create a new automation rule as described above.
+
+1. Add a condition or a condition group.
+
+1. Select **Custom details key (Preview)** from the properties drop-down list. Select **Equals** or **Does not equal** from the operators drop-down list.
+
+    For the custom details condition, the values in the last drop-down list come from the custom details that were surfaced in all the analytics rules listed in the first condition. Select the custom detail you want to use as a condition.
+
+    :::image type="content" source="media/create-manage-use-automation-rules/custom-detail-key-condition.png" alt-text="Screenshot of adding a custom detail key as a condition.":::
+
+1. You've now chosen the field you want to evaluate for this condition. Now you have to specify the value appearing in that field that will make this condition evaluate to *true*.  
+Select **+ Add item condition**.
+
+    :::image type="content" source="media/create-manage-use-automation-rules/add-item-condition.png" alt-text="Screenshot of selecting add item condition for automation rules.":::
+
+    The value condition line appears below.
+
+    :::image type="content" source="media/create-manage-use-automation-rules/custom-details-value.png" alt-text="Screenshot of the custom detail value field appearing.":::
+
+1. Select **Contains** or **Does not contain** from the operators drop-down list. In the text box to the right, enter the value for which you want the condition to evaluate to *true*.
+
+    :::image type="content" source="media/create-manage-use-automation-rules/custom-details-value-filled.png" alt-text="Screenshot of the custom detail value field filled in.":::
+
+In this example, if the incident has the custom detail *DestinationEmail*, and if the value of that detail is `[email protected]`, the actions defined in the automation rule will run.
+
 ### Add actions
 
 Choose the actions you want this automation rule to take. Available actions include **Assign owner**, **Change status**, **Change severity**, **Add tags**, and **Run playbook**. You can add as many actions as you like.
@@ -156,8 +202,10 @@ Playbook actions within an automation rule may be treated differently under some
 | More than two minutes | Two minutes after playbook began running,<br>regardless of whether or not it was completed |
 
 ## Next steps
+
 In this document, you learned how to use automation rules to centrally manage response automation for Microsoft Sentinel incidents and alerts.
 
+- To learn how to add advanced conditions with `OR` operators to automation rules, see [Add advanced conditions to Microsoft Sentinel automation rules](add-advanced-conditions-to-automation-rules.md).
 - To learn more about automation rules, see [Automate incident handling in Microsoft Sentinel with automation rules](automate-incident-handling-with-automation-rules.md)
 - To learn more about advanced automation options, see [Automate threat response with playbooks in Microsoft Sentinel](automate-responses-with-playbooks.md).
 - To migrate alert-trigger playbooks to be invoked by automation rules, see [Migrate your Microsoft Sentinel alert-trigger playbooks to automation rules](migrate-playbooks-to-automation-rules.md)