Draft ready

Author: yelevin

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

@@ -16,9 +16,7 @@ This article explains what Microsoft Sentinel playbooks are, and how to use them
 
 SOC analysts are typically inundated with security alerts and incidents on a regular basis, at volumes so large that available personnel are overwhelmed. This results all too often in situations where many alerts are ignored and many incidents aren't investigated, leaving the organization vulnerable to attacks that go unnoticed.
 
-Analysts are also tasked with basic remediation and investigation of the incidents they do manage to address.
-
-Many, if not most, of these alerts and incidents conform to recurring patterns that can be addressed by specific and defined sets of remediation actions.
+Many, if not most, of these alerts and incidents conform to recurring patterns that can be addressed by specific and defined sets of remediation actions. Analysts are also tasked with basic remediation and investigation of the incidents they do manage to address. To the extent that these activities can be automated, a SOC can be that much more productive and efficient, allowing analysts to devote more time and energy to investigative activity.
 
 A playbook is a collection of these remediation actions that can be run from Microsoft Sentinel as a routine. A playbook can help [**automate and orchestrate your threat response**](tutorial-respond-threats-playbook.md); it can be run manually on-demand on entities (in preview - see below) and alerts, or set to run automatically in response to specific alerts or incidents, when triggered by an [automation rule](automate-incident-handling-with-automation-rules.md).
 
@@ -109,8 +107,9 @@ There are many differences between these two resource types, some of which affec
 
 #### Azure roles for Microsoft Sentinel
 
-- **Microsoft Sentinel Contributor** role lets you attach a playbook to an analytics rule.
-- **Microsoft Sentinel Responder** role lets you run a playbook manually.
+- **Microsoft Sentinel Contributor** role lets you attach a playbook to an analytics or automation rule.
+- **Microsoft Sentinel Responder** role lets you access an incident in order to run a playbook manually. But to actually run the playbook, you also need...
+- **Microsoft Sentinel Playbook Operator** role lets you run a playbook manually.
 - **Microsoft Sentinel Automation Contributor** allows automation rules to run playbooks. It is not used for any other purpose.
 
 #### Learn more
@@ -299,7 +298,7 @@ For these and other reasons, Microsoft Sentinel allows you to **run playbooks ma
 
     This opens the **Alert playbooks** panel.
 
-- **To run a playbook on an entity,**, select an entity in any of the following ways:
+- **To run a playbook on an entity,** select an entity in any of the following ways:
     - From the **Entities** tab of an incident, choose an entity from the list and select the **Run playbook (Preview)** link at the end of its line in the list.
     - From the **Investigation graph**, select an entity and select the **Run playbook (Preview)** button in the entity side panel.
     - From **Entity behavior**, select an entity and from the entity page, select the **Run playbook (Preview)** button in the left-hand panel.

articles/sentinel/media/tutorial-respond-threats-playbook/entity-trigger-types-standard.png

@@ -11,13 +11,21 @@ ms.date: 12/07/2022
 
 This article shows you how to take response actions against threat actors on the spot, during the course of an incident investigation or threat hunt, without pivoting or context switching out of the investigation or hunt. You accomplish this using playbooks based on the new entity trigger.
 
+The entity trigger currently supports the following entity types:
+- [Account](entities-reference.md#user-account)
+- [Host](entities-reference.md#host)
+- [IP](entities-reference.md#ip-address)
+- [URL](entities-reference.md#url)
+- [DNS](entities-reference.md#domain-name)
+- [FileHash](entities-reference.md#file-hash)
+
 > [!IMPORTANT]
 >
 > The **entity trigger** 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.
 
 ## Run playbooks with the entity trigger
 
-When you're investigating an incident, and you determine that a given entity - a user account, a host, an IP address, a file, and so on - represents a threat, you can take immediate remediation actions on that threat by running a playbook on-demand. You can do likewise if you encounter risky entities while proactively hunting for threats outside the context of incidents. 
+When you're investigating an incident, and you determine that a given entity - a user account, a host, an IP address, a file, and so on - represents a threat, you can take immediate remediation actions on that threat by running a playbook on-demand. You can do likewise if you encounter suspicious entities while proactively hunting for threats outside the context of incidents.
 
 1. Select the entity in whichever context you encounter it, and choose the appropriate means to run a playbook, as follows:
     - In the **Entities** tab of an incident, choose the entity from the list and select the **Run playbook (Preview)** link at the end of its line in the list.
@@ -42,8 +50,10 @@ When you're investigating an incident, and you determine that a given entity - a
 
 1. In the **Playbooks** tab, you'll see a list of all the playbooks that you have access to and that use the **Microsoft Sentinel Entity** trigger for that entity type (in this case, user accounts). Select the **Run** button for the playbook you want to run it immediately.
 
-1. You can audit the activity of your entity-trigger playbooks in the **Runs** tab. You'll see a list of all the times any playbook has been run on the entity you selected. It might take a few seconds for any just-completed run to appear in this list. Selecting a specific run will open the full run log in Azure Logic Apps.
+   > [!NOTE]
+   > If you don't see the playbook you want to run in the list, it means Microsoft Sentinel doesn't have permissions to run playbooks in that resource group ([learn more](tutorial-respond-threats-playbook.md#explicit-permissions)). To grant those permissions, select **Settings** from the main menu, choose the **Settings** tab, expand the **Playbook permissions** expander, and select **Configure permissions**. In the **Manage permissions** panel that opens up, mark the check boxes of the resource groups containing the playbooks you want to run, and select **Apply**.
 
+1. You can audit the activity of your entity-trigger playbooks in the **Runs** tab. You'll see a list of all the times any playbook has been run on the entity you selected. It might take a few seconds for any just-completed run to appear in this list. Selecting a specific run will open the full run log in Azure Logic Apps.
 
 
 ## Next steps

articles/sentinel/media/tutorial-respond-threats-playbook/entity-trigger-types.png

@@ -25,6 +25,8 @@ Use Azure RBAC to create and assign roles within your security operations team t
 
 - [Microsoft Sentinel Contributor](../role-based-access-control/built-in-roles.md#microsoft-sentinel-contributor) can, in addition to the above, create and edit workbooks, analytics rules, and other Microsoft Sentinel resources.
 
+- [Microsoft Sentinel Playbook Operator](../role-based-access-control/built-in-roles.md#microsoft-sentinel-playbook-operator) can list, view, and manually run playbooks.
+
 - [Microsoft Sentinel Automation Contributor](../role-based-access-control/built-in-roles.md#microsoft-sentinel-automation-contributor) allows Microsoft Sentinel to add playbooks to automation rules. It isn't meant for user accounts.
 
 > [!NOTE]
@@ -39,7 +41,7 @@ Users with particular job requirements may need to be assigned other roles or sp
 
 - **Working with playbooks to automate responses to threats**
 
-    Microsoft Sentinel uses **playbooks** for automated threat response. Playbooks are built on **Azure Logic Apps**, and are a separate Azure resource. For specific members of your security operations team, you might want to assign the ability to use Logic Apps for Security Orchestration, Automation, and Response (SOAR) operations. You can use the [Logic App Contributor](../role-based-access-control/built-in-roles.md#logic-app-contributor) role to assign explicit permission for using playbooks.
+    Microsoft Sentinel uses **playbooks** for automated threat response. Playbooks are built on **Azure Logic Apps**, and are a separate Azure resource. For specific members of your security operations team, you might want to assign the ability to use Logic Apps for Security Orchestration, Automation, and Response (SOAR) operations. You can use the [Microsoft Sentinel Playbook Operator](../role-based-access-control/built-in-roles.md#microsoft-sentinel-playbook-operator) role to assign explicit, limited permission for running playbooks, and the [Logic App Contributor](../role-based-access-control/built-in-roles.md#logic-app-contributor) role to create and edit playbooks.
 
 - **Giving Microsoft Sentinel permissions to run playbooks**
 
@@ -73,12 +75,13 @@ For example, a user assigned the **Microsoft Sentinel Reader** role, but not the
 
 This table summarizes the Microsoft Sentinel roles and their allowed actions in Microsoft Sentinel.
 
-| Role | Create and run playbooks| Create and edit analytics rules, workbooks, and other Microsoft Sentinel resources | Manage incidents (dismiss, assign, etc.) | View data, incidents, workbooks, and other Microsoft Sentinel resources |
-|---|---|---|---|---|
-| Microsoft Sentinel Reader | -- | --[*](#workbooks) | -- | ✓ |
-| Microsoft Sentinel Responder | -- | --[*](#workbooks) | ✓ | ✓ |
-| Microsoft Sentinel Contributor | -- | ✓ | ✓ | ✓ |
-| Microsoft Sentinel Contributor + Logic App Contributor | ✓ | ✓ | ✓ | ✓ |
+| Role | View and run playbooks | Create and edit playbooks | Create and edit analytics rules, workbooks, and other Microsoft Sentinel resources | Manage incidents (dismiss, assign, etc.) | View data, incidents, workbooks, and other Microsoft Sentinel resources |
+|---|---|---|---|---|---|
+| Microsoft Sentinel Reader | -- | -- | --[*](#workbooks) | -- | ✓ |
+| Microsoft Sentinel Responder | -- | -- | --[*](#workbooks) | ✓ | ✓ |
+| Microsoft Sentinel Contributor | -- | -- | ✓ | ✓ | ✓ |
+| Microsoft Sentinel Playbook Operator | ✓ | -- | -- | -- | -- |
+| Logic App Contributor | ✓ | ✓ | -- | -- | -- |
 
 
 <a name=workbooks></a>* Users with these roles can create and delete workbooks with the [Workbook Contributor](../role-based-access-control/built-in-roles.md#workbook-contributor) role. Learn about [Other roles and permissions](#other-roles-and-permissions).
@@ -101,10 +104,10 @@ Review the [role recommendations](#role-and-permissions-recommendations) for whi
 
 After understanding how roles and permissions work in Microsoft Sentinel, you can review these best practices for applying roles to your users:
 
-|User type  |Role |Resource group  |Description  |
-|---------|---------|---------|---------|
-|**Security analysts**     | [Microsoft Sentinel Responder](../role-based-access-control/built-in-roles.md#microsoft-sentinel-responder)        | Microsoft Sentinel's resource group        | View data, incidents, workbooks, and other Microsoft Sentinel resources. <br><br>Manage incidents, such as assigning or dismissing incidents.        |
-|     | [Logic Apps Operator](../role-based-access-control/built-in-roles.md#logic-app-operator)        | Microsoft Sentinel's resource group, or the resource group where your playbooks are stored        | Attach playbooks to analytics and automation rules. <br>Run playbooks.        |
+| User type  | Role | Resource group  | Description  |
+| --------- | --------- | --------- | --------- |
+| **Security analysts**     | [Microsoft Sentinel Responder](../role-based-access-control/built-in-roles.md#microsoft-sentinel-responder)        | Microsoft Sentinel's resource group        | View data, incidents, workbooks, and other Microsoft Sentinel resources. <br><br>Manage incidents, such as assigning or dismissing incidents.        |
+|     | [Microsoft Sentinel Playbook Operator](../role-based-access-control/built-in-roles.md#microsoft-sentinel-playbook-operator)        | Microsoft Sentinel's resource group, or the resource group where your playbooks are stored        | Attach playbooks to analytics and automation rules. <br>Run playbooks.        |
 |**Security engineers**     | [Microsoft Sentinel Contributor](../role-based-access-control/built-in-roles.md#microsoft-sentinel-contributor)       |Microsoft Sentinel's resource group         |   View data, incidents, workbooks, and other Microsoft Sentinel resources. <br><br>Manage incidents, such as assigning or dismissing incidents. <br><br>Create and edit workbooks, analytics rules, and other Microsoft Sentinel resources.      |
 |     | [Logic Apps Contributor](../role-based-access-control/built-in-roles.md#logic-app-contributor)        | Microsoft Sentinel's resource group, or the resource group where your playbooks are stored        | Attach playbooks to analytics and automation rules. <br>Run and modify playbooks.         |
 |  **Service Principal**   | [Microsoft Sentinel Contributor](../role-based-access-control/built-in-roles.md#microsoft-sentinel-contributor)      |  Microsoft Sentinel's resource group       | Automated configuration for management tasks |

articles/sentinel/media/tutorial-respond-threats-playbook/sentinel-triggers.png

@@ -80,7 +80,7 @@ Follow these steps to create a new playbook in Microsoft Sentinel:
 
     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** or **Playbook with alert trigger**. Then, continue following the steps in the **Logic Apps Consumption** 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.
@@ -120,6 +120,10 @@ Regardless of which trigger you chose to create your playbook with in the previo
 
     :::image type="content" source="media/tutorial-respond-threats-playbook/logic-app-blank-LAC.png" alt-text="Screenshot of logic app designer screen with opening trigger." lightbox="media/tutorial-respond-threats-playbook/logic-app-blank-LAC.png":::
 
+    If you chose the **Microsoft Sentinel entity (Preview)** trigger, select the type of entity you want this playbook to receive as an input.
+
+    :::image type="content" source="media/tutorial-respond-threats-playbook/entity-trigger-types.png" alt-text="Screenshot of drop-down list of entity types to choose from to set playbook schema.":::
+
 # [Logic Apps Standard](#tab/LAS)
 
 ### Prepare the Logic App and workflow
@@ -198,22 +202,24 @@ Since you selected **Blank playbook**, a new browser tab will open and take you
 
 1. Select the **Azure** tab and enter "Sentinel" in the Search line.
 
-1. In the **Triggers** tab below, you will see the two triggers offered by Microsoft Sentinel:
+1. In the **Triggers** tab below, you will see the three triggers offered by Microsoft Sentinel:
     - Microsoft Sentinel alert (preview)
+    - Microsoft Sentinel entity (preview)
     - Microsoft Sentinel incident (preview)
 
    Select the trigger that matches the type of playbook you are creating.
 
-    > [!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)
-
     :::image type="content" source="./media/tutorial-respond-threats-playbook/sentinel-triggers.png" alt-text="Choose a trigger for your playbook":::
 
+    If you chose the **Microsoft Sentinel entity (Preview)** trigger, select the type of entity you want this playbook to receive as an input.
+
+    :::image type="content" source="media/tutorial-respond-threats-playbook/entity-trigger-types-standard.png" alt-text="Screenshot of drop-down list of entity types to choose from to set playbook schema.":::
+
 > [!NOTE]
 > When you choose a trigger, or any subsequent action, you will be asked to authenticate to whichever resource provider you are interacting with. In this case, the provider is Microsoft Sentinel. There are a few different approaches you can take to authentication. For details and instructions, see [**Authenticate playbooks to Microsoft Sentinel**](authenticate-playbooks-to-sentinel.md).
 
+For more about which trigger to use, see [**Use triggers and actions in Microsoft Sentinel playbooks**](playbook-triggers-actions.md)
+
 
 ---
 

articles/sentinel/respond-threats-during-investigation.md

@@ -4,7 +4,7 @@ description: This article describes new features in Microsoft Sentinel from the
 author: yelevin
 ms.author: yelevin
 ms.topic: conceptual
-ms.date: 09/06/2022
+ms.date: 12/08/2022
 ms.custom: ignite-fall-2021
 ---
 
@@ -18,8 +18,20 @@ The listed features were released in the last three months. For information abou
 
 ## December 2022
 
+- [Create and run playbooks on entities on-demand (Preview)](#create-and-run-playbooks-on-entities-on-demand-preview)
 - [Customize more alert properties (Preview)](#customize-more-alert-properties-preview)
 
+### Create and run playbooks on entities on-demand (Preview)
+
+SOC analysts can now take immediate action on a particular entity representing a threat actor, while in the middle of investigating an incident or hunting for threats, without leaving those contexts or having to pivot to other screens or apps. 
+
+Similarly, SOC engineers can now encapsulate a series of automated actions in workflows that run on a specific entity, so that analysts can use these workflows in the scenarios above.
+
+These improvements for SOC efficiency and productivity are thanks to the **new entity trigger for playbooks**.
+
+Learn more about [running playbooks on entities on-demand](respond-threats-during-investigation.md).
+Learn more about [creating playbooks based on the entity trigger](tutorial-respond-threats-playbook.md#create-a-playbook).
+
 ### Customize more alert properties (Preview)
 
 Alerts generated by a given analytics rule - and all incidents created as a result - inherit the name, description, severity, and tactics defined in the rule, without regard to the particular content of a specific instance of the alert.