Merge pull request #285617 from yelevin/yelevin/import-export-automation-rules

Supported entity properties

Author: PMEds28

articles/sentinel/TOC.yml

@@ -1301,6 +1301,8 @@
     items:
     - name: SOAR content catalog
       href: sentinel-soar-content.md
+    - name: Automation rules reference
+      href: automation-rule-reference.md
   - name: Data collection references
     items:
     - name: Data source schema reference

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

@@ -1,6 +1,6 @@
 ---
 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.
+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. Automation rules increase your SOC's effectiveness and save you time and resources.
 author: batamig
 ms.author: bagol
 ms.topic: conceptual
@@ -14,7 +14,7 @@ ms.collection: usx-security
 
 # Automate threat response in Microsoft Sentinel with automation rules
 
-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.
+This article explains what Microsoft Sentinel automation rules are, and how to use them to implement your Security Orchestration, Automation and Response (SOAR) operations. Automation rules increase your SOC's effectiveness and save you time and resources.
 
 [!INCLUDE [unified-soc-preview](includes/unified-soc-preview.md)]
 
@@ -52,7 +52,7 @@ Automation rules are made up of several components:
 
 ### Triggers
 
-Automation rules are triggered **when an incident is created or updated** or **when an alert is created**. Recall that incidents include alerts, and that both alerts and incidents can be created by analytics rules, of which there are several types, as explained in [Threat detection in Microsoft Sentinel](threat-detection.md).
+Automation rules are triggered **when an incident is created or updated** or **when an alert is created**. Recall that incidents include alerts, and that both alerts and incidents can be created by analytics rules, as explained in [Threat detection in Microsoft Sentinel](threat-detection.md).
 
 The following table shows the different possible scenarios that cause an automation rule to run.
 
@@ -64,25 +64,25 @@ The following table shows the different possible scenarios that cause an automat
 
 #### Incident-based or alert-based automation?
 
-Now that both incident automation and alert automation are handled centrally by automation rules as well as playbooks, how should you choose when to use which?
+With automation rules centrally handling the response to both incidents and alerts, how should you choose which to automate, and in which circumstances?
 
 For most use cases, **incident-triggered automation** is the preferable approach. In Microsoft Sentinel, an **incident** is a “case file” – an aggregation of all the relevant evidence for a specific investigation. It’s a container for alerts, entities, comments, collaboration, and other artifacts. Unlike **alerts** which are single pieces of evidence, incidents are modifiable, have the most updated status, and can be enriched with comments, tags, and bookmarks. The incident allows you to track the attack story that keeps evolving with the addition of new alerts. 
 
 For these reasons, it makes more sense to build your automation around incidents. So the most appropriate way to create playbooks is to base them on the Microsoft Sentinel incident trigger in Azure Logic Apps.
 
-The main reason to use **alert-triggered automation** is for responding to alerts generated by analytics rules that *do not create incidents* (that is, where incident creation has been *disabled* in the **Incident settings** tab of the [analytics rule wizard](detect-threats-custom.md#configure-the-incident-creation-settings)).
+The main reason to use **alert-triggered automation** is for responding to alerts generated by analytics rules that *do not create incidents* (that is, where incident creation is *disabled* in the **Incident settings** tab of the [analytics rule wizard](detect-threats-custom.md#configure-the-incident-creation-settings)).
 
-This reason is especially relevant when your Microsoft Sentinel workspace is onboarded to the unified security operations platform, as all incident creation happens in Microsoft Defender XDR, and therefore the incident creation rules in Microsoft Sentinel *must be disabled*.
+This reason is especially relevant when your Microsoft Sentinel workspace is onboarded to the unified security operations platform. In this scenario, all incident creation happens in Microsoft Defender XDR, and therefore the incident creation rules in Microsoft Sentinel *must be disabled*.
 
-Even without being onboarded to the unified portal, you might anyway decide to use alert-triggered automation if you want to use other external logic to determine if and how incidents are created from alerts, as well as if and how alerts are grouped into incidents. For example:
+Even without being onboarded to the unified portal, you might anyway decide to use alert-triggered automation if you want to use other external logic to decide if and when to create incidents from alerts, and how alerts are grouped together. For example:
 
-- A playbook can be triggered by an alert that doesn’t have an associated incident, enrich the alert with information from other sources, and based on some external logic decide whether to create an incident or not.
+- A playbook, triggered by an alert that doesn’t have an associated incident, can enrich the alert with information from other sources, and based on some external logic decide whether to create an incident or not.
 
-- A playbook can be triggered by an alert and, instead of creating an incident, look for an appropriate existing incident to add the alert to. Learn more about [incident expansion](relate-alerts-to-incidents.md).
+- A playbook, triggered by an alert, can, instead of creating an incident, look for an appropriate existing incident to add the alert to. Learn more about [incident expansion](relate-alerts-to-incidents.md).
 
-- A playbook can be triggered by an alert and notify SOC personnel of the alert, so the team can decide whether or not to create an incident.
+- A playbook, triggered by an alert, can notify SOC personnel of the alert so the team can decide whether or not to create an incident.
 
-- 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.
+- A playbook, triggered by an alert, can send the alert to an external ticketing system for incident creation and management, and that system creates a new ticket for each alert.
 
 > [!NOTE]
 > - Alert-triggered automation is available only for alerts created by [**Scheduled**, **NRT**, and **Microsoft security** analytics rules](threat-detection.md).
@@ -91,7 +91,7 @@ Even without being onboarded to the unified portal, you might anyway decide to u
 
 ### Conditions
 
-Complex sets of conditions can be defined to govern when actions (see below) should run. These conditions include the event that triggers the rule (incident created or updated, or alert created), the states or values of the incident's properties and [entity properties](entities-reference.md) (for incident trigger only), and also the analytics rule or rules that generated the incident or alert.
+Complex sets of conditions can be defined to govern when actions (see below) should run. These conditions include the event that triggers the rule (incident created or updated, or alert created), the states or values of the incident's properties and [entity properties](#supported-entity-properties) (for incident trigger only), and also the analytics rule or rules that generated the incident or alert.
 
 When an automation rule is triggered, it checks the triggering incident or alert against the conditions defined in the rule. For incidents, the property-based conditions are evaluated according to **the current state** of the property at the moment the evaluation occurs, or according to **changes in the state** of the property (see below for details). Since a single incident creation or update event could trigger several automation rules, the **order** in which they run (see below) makes a difference in determining the outcome of the conditions' evaluation. The **actions** defined in the rule are executed only if all the conditions are satisfied.
 
@@ -114,7 +114,7 @@ For example, if you define **Analytic rule name** as **Contains == Brute force a
 
 The conditions evaluated in rules defined using the trigger **When an incident is updated** include all of those listed for the incident creation trigger. But the update trigger includes more properties that can be evaluated.
 
-One of these properties is **Updated by**. This property lets you track the type of source that made the change in the incident. You can create a condition evaluating whether the incident was updated by one of the following values, depending on whether you've onboarded your workspace to the unified security operations platform:
+One of these properties is **Updated by**. This property lets you track the type of source that made the change in the incident. You can create a condition evaluating whether the incident was updated by one of the following values, depending on whether you onboarded your workspace to the unified security operations platform:
 
 ##### [Onboarded workspaces](#tab/onboarded)
 
@@ -136,6 +136,7 @@ One of these properties is **Updated by**. This property lets you track the type
 - Microsoft Defender XDR
 
 ---
+
 Using this condition, for example, you can instruct this automation rule to run on any change made to an incident, except if it was made by another automation rule.
 
 More to the point, the update trigger also uses other operators that check **state changes** in the values of incident properties as well as their current state. A **state change** condition would be satisfied if:
@@ -168,13 +169,17 @@ In this example, in *Incident 1*:
 
 In *Incident 2*, the outcome is the same, regardless of which type of condition is defined.
 
+#### Supported entity properties
+
+For the list of entity properties supported as conditions for automation rules, see [Microsoft Sentinel automation rules reference](automation-rule-reference.md).
+
 #### Alert create trigger
 
 Currently the only condition that can be configured for the alert creation trigger is the set of analytics rules for which the automation rule is run.
 
 ### Actions
 
-Actions can be defined to run when the conditions (see above) are met. You can define many actions in a rule, and you can choose the order in which they’ll run (see below). The following actions can be defined using automation rules, without the need for the [advanced functionality of a playbook](automate-responses-with-playbooks.md):
+Actions can be defined to run when the conditions (see above) are met. You can define many actions in a rule, and you can choose the order in which they run (see below). The following actions can be defined using automation rules, without the need for the [advanced functionality of a playbook](automate-responses-with-playbooks.md):
 
 - Adding a task to an incident – you can create a [checklist of tasks for analysts to follow](incident-tasks.md) throughout the processes of triage, investigation, and remediation of the incident, to ensure that no critical steps are missed.
 
@@ -212,7 +217,7 @@ Rules based on the update trigger have their own separate order queue. If such r
 - Each trigger type maintains its own queue.
 - For rules created in the Azure portal, the **order** field is automatically populated with the number following the highest number used by existing rules of the same trigger type.
 - However, for rules created in other ways (command line, API, etc.), the **order** number must be assigned manually.
-- There is no validation mechanism preventing multiple rules from having the same order number, even within the same trigger type. 
+- There is no validation mechanism that prevents multiple rules from having the same order number, even within the same trigger type. 
 - You can allow two or more rules of the same trigger type to have the same order number, if you don't care which order they run in.
 - For rules of the same trigger type with the same order number, the execution engine randomly selects which rules run in which order.
 - For rules of different *incident trigger* types, all applicable rules with the *incident creation* trigger type run first (according to their order numbers), and only then the rules with the *incident update* trigger type (according to *their* order numbers).
@@ -283,7 +288,7 @@ Notify your various teams and other personnel when changes are made to incidents
 
 ### Maintain synchronization with external systems
 
-If you've used playbooks to create tickets in external systems when incidents are created, you can use an update-trigger automation rule to call a playbook that updates those tickets.
+If you used playbooks to create tickets in external systems when incidents are created, you can use an update-trigger automation rule to call a playbook that updates those tickets.
 
 ## Automation rules execution
 
@@ -368,4 +373,4 @@ In this document, you learned about how automation rules can help you to central
 - [Create and use Microsoft Sentinel automation rules to manage incidents](create-manage-use-automation-rules.md).
 - [Use automation rules to create lists of tasks for analysts](create-tasks-automation-rule.md).
 - To learn more about advanced automation options, see [Automate threat response with playbooks in Microsoft Sentinel](automate-responses-with-playbooks.md).
-- For help in implementing playbooks, see [Tutorial: Use playbooks to automate threat responses in Microsoft Sentinel](tutorial-respond-threats-playbook.md).
+- For help with implementing playbooks, see [Tutorial: Use playbooks to automate threat responses in Microsoft Sentinel](tutorial-respond-threats-playbook.md).