Create and manage Microsoft Sentinel playbooks
Playbooks are collections of procedures that can be run from Microsoft Sentinel in response to an entire incident, to an individual alert, or to a specific entity. A playbook can help automate and orchestrate your response, and can be attached to an automation rule to run automatically when specific alerts are generated or when incidents are created or updated. Playbooks can also be run manually on-demand on specific incidents, alerts, or entities.
This article describes how to create and manage Microsoft Sentinel playbooks. You can later attach these playbooks to analytics rules or automation rules, or run them manually on specific incidents, alerts, or entities.
Note
Playbooks in Microsoft Sentinel are based on workflows built in Azure Logic Apps, which means that you get all the power, customizability, and built-in templates of logic apps. Additional charges may apply. For pricing information, visit the Azure Logic Apps pricing page.
Important
Microsoft Sentinel is now generally available within the Microsoft unified security operations platform in the Microsoft Defender portal. For more information, see Microsoft Sentinel in the Microsoft Defender portal.
Prerequisites
An Azure account and subscription. If you don't have a subscription, sign up for a free Azure account.
To create and manage playbooks, you need access to Microsoft Sentinel with one of the following Azure roles:
Logic app Azure roles Description Consumption Logic App Contributor Edit and manage logic apps. Consumption Logic App Operator Read, enable, and disable logic apps. Standard Logic Apps Standard Operator Enable, resubmit, and disable workflows. Standard Logic Apps Standard Developer Create and edit workflows. Standard Logic Apps Standard Contributor Manage all aspects of a workflow. For more information, see the following documentation:
Before you create your playbook, we recommend that you read Azure Logic Apps for Microsoft Sentinel playbooks.
Create a playbook
Follow these steps to create a new playbook in Microsoft Sentinel:
In the Azure portal or in the Defender portal, go to your Microsoft Sentinel workspace. On the workspace menu, under Configuration, select Automation.
From the top menu, select Create, and then select one of the following options:
If you're creating a Consumption playbook, select one of the following options, depending on the trigger you want to use, and then follow the steps for a Consumption logic app:
- Playbook with incident trigger
- Playbook with alert trigger
- Playbook with entity trigger
This guide continues with the Playbook with entity trigger.
If you're creating a Standard playbook, select Blank playbook and then follow the steps for the Standard logic app type.
For more information, see Supported logic app types and Supported triggers and actions in Microsoft Sentinel playbooks.
Prepare your playbook's logic app
Select one of the following tabs for details about how to create a logic app for your playbook, depending on whether you're using a Consumption or Standard logic app. For more information, see Supported logic app types.
Tip
If your playbooks need access to protected resources that are inside or connected to an Azure virtual network, create a Standard logic app workflow.
Standard workflows run in single-tenant Azure Logic Apps and support using private endpoints for inbound traffic so that your workflows can communicate privately and securely with virtual networks. Standard workflows also support virtual network integration for outbound traffic. For more information, see Secure traffic between virtual networks and single-tenant Azure Logic Apps using private endpoints.
After you select the trigger, which includes an incident, alert, or entity trigger, the Create playbook wizard appears, for example:
Follow these steps to create your playbook:
On the Basics tab, provide the following information:
For Subscription and Resource group, select the values you want from their respective lists.
The Region value is set to the same region as the associated Log Analytics workspace.
For Playbook name, enter a name for your playbook.
To monitor this playbook's activity for diagnostic purposes, select Enable diagnostics logs in Log Analytics, and then select a Log Analytics workspace unless you already selected a workspace.
Select Next : Connections >.
On the Connections tab, we recommend leaving the default values, which configure a logic app to connect to Microsoft Sentinel with a managed identity.
For more information, see Authenticate playbooks to Microsoft Sentinel.
To continue, select Next : Review and create >.
On the Review and create tab, review your configuration choices, and select Create playbook.
Azure takes a few minutes to create and deploy your playbook. After deployment completes, your playbook opens in the Consumption workflow designer for Azure Logic Apps. The trigger that you selected earlier automatically appears as the first step in your workflow, so now you can continue building the workflow from here.
On the designer, select the Microsoft Sentinel trigger, if not already selected.
On the Create connection pane, follow these steps to provide the required information to connect to Microsoft Sentinel.
For Authentication, select from the following methods, which affect subsequent connection parameters:
Method Description OAuth Open Authorization (OAuth) is a technology standard that lets you authorize an app or service to sign in to another without exposing private information, such as passwords. OAuth 2.0 is the industry protocol for authorization and grants limited access to protected resources. For more information, see the following resources:
- What is OAuth?
- OAuth 2.0 authorization with Microsoft Entra IDService principal A service principal represents an entity that requires access to resources that are secured by a Microsoft Entra tenant. For more information, see Service principal object. Managed identity An identity that is automatically managed in Microsoft Entra ID. Apps can use this identity to access resources that support Microsoft Entra authentication and to obtain Microsoft Entra tokens without having to manage any credentials.
For optimal security, Microsoft recommends using a managed identity for authentication when possible. This option provides superior security and helps keep authentication information secure so that you don't have to manage this sensitive information. For more information, see the following resources:
- What are managed identities for Azure resources?
- Authenticate access and connections to Azure resources with managed identities in Azure Logic Apps.For more information, see Authentication prompts.
Based on your selected authentication option, provide the necessary parameter values for the corresponding option.
For more information about these parameters, see Microsoft Sentinel connector reference.
For Tenant ID, select your Microsoft Entra tenant ID.
When you finish, select Sign in.
If you previously chose Playbook with entity trigger, select the type of entity you want this playbook to receive as an input.
Authentication prompts
When you add a trigger or subsequent action that requires authentication, you might be prompted to choose from the available authentication types supported by the corresponding resource provider. In this example, a Microsoft Sentinel trigger is the first operation that you add to your workflow. So, the resource provider is Microsoft Sentinel, which supports several authentication options. For more information, see the following documentation:
- Authenticate playbooks to Microsoft Sentinel
- Supported triggers and actions in Microsoft Sentinel playbooks
Add actions to your playbook
Now that you have a workflow for your playbook, define what happens when you call the playbook. Add actions, logical conditions, loops, or switch case conditions, all by selecting the plus sign (+) on the designer. For more information, see Create a workflow with a trigger or action.
This selection opens the Add an action pane where you can browse or search for services, applications, systems, control flow actions, and more. After you enter your search terms or select the resource that you want, the results list shows you the available actions.
In each action, when you select inside a field, you get the following options:
Dynamic content (lightning icon): Choose from a list of available outputs from the preceding actions in the workflow, including the Microsoft Sentinel trigger. For example, these outputs can include the attributes of an alert or incident that was passed to the playbook, including the values and attributes of all the mapped entities and custom details in the alert or incident. You can add references to the current action by selecting these outputs.
For examples that show using dynamic content, see the following sections:
Expression editor (function icon): Choose from a large library of functions to add more logic to your workflow.
For more information, see Supported triggers and actions in Microsoft Sentinel playbooks.
Dynamic content: Entity playbooks with no incident ID
Playbooks created with the Microsoft Sentinel entity trigger often use the Incident ARM ID field, for example, to update an incident after taking action on the entity. If such a playbook is triggered in a scenario that's unconnected to an incident, such as when threat hunting, there's no incident ID to populate this field. Instead, the field is populated with a null value. As a result, the playbook might fail to run to completion.
To prevent this failure, we recommend that you create a condition that checks for a value in the incident ID field before the workflow takes any other actions. You can prescribe a different set of actions to take if the field has a null value, due to the playbook not being run from an incident.
In your workflow, preceding the first action that refers to the Incident ARM ID field, follow these general steps to add a Condition action.
In the Condition pane, on the condition row, select the left Choose a value field, and then select the dynamic content option (lightning icon).
From the dynamic content list, under Microsoft Sentinel incident, use the search box to find and select Incident ARM ID.
Tip
If the output doesn't appear in the list, next to the trigger name, select See more.
In the middle field, from the operator list, select is not equal to.
In the right Choose a value field, and select the expression editor option (function icon).
In the editor, enter null, and select Add.
When you finish, your condition looks similar to the following example:
Dynamic content: Work with custom details
In the Microsoft Sentinel incident trigger, the Alert custom details output is an array of JSON objects where each represents a custom detail from an alert. Custom details are key-value pairs that let you surface information from events in the alert so they can be represented, tracked, and analyzed as part of the incident.
This field in the alert is customizable, so its schema depends on the type of event that is surfaced. To generate the schema that determines how to parse the custom details output, provide the data from an instance of this event:
On the Microsoft Sentinel workspace menu, under Configuration, select Analytics.
Follow the steps to create or open an existing scheduled query rule or NRT query rule.
On the Set rule logic tab, expand the Custom details section, for example:
The following table provides more information about these key-value pairs:
Item Location Description Key Left column Represents the custom fields that you create. Value Right column Represents the fields from the event data that populate the custom fields. To generate the schema, provide the following example JSON code:
{ "FirstCustomField": [ "1", "2" ], "SecondCustomField": [ "a", "b" ] }The code shows the key names as arrays, and the values as items in the arrays. Values are shown as the actual values, not the column that contains the values.
To use custom fields for incident triggers, follow these steps for your workflow:
In the workflow designer, under the Microsoft Sentinel incident trigger, add the built-in action named Parse JSON.
Select inside the action's Content parameter, and select the dynamic content list option (lightning icon).
From the list, in the incident trigger section, find and select Alert Custom Details, for example:
This selection automatically adds a For each loop around Parse JSON because an incident contains an array of alerts.
In the Parse JSON information pane, select Use sample payload to generate schema, for example:
In the Enter or paste a sample JSON payload box, provide a sample payload, and select Done.
For example, you can find a sample payload by looking in Log Analytics for another instance of this alert, and then copying the custom details object, which you can find under Extended Properties. To access Log Analytics data, go either to the Logs page in the Azure portal or the Advanced hunting page in the Defender portal.
The following example shows the earlier sample JSON code:
When you finish, the Schema box now contains the generated schema based on the sample that you provided. The Parse JSON action creates custom fields that you can now use as dynamic fields with Array type in your workflow's subsequent actions.
The following example shows an array and its items, both in the schema and in the dynamic content list for a subsequent action named Compose:
Manage your playbooks
Select the Automation > Active playbooks tab to view all the playbooks you have access to, filtered by your subscription view.
After you onboard to the unified security operations platform, by default the Active playbooks tab shows a predefined filter with onboarded workspace's subscription. In the Azure portal, edit the subscriptions you're showing from the Directory + subscription menu in the global Azure page header.
While the Active playbooks tab displays all the active playbooks available across any selected subscriptions, by default a playbook can be used only within the subscription to which it belongs, unless you specifically grant Microsoft Sentinel permissions to the playbook's resource group.
The Active playbooks tab shows your playbooks with the following details:
| Column name | Description |
|---|---|
| Status | Indicates if the playbook is enabled or disabled. |
| Plan | Indicates whether the playbook uses the Standard or Consumption Azure Logic Apps resource type. Playbooks of the Standard type use the LogicApp/Workflow naming convention, which reflects how a Standard playbook represents a workflow that exists alongside other workflows in a single logic app. For more information, see Azure Logic Apps for Microsoft Sentinel playbooks. |
| Trigger kind | Indicates the trigger in Azure Logic Apps that starts this playbook: - Microsoft Sentinel Incident/Alert/Entity: The playbook is started with one of the Sentinel triggers, including incident, alert, or entity - Using Microsoft Sentinel Action: The playbook is started with a non-Microsoft Sentinel trigger but uses a Microsoft Sentinel action - Other: The playbook doesn't include any Microsoft Sentinel components - Not initialized: The playbook was created, but contains no components, neither triggers no actions. |
Select a playbook to open its Azure Logic Apps page, which shows more details about the playbook. On the Azure Logic Apps page:
- View a log of all times the playbook ran
- View run results, including successes and failures and other details
- If you have the relevant permissions, open the workflow designer in Azure Logic Apps to edit the playbook directly
Related content
After you create your playbook, attach it to rules to be triggered by events in your environment, or run your playbooks manually on specific incidents, alerts, or entities.
For more information, see: