Merge pull request #270420 from yelevin/yelevin/new-automation-operator

New automation operator

Author: v-dirichards

articles/sentinel/automate-incident-handling-with-automation-rules.md

@@ -1,10 +1,10 @@
 ---
 title: Automate threat response in Microsoft Sentinel with automation rules | Microsoft Docs
 description: This article explains what Microsoft Sentinel automation rules are, and how to use them to implement your Security Orchestration, Automation and Response (SOAR) operations, increasing your SOC's effectiveness and saving you time and resources.
-ms.topic: conceptual
 author: batamig
 ms.author: bagol
-ms.date: 03/14/2024
+ms.topic: conceptual
+ms.date: 03/27/2024
 appliesto:
     - Microsoft Sentinel in the Azure portal
     - Microsoft Sentinel in the Microsoft Defender portal
@@ -58,9 +58,9 @@ The following table shows the different possible scenarios that will cause an au
 
 | Trigger type | Events that cause the rule to run |
 | --------- | ------------ |
-| **When incident is created** | - A new incident is created by an analytics rule.<br>- An incident is ingested from Microsoft Defender XDR.<br>- A new incident is created manually. |
-| **When incident is updated**<br> | - An incident's status is changed (closed/reopened/triaged).<br>- An incident's owner is assigned or changed.<br>- An incident's severity is raised or lowered.<br>- Alerts are added to an incident.<br>- Comments, tags, or tactics are added to an incident. |
-| **When alert is created**<br> | - An alert is created by a scheduled analytics rule.
+| **When incident is created** | <li>A new incident is created by an analytics rule.<li>An incident is ingested from Microsoft Defender XDR.<li>A new incident is created manually. |
+| **When incident is updated** | <li>An incident's status is changed (closed/reopened/triaged).<li>An incident's owner is assigned or changed.<li>An incident's severity is raised or lowered.<li>Alerts are added to an incident.<li>Comments, tags, or tactics are added to an incident. |
+| **When alert is created** | <li>An alert is created by an analytics rule. |
 
 #### Incident-based or alert-based automation?
 
@@ -81,7 +81,9 @@ The main reason to use **alert-triggered automation** is for responding to alert
 - A playbook can be triggered by an alert and send the alert to an external ticketing system for incident creation and management, creating a new ticket for each alert.
 
 > [!NOTE]
-> Alert-triggered automation is available only for [alerts](detect-threats-built-in.md) created by **Scheduled** analytics rules. Alerts created by **Microsoft Security** analytics rules are not supported.
+> - Alert-triggered automation is available only for [alerts](detect-threats-built-in.md) created by **Scheduled** analytics rules. Alerts created by **Microsoft Security** analytics rules are not supported.
+>
+> - Alert-triggered automation is not currently available in the unified security operations platform in the Microsoft Defender portal.
 
 ### Conditions
 
@@ -93,7 +95,7 @@ When an automation rule is triggered, it checks the triggering incident or alert
 
 For rules defined using the trigger **When an incident is created**, you can define conditions that check the **current state** of the values of a given list of incident properties, using one or more of the following operators:
 
-An incident property's value 
+An incident property's value
 - **equals** or **does not equal** the value defined in the condition.
 - **contains** or **does not contain** the value defined in the condition.
 - **starts with** or **does not start with** the value defined in the condition.
@@ -137,14 +139,27 @@ An incident property's value was
 - **changed to** the value defined in the condition.
 - **added** to (this applies to properties with a list of values).
 
-An automation rule, based on the update trigger, can run on an incident that was updated by another automation rule, based on the incident creation trigger, that ran on the incident.
+#### *Tag* property: individual vs. collection
 
-Also, if an incident is updated by an automation rule that ran on the incident's creation, the incident can be evaluated by *both* a subsequent *incident-creation* automation rule *and* an *incident-update* automation rule, both of which will run if the incident satisfies the rules' conditions.
+The incident property **Tag** is a collection of individual items&mdash;a single incident can have multiple tags applied to it. You can define conditions that check **each tag in the collection individually**, and conditions that check **the collection of tags as a unit**.
 
-If an incident triggers both create-trigger and update-trigger automation rules, the create-trigger rules will run first, according to their **[Order](#order)** numbers, and then the update-trigger rules will run, according to *their* **Order** numbers.
+- **Any individual tag** operators check the condition against every tag in the collection. The evaluation is *true* when *at least one tag* satisfies the condition.
+- **Collection of all tags** operators check the condition against the collection of tags as a single unit. The evaluation is *true* only if *the collection as a whole* satisfies the condition.
 
-> [!NOTE]
-> After onboarding to the unified security operations platform, if multiple changes are made to the same incident in a five to ten minute period, a single update is sent to Microsoft Sentinel, with only the most recent change.
+This distinction matters when your condition is a negative (does not contain), and some tags in the collection satisfy the condition and others don't.
+
+Let's look at an example where your condition is, **Tag does not contain "2024"**, and you have two incidents, each with two tags:
+
+| \ Incidents &#9654;<br>Condition &#9660; \ | Incident 1<br>Tag 1: 2024<br>Tag 2: 2023 | Incident 2<br>Tag 1: 2023<br>Tag 2: 2022 |
+| -------------------------------------- | :------------------------: | :------------------------: |
+| **Any individual tag<br>does not contain "2024"** | ***TRUE***      | TRUE                       |
+| **Collection of all tags<br>does not contain "2024"** | ***FALSE*** | TRUE                       |
+
+In this example, in *Incident 1*: 
+- If the condition checks each tag individually, then since there's at least one tag that *satisfies the condition* (that *doesn't* contain "2024"), the overall condition is **true**.
+- If the condition checks all the tags in the incident as a single unit, then since there's at least one tag that *doesn't satisfy the condition* (that *does* contain "2024"), the overall condition is **false**.
+
+In *Incident 2*, the outcome will be the same, regardless of which type of condition is defined.
 
 #### Alert create trigger
 
@@ -196,6 +211,9 @@ Rules based on the update trigger have their own separate order queue. If such r
 - For rules of different *incident trigger* types, all applicable rules with the *incident creation* trigger type will run first (according to their order numbers), and only then the rules with the *incident update* trigger type (according to *their* order numbers).
 - Rules always run sequentially, never in parallel.
 
+> [!NOTE]
+> After onboarding to the unified security operations platform, if multiple changes are made to the same incident in a five to ten minute period, a single update is sent to Microsoft Sentinel, with only the most recent change.
+
 ## Common use cases and scenarios
 
 ### Incident tasks

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

@@ -4,7 +4,7 @@ description: This article explains how to create and use automation rules in Mic
 ms.topic: how-to
 author: batamig
 ms.author: bagol
-ms.date: 03/14/2024
+ms.date: 04/03/2024
 appliesto:
     - Microsoft Sentinel in the Azure portal
     - Microsoft Sentinel in the Microsoft Defender portal
@@ -34,7 +34,7 @@ The first step in designing and defining your automation rule is figuring out wh
 You also want to determine your use case. What are you trying to accomplish with this automation? Consider the following options:
 
 - Create tasks for your analysts to follow in triaging, investigating, and remediating incidents.
-- Suppress noisy incidents. (Alternately use other methods to [handle false positives in Microsoft Sentinel](false-positives.md).)
+- Suppress noisy incidents. (Alternatively, use other methods to [handle false positives in Microsoft Sentinel](false-positives.md).)
 - Triage new incidents by changing their status from New to Active and assigning an owner.
 - Tag incidents to classify them.
 - Escalate an incident by assigning a new owner.
@@ -52,9 +52,9 @@ The following table shows the different possible scenarios that will cause an au
 
 | Trigger type | Events that cause the rule to run |
 | --------- | ------------ |
-| **When incident is created** | - A new incident is created by an analytics rule.<br>- An incident is ingested from Microsoft Defender XDR.<br>- A new incident is created manually. |
-| **When incident is updated**<br> | - An incident's status is changed (closed/reopened/triaged).<br>- An incident's owner is assigned or changed.<br>- An incident's severity is raised or lowered.<br>- Alerts are added to an incident.<br>- Comments, tags, or tactics are added to an incident. |
-| **When alert is created**<br> | - An alert is created by a scheduled analytics rule.
+| **When incident is created** | <li>A new incident is created by an analytics rule.<li>An incident is ingested from Microsoft Defender XDR.<li>A new incident is created manually. |
+| **When incident is updated**<br> | <li>An incident's status is changed (closed/reopened/triaged).<li>An incident's owner is assigned or changed.<li>An incident's severity is raised or lowered.<li>Alerts are added to an incident.<li>Comments, tags, or tactics are added to an incident. |
+| **When alert is created**<br> | <li>An alert is created by an analytics rule. |
 
 ## Create your automation rule
 
@@ -143,28 +143,66 @@ Use the options in the **Conditions** area to define conditions for your automat
 1. Select an operator from the next drop-down box to the right.
     :::image type="content" source="media/create-manage-use-automation-rules/select-operator.png" alt-text="Screenshot of selecting a condition operator for automation rules.":::
 
-The list of operators you can choose from varies according to the selected trigger and property. 
+    The list of operators you can choose from varies according to the selected trigger and property. 
 
-#### Conditions available with the create trigger
+    #### Conditions available with the create trigger
 
-| 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>- Custom details key (Preview) | -Equals/Does not equal |
-| - Tactics<br>- Alert product names<br>- Custom details value (Preview) <br>- Analytic rule name| - Contains/Does not contain |
+    | Property | Operator set |
+    | -------- | -------- |
+    | - **Title**<br>- **Description**<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 |
+    | - **Tag** (See [individual vs. collection](automate-incident-handling-with-automation-rules.md#tag-property-individual-vs-collection)) | **Any individual tag:**<br>- Equals/Does not equal<br>- Contains/Does not contain<br>- Starts with/Does not start with<br>- Ends with/Does not end with<br><br>**Collection of all tags:**<br>- Contains/Does not contain |
+    | - **Severity**<br>- **Status**<br>- **Custom details key** | - Equals/Does not equal |
+    | - **Tactics**<br>- **Alert product names**<br>- **Custom details value**<br>- **Analytic rule name** | - Contains/Does not contain |
 
-#### Conditions available with the update trigger
+    #### Conditions available with the update trigger
 
-| 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 |
-| - 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 |
-| - Updated by<br>- Custom details key (Preview) | - Equals/Does not equal |
-| - Tactics | - Contains/Does not contain<br>- Added |
-| - Alert product names<br>- Custom details value (Preview) <br>- Analytic rule name| - Contains/Does not contain |
+    | Property | Operator set |
+    | -------- | -------- |
+    | - **Title**<br>- **Description**<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 |
+    | - **Tag** (See [individual vs. collection](automate-incident-handling-with-automation-rules.md#tag-property-individual-vs-collection)) | **Any individual tag:**<br>- Equals/Does not equal<br>- Contains/Does not contain<br>- Starts with/Does not start with<br>- Ends with/Does not end with<br><br>**Collection of all tags:**<br>- Contains/Does not contain |
+    | - **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 |
+    | - **Updated by**<br>- **Custom details key** | - Equals/Does not equal |
+    | - **Tactics** | - Contains/Does not contain<br>- Added |
+    | - **Alert product names**<br>- **Custom details value**<br>- **Analytic rule name** | - Contains/Does not contain |
 
+1. Enter a value in the field on the right. Depending on the property you chose, this might be either a text box or a drop-down in which you select from a closed list of values. You might also be able to add several values by selecting the dice icon to the right of the text box.
+
+    :::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 tags
+
+You can create two kinds of conditions based on tags:
+
+- Conditions with **Any individual tag** operators evaluate the specified value against every tag in the collection. The evaluation is *true* when *at least one tag* satisfies the condition.
+- Conditions with **Collection of all tags** operators evaluate the specified value against the collection of tags as a single unit. The evaluation is *true* only if *the collection as a whole* satisfies the condition.
+
+To add one of these conditions based on an incident's tags, take the following steps:
+
+1. Create a new automation rule as described above.
+
+1. Add a condition or a condition group.
+
+1. Select **Tag** from the properties drop-down list.
+
+1. Select the operators drop-down list to reveal the available operators to choose from.
+
+    ##### [Onboarded workspaces](#tab/onboarded)
+
+    :::image type="content" source="media/create-manage-use-automation-rules/tag-create-condition-defender.png" alt-text="Screenshot of list of operators for tag condition in create trigger rule--for onboarded workspaces." lightbox="media/create-manage-use-automation-rules/tag-create-condition-defender.png":::
+
+    ##### [Workspaces not onboarded](#tab/not-onboarded)
+
+    :::image type="content" source="media/create-manage-use-automation-rules/tag-create-condition-azure.png" alt-text="Screenshot of list of operators for tag condition in create trigger rule--for non-onboarded workspaces." lightbox="media/create-manage-use-automation-rules/tag-create-condition-azure.png":::
+
+    ---
+
+    See how the operators are divided in two categories as described before. Choose your operator carefully based on how you want the tags to be evaluated.
+
+    For more information, see [*Tag* property: individual vs. collection](automate-incident-handling-with-automation-rules.md#tag-property-individual-vs-collection).
 
 #### Conditions based on custom details
 
@@ -182,7 +220,7 @@ You can set the value of a [custom detail surfaced in an incident](surface-custo
 
     :::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*.  
+1. You chose the field you want to evaluate for this condition. Now specify the value appearing in that field that makes 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.":::