Final draft

Author: yelevin

articles/sentinel/whats-new.md

@@ -126,50 +126,51 @@ A [new version of the Microsoft Sentinel Logstash plugin](connect-logstash-data-
 
 ### New behavior for alert grouping in analytics rules
 
-As of **February 2, 2023**, Microsoft is changing the way that incidents are created from analytics rules with certain event and alert grouping settings, and also the way that such incidents are updated by automation rules.
+As of **February 2, 2023**, Microsoft Sentinel is changing the way that incidents are created from analytics rules with certain event and alert grouping settings, and also the way that such incidents are updated by automation rules. This change is being made in order to produce incidents with more complete information and to simplify automation triggered by the creating and updating of incidents.
 
 The affected analytics rules are those with both of the following two settings:
 - **Event grouping** is set to **Trigger an alert for each event** (sometimes referred to as "alert per row" or "alert per result").
 - **Alert grouping** is enabled, in any one of the [three possible configurations](detect-threats-custom.md#alert-grouping).
 
 #### The problem
 
-Rules with these two settings generate unique alerts for each event (result) returned by the query. These alerts are then all grouped together into a single incidents or a small number of incidents (depending on the alert grouping configuration choice).
+Rules with these two settings generate unique alerts for each event (result) returned by the query. These alerts are then all grouped together into a single incident (or a small number of incidents, depending on the alert grouping configuration choice).
 
-The problem is that the incidents are created as soon as the first alert is generated, so at that point they contain only the first alert. The remaining alerts are joined to the incident one after the other as they are generated. So you end up with a single running of an analytics rule resulting in:
+The problem is that the incident is created as soon as the first alert is generated, so at that point the incident contains only the first alert. The remaining alerts are joined to the incident, one after the other, as they are generated. So you end up with a *single running of an analytics rule* resulting in:
 - One incident creation event *and*
 - Up to 149 incident update events
 
 These circumstances result in unpredictable behavior when evaluating the conditions defined in automation rules or populating the incident schema in playbooks:
 
-- Automation rules on this incident will run immediately on its creation, even with just the one alert included. So the automation rule will only consider the incident's status as containing the first alert, even though alerts will continue being added while the automation rule is running. So you end up with a situation where the automation rule's evaluation of the incident is incomplete and likely incorrect.
+- **Incorrect evaluation of an incident's conditions by automation rules:**
 
-- Entities in later alerts being left out of the incident.
+    Automation rules on this incident will run immediately on its creation, even with just the one alert included. So the automation rule will only consider the incident's status as containing the first alert, even though other alerts are being created nearly simultaneously (by the same running of the analytics rule) and will continue being added while the automation rule is running. So you end up with a situation where the automation rule's evaluation of the incident is incomplete and likely incorrect.
+
+    If there are automation rules defined to run when the incident is *updated*, they will run again and again as each subsequent alert is added to the incident (even though the alerts were all generated by the same running of the analytics rule). So you'll have alerts being added and automation rules running, each time possibly incorrectly evaluating the conditions of the incident.
 
     Automation rules' conditions might ignore entities that only later become part of the incident but weren't included in the first alert/creation of the incident.
 
-- Because of the previous behavior, Playbooks may only consider the details of the first alert in an incident, but not those from subsequent alerts. 
+    In these cases, incorrect evaluation of an incident's condition may cause automation rules to run when they shouldn't, or not to run when they should. The result of this would be that the wrong actions would be taken on an incident, or that the right actions would not be taken.
 
-#### The solution
+- **Information in later alerts being ignored when playbooks are run on the incident:**
 
-The following table describes the change in the incident creation and automation behaviors:
+    When an automation rule calls a playbook, it passes the incident's detailed information to the playbook. Because of the behavior mentioned above, a playbook might only receive the details (entities, custom details, and so on) of the first alert in an incident, but not those from subsequent alerts. This means that the playbook's actions would not have access to all the information in the incident.
 
-| When incident created/updated with multiple alerts | Before the change | After the change |
-| -- | -- | -- |
-| **Automation rule** conditions (trigger: when an incident is created/updated) will be evaluated based on... | The first alert of the incident only. This causes unexpected behavior ('race condition') when evaluating automation rules conditions. | after all alerts and entities, triggered by this rule execution and grouped to this incident, have been added, with the most recent incident properties (such as severity and tactics). |
-| **Playbook input** (Microsoft Sentinel incident trigger) | Alerts list contains only the first alert of the incident | Alerts list contains all the alerts triggered by this rule execution and grouped to this incident |
-| **SecurityIncident** table in Log Analytics shows... | -&nbsp;One&nbsp;row&nbsp;for&nbsp;*incident&nbsp;created*&nbsp;with&nbsp;one&nbsp;alert.<br>- Multiple&nbsp;events&nbsp;of&nbsp;*alert&nbsp;added*. | One row for *incident created* only after all alerts triggered by this rule execution have been added and grouped to this incident. |
+#### The solution
 
+Going forward, instead of creating the incident as soon as the first alert is generated, Microsoft Sentinel will wait until a single running of an analytics rule has generated all of its alerts, and then create the incident, adding all the alerts to it at once. So instead of an incident creation event and a whole bunch of incident update events, you have only the incident creation event.
 
-#### How to prepare for this change?
+Now, automation rules that run on the creation of an incident can evaluate the complete incident with all of its alerts (as well as entities and custom details) and its most updated properties, and any playbooks that run will similarly have the complete details of the incident.
 
-- Check whether you have automation rules with **When incident is created** or **When incident is updated** which are set to run on analytics rule with the configuration above.
 
-    These automation rules' conditions will now be evaluated based on the incident after all alerts, triggered by this rule execution and grouped to this incident, and their entities have been added, with the most recent incident properties.
 
-- If these automation rules also trigger playbooks, and these playbooks work on the incident alerts or entities, they may now get more alerts and entities than they used to.
+The following table describes the change in the incident creation and automation behaviors:
 
-- If you have any scripts  or pre-defined queries running based on the *SecurityIncident* table, please note that for these analytics rules, the way rows are added to the table will be different (One row for incident created after all alerts have been added).
+| When incident created/updated with multiple alerts | Before the change | After the change |
+| -- | -- | -- |
+| **Automation rule** conditions are evaluated based on... | The first alert generated by the current running of the analytics rule. | All alerts and entities resulting from the current running of the analytics rule. |
+| **Playbook input** includes... | - Alerts list containing only the first alert of the incident.<br>- Entities list containing only entities from the first alert of the incident. | - Alerts list containing all the alerts triggered by this rule execution and grouped to this incident.<br>- Entities list containing the entities from all the alerts triggered by this rule execution and grouped to this incident. |
+| **SecurityIncident** table in Log Analytics shows... | -&nbsp;One&nbsp;row&nbsp;for&nbsp;*incident&nbsp;created*&nbsp;with&nbsp;one&nbsp;alert.<br>- Multiple&nbsp;events&nbsp;of&nbsp;*alert&nbsp;added*. | One row for *incident created* only after all alerts triggered by this rule execution have been added and grouped to this incident. |
 
 ### Microsoft 365 Defender now integrates Azure Active Directory Identity Protection (AADIP)