Final draft

Author: yelevin

articles/sentinel/automate-responses-with-playbooks.md

@@ -218,7 +218,7 @@ The actions you can take on entities using this playbook type include:
 - Blocking a compromised user.
 - Blocking traffic from a malicious IP address in your firewall.
 - Isolating a compromised host on your network.
-- Adding an IP address to a safe/unsafe address watchlist, or to your external CMDB. ***(???)***
+- Adding an IP address to a safe/unsafe address watchlist, or to your external CMDB.
 - Getting a file hash report from an external threat intelligence source and adding it to an incident as a comment.
 
 ## How to run a playbook

articles/sentinel/media/playbook-triggers-actions/entity-trigger-actions.png

@@ -31,13 +31,13 @@ For the complete specification of the Microsoft Sentinel connector, see the [Log
 
 ## Microsoft Sentinel triggers summary
 
-Though the Microsoft Sentinel connector can be used in a variety of ways, the connector's components can be divided into 2 flows, each triggered by a different Microsoft Sentinel occurrence:
+Though the Microsoft Sentinel connector can be used in a variety of ways, the connector's components can be divided into three flows, each triggered by a different Microsoft Sentinel occurrence:
 
 | Trigger (full name in Logic Apps Designer) | When to use it | Known limitations 
 | --------------------- | -------------- | -------------- | 
 | **Microsoft Sentinel incident (Preview)** | Recommended for most incident automation scenarios.<br><br>The playbook receives incident objects, including entities and alerts. Using this trigger allows the playbook to be attached to an **Automation rule**, so it can be triggered when an incident is created (and now, updated as well) in Microsoft Sentinel, and all the [benefits of automation rules](./automate-incident-handling-with-automation-rules.md) can be applied to the incident. | Playbooks with this trigger do not support alert grouping, meaning they will receive only the first alert sent with each incident.
 | **Microsoft Sentinel alert (Preview)** | Advisable for playbooks that need to be run on alerts manually from the Microsoft Sentinel portal, or for **scheduled** analytics rules that don't generate incidents for their alerts. | This trigger cannot be used to automate responses for alerts generated by **Microsoft security** analytics rules.<br><br>Playbooks using this trigger cannot be called by **automation rules**. |
-| **Microsoft Sentinel entity (Preview)** | To be used for playbooks that need to be run manually on specific entities from an investigation or threat hunting context, or in scenarios that a SOC does not want to automate. | Playbooks using this trigger cannot be called by **automation rules**. |
+| **Microsoft Sentinel entity (Preview)** | To be used for playbooks that need to be run manually on specific entities from an investigation or threat hunting context. | Playbooks using this trigger cannot be called by **automation rules**. |
 
 The schemas used by these flows are not identical. The recommended practice is to use the **Microsoft Sentinel incident trigger** flow, which is applicable to most scenarios.
 
@@ -72,7 +72,7 @@ The **Incident** object received from **Microsoft Sentinel incident** includes t
 | **Entities - Get \<*entity type*\>** | In playbooks that work on a specific entity type (**IP**, **Account**, **Host**, **URL** or **FileHash**) which is known at playbook creation time, and you need to be able to parse it and work on its unique fields. |
 |
 
-## Work with incidents - Usage Examples
+## Work with incidents - usage examples
 
 > [!TIP] 
 > The actions **Update Incident** and **Add a Comment to Incident** require the **Incident ARM ID**.
@@ -109,7 +109,20 @@ Basic playbook to send incident details over mail:
 
     !["Alert trigger simple add comment example"](media/playbook-triggers-actions/alert-comment.png)
 
-## Work with specific Entity types
+## Work with entities
+
+> [!NOTE]
+> If a playbook created with the **Entity trigger** makes use of the **Incident ARM ID** field, then in the event that this playbook is triggered in a context unconnected to an incident, this field will be populated with a null value. The playbook will still run, but any actions that refer to the incident ID will be skipped.
+> 
+> Examples of this situation might be if the playbook was run from an entity page accessed from the **Entity behavior** page, or as the result of a hunting query.
+
+### Usage example - disable a user
+
+- Playbook is triggered by **Microsoft Sentinel Entity**
+
+    :::image type="content" source="media/playbook-triggers-actions/entity-trigger-actions.png" alt-text="Screenshot showing actions to take in an entity-trigger playbook to disable a user.":::
+
+### Work with specific Entity types
 
 The **Entities** dynamic field is an array of JSON objects, each of which represents an entity. Each entity type has its own schema, depending on its unique properties.
 

articles/sentinel/playbook-triggers-actions.md

@@ -10,8 +10,6 @@ ms.author: yelevin
 
 # Tutorial: Use playbooks with automation rules in Microsoft Sentinel
 
-[!INCLUDE [Banner for top of topics](./includes/banner.md)]
-
 This tutorial shows you how to use playbooks together with automation rules to automate your incident response and remediate security threats detected by Microsoft Sentinel. When you complete this tutorial you will be able to:
 
 > [!div class="checklist"]
@@ -76,16 +74,13 @@ Follow these steps to create a new playbook in Microsoft Sentinel:
 
 1. From the top menu, select **Create**.
 
-1. The drop-down menu that appears under **Create** gives you three choices for creating playbooks:
+1. The drop-down menu that appears under **Create** gives you four choices for creating playbooks:
 
     1. If you're creating a **Standard** playbook (the new kind - see [Logic app types](automate-responses-with-playbooks.md#logic-app-types)), select **Blank playbook** and then follow the steps in the **Logic Apps Standard** tab below.
 
     1. If you're creating a **Consumption** playbook (the original, classic kind), then, depending on which trigger you want to use, select either **Playbook with incident trigger**, **Playbook with alert trigger**, or **Playbook with entity trigger**. Then, continue following the steps in the **Logic Apps Consumption** tab below.
 
-        > [!NOTE]
-        > Remember that only playbooks based on the **incident trigger** can be called by automation rules. Playbooks based on the **alert trigger** must be defined to run directly in [analytics rules](detect-threats-custom.md#set-automated-responses-and-create-the-rule). Both types can also be run manually.
-        > 
-        > For more about which trigger to use, see [**Use triggers and actions in Microsoft Sentinel playbooks**](playbook-triggers-actions.md)
+        For more about which trigger to use, see [**Use triggers and actions in Microsoft Sentinel playbooks**](playbook-triggers-actions.md).
 
 # [Logic Apps Consumption](#tab/LAC)
 ### Prepare the playbook and Logic App
@@ -229,9 +224,13 @@ Now you can define what happens when you call the playbook. You can add actions,
 
 In every one of these steps, clicking on any field displays a panel with two menus: **Dynamic content** and **Expression**. From the **Dynamic content** menu, you can add references to the attributes of the alert or incident that was passed to the playbook, including the values and attributes of all the [mapped entities](map-data-fields-to-entities.md) and [custom details](surface-custom-details-in-alerts.md) contained in the alert or incident. From the **Expression** menu, you can choose from a large library of functions to add additional logic to your steps.
 
-   :::image type="content" source="./media/tutorial-respond-threats-playbook/logic-app.png" alt-text="Logical app designer":::
+This screenshot shows the actions and conditions you would add in creating the playbook described in the example at the beginning of this document. Learn more about [adding actions to your playbooks](playbook-triggers-actions.md).
+
+   :::image type="content" source="./media/tutorial-respond-threats-playbook/logic-app.png" alt-text="Screenshot showing the Logic App designer with an incident trigger workflow.":::
+
+See [**Use triggers and actions in Microsoft Sentinel playbooks**](playbook-triggers-actions.md) for details about actions you can add to playbooks for different purposes.
 
-This screenshot shows the actions and conditions you would add in creating the playbook described in the example at the beginning of this document. The only difference is that in the playbook shown here, you are using the **alert trigger** instead of the **incident trigger**. This means that you'll call this playbook from an analytics rule directly, not from an automation rule. Both ways of calling a playbook will be described below.
+In particular, note this important information about [**working with playbooks based on the entity trigger**](playbook-triggers-actions.md#work-with-entities).
 
 ## Automate threat responses
 
@@ -245,11 +244,11 @@ To create an automation rule:
 
 1. From the **Automation** blade in the Microsoft Sentinel navigation menu, select **Create** from the top menu and then **Add new rule**.
 
-   :::image type="content" source="./media/tutorial-respond-threats-playbook/add-new-rule.png" alt-text="Add a new rule":::
+   :::image type="content" source="./media/tutorial-respond-threats-playbook/add-new-rule.png" alt-text="Screenshot showing how to add a new automation rule.":::
 
 1. The **Create new automation rule** panel opens. Enter a name for your rule.
 
-   :::image type="content" source="./media/tutorial-respond-threats-playbook/create-automation-rule.png" alt-text="Create an automation rule":::
+   :::image type="content" source="./media/tutorial-respond-threats-playbook/create-automation-rule.png" alt-text="Screenshot showing the automation rule creation wizard.":::
 
 1. If you want the automation rule to take effect only on certain analytics rules, specify which ones by modifying the **If Analytics rule name** condition.
 
@@ -349,6 +348,31 @@ You can see the run history for playbooks on an alert by selecting the **Runs**
 
 You can see the run history for playbooks on an incident by selecting the **Runs** tab on the **Run playbook on incident** panel. It might take a few seconds for any just-completed run to appear in the list. Selecting a specific run will open the full run log in Logic Apps.
 
+### Run a playbook manually on an entity
+
+1. Select an entity in one of the following ways, depending on your originating context:
+
+    **If you're in an incident's details page:**
+    1. Select the incident's **Entities** tab.
+    1. Find an entity from the list (don't select it).
+    1. Select the **Run playbook (Preview)** link at the end of its line in the list.  
+    If you selected the entity and entered its entity page, select the **Run playbook (Preview)** button in the left-hand panel.
+    
+    **If you're in the Investigation graph:**
+    1. Select an entity in the graph.
+    1. Select the **Run playbook (Preview)** button in the entity side panel.  
+    For some entity types, you may have to select the **Entity actions** button and from the resulting menu select **Run playbook (Preview)**.
+
+    **If you're proactively hunting for threats:**
+    1. From the **Entity behavior** screen, select an entity from the lists on the page, or search for and select another entity.
+    1. In the [entity page](entity-pages.md), select the **Run playbook (Preview)** button in the left-hand panel.
+
+1. Regardless of the context you came from, the instructions above will all open the **Run playbook on *\<entity type>*** panel. You'll see a list of all playbooks that you have access to that were configured with the **Microsoft Sentinel Entity** Logic Apps trigger for the selected entity type.
+
+1. Select **Run** on the line of a specific playbook to run it immediately.
+
+You can see the run history for playbooks on a given entity by selecting the **Runs** tab on the **Run playbook on *\<entity type>*** panel. It might take a few seconds for any just-completed run to appear in the list. Selecting a specific run will open the full run log in Logic Apps.
+
 ## Next steps
 
 In this tutorial, you learned how to use playbooks and automation rules in Microsoft Sentinel to respond to threats.