Tutorial: Use playbooks with automation rules in Microsoft Sentinel

Note

Azure Sentinel is now called Microsoft Sentinel, and we’ll be updating these pages in the coming weeks. Learn more about recent Microsoft security enhancements.

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:

  • Create an automation rule
  • Create a playbook
  • Add actions to a playbook
  • Attach a playbook to an automation rule or an analytics rule to automate threat response

Note

This tutorial provides basic guidance for a top customer task: creating automation to triage incidents. For more information, see our How-to section, such as Automate threat response with playbooks in Microsoft Sentinel and Use triggers and actions in Microsoft Sentinel playbooks.

What are automation rules and playbooks?

Automation rules help you triage incidents in Microsoft Sentinel. You can use them to automatically assign incidents to the right personnel, close noisy incidents or known false positives, change their severity, and add tags. They are also the mechanism by which you can run playbooks in response to incidents.

Playbooks are collections of procedures that can be run from Microsoft Sentinel in response to an alert or incident. A playbook can help automate and orchestrate your response, and can be set to run automatically when specific alerts or incidents are generated, by being attached to an analytics rule or an automation rule, respectively. It can also be run manually on-demand.

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. Each playbook is created for the specific subscription to which it belongs, but the Playbooks display shows you all the playbooks available across any selected subscriptions.

Note

Because playbooks make use of Azure Logic Apps, additional charges may apply. Visit the Azure Logic Apps pricing page for more details.

For example, if you want to stop potentially compromised users from moving around your network and stealing information, you can create an automated, multifaceted response to incidents generated by rules that detect compromised users. You start by creating a playbook that takes the following actions:

  1. When the playbook is called by an automation rule passing it an incident, the playbook opens a ticket in ServiceNow or any other IT ticketing system.

  2. It sends a message to your security operations channel in Microsoft Teams or Slack to make sure your security analysts are aware of the incident.

  3. It also sends all the information in the incident in an email message to your senior network admin and security admin. The email message will include Block and Ignore user option buttons.

  4. The playbook waits until a response is received from the admins, then continues with its next steps.

  5. If the admins choose Block, it sends a command to Azure AD to disable the user, and one to the firewall to block the IP address.

  6. If the admins choose Ignore, the playbook closes the incident in Microsoft Sentinel, and the ticket in ServiceNow.

In order to trigger the playbook, you'll then create an automation rule that runs when these incidents are generated. That rule will take these steps:

  1. The rule changes the incident status to Active.

  2. It assigns the incident to the analyst tasked with managing this type of incident.

  3. It adds the "compromised user" tag.

  4. Finally, it calls the playbook you just created. (Special permissions are required for this step.)

Playbooks can be run automatically in response to incidents, by creating automation rules that call the playbooks as actions, as in the example above. They can also be run automatically in response to alerts, by telling the analytics rule to automatically run one or more playbooks when the alert is generated.

You can also choose to run a playbook manually on-demand, as a response to a selected alert.

Get a more complete and detailed introduction to automating threat response using automation rules and playbooks in Microsoft Sentinel.

Important

  • Automation rules, and the use of the incident trigger for playbooks, are currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Create a playbook

Follow these steps to create a new playbook in Microsoft Sentinel:

Prepare the playbook and Logic App

  1. From the Microsoft Sentinel navigation menu, select Automation.

  2. On the top menu, select Create and Add new playbook.

    Add a new playbook

    A new browser tab will open and take you to the Create a logic app wizard.

    Create a logic app

  3. Enter your Subscription and Resource group, and give your playbook a name under Logic app name.

  4. For Region, select the Azure region where your Logic App information is to be stored.

  5. If you want to monitor this playbook's activity for diagnostic purposes, mark the Enable log analytics check box, and enter your Log Analytics workspace name.

  6. If you want to apply tags to your playbook, click Next : Tags > (not connected to tags applied by automation rules. Learn more about tags). Otherwise, click Review + Create. Confirm the details you provided, and click Create.

  7. While your playbook is being created and deployed (this will take a few minutes), you will be taken to a screen called Microsoft.EmptyWorkflow. When the "Your deployment is complete" message appears, click Go to resource.

  8. You will be taken to your new playbook's Logic Apps Designer, where you can start designing the workflow. You'll see a screen with a short introductory video and some commonly used Logic App triggers and templates. Learn more about creating a playbook with Logic Apps.

  9. Select the Blank Logic App template.

    Logic Apps Designer template gallery

Choose the trigger

Every playbook must start with a trigger. The trigger defines the action that will start the playbook and the schema that the playbook will expect to receive.

  1. In the search bar, look for Microsoft Sentinel. Select Microsoft Sentinel when it appears in the results.

  2. In the resulting Triggers tab, you will see the two triggers offered by Microsoft Sentinel:

    • When a response to a Microsoft Sentinel Alert is triggered
    • When Microsoft Sentinel incident creation rule was triggered

    Choose 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 and can also be run manually.

    For more about which trigger to use, see Use triggers and actions in Microsoft Sentinel playbooks

    Choose a trigger for your playbook

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.

Add actions

Now you can define what happens when you call the playbook. You can add actions, logical conditions, loops, or switch case conditions, all by selecting New step. This selection opens a new frame in the designer, where you can choose a system or an application to interact with or a condition to set. Enter the name of the system or application in the search bar at the top of the frame, and then choose from the available results.

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 entities involved. From the Expression menu, you can choose from a large library of functions to add additional logic to your steps.

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. 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.

Automate threat responses

You've created your playbook and defined the trigger, set the conditions, and prescribed the actions that it will take and the outputs it will produce. Now you need to determine the criteria under which it will run and set up the automation mechanism that will run it when those criteria are met.

Respond to incidents

You use a playbook to respond to an incident by creating an automation rule that will run when the incident is generated, and in turn it will call the playbook.

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.

    Add a new rule

  2. The Create new automation rule panel opens. Enter a name for your rule.

    Create an automation rule

  3. 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.

  4. Add any other conditions you want this automation rule's activation to depend on. Click Add condition and choose conditions from the drop-down list. The list of conditions is populated by alert detail and entity identifier fields.

  5. Choose the actions you want this automation rule to take. Available actions include Assign owner, Change status, Change severity, Add tags, and Run playbook. You can add as many actions as you like.

  6. If you add a Run playbook action, you will be prompted to choose from the drop-down list of available playbooks. Only playbooks that start with the incident trigger can be run from automation rules, so only they will appear in the list.

    Important

    Microsoft Sentinel must be granted explicit permissions in order to run playbooks from automation rules. If a playbook appears "grayed out" in the drop-down list, it means Sentinel does not have permission to that playbook's resource group. Click the Manage playbook permissions link to assign 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 click Apply. Manage permissions

    • You yourself must have owner permissions on any resource group to which you want to grant Microsoft Sentinel permissions, and you must have the Logic App Contributor role on any resource group containing playbooks you want to run.

    • In a multi-tenant deployment, if the playbook you want to run is in a different tenant, you must grant Microsoft Sentinel permission to run the playbook in the playbook's tenant.

      1. From the Microsoft Sentinel navigation menu in the playbooks' tenant, select Settings.
      2. In the Settings blade, select the Settings tab, then the Playbook permissions expander.
      3. Click the Configure permissions button to open the Manage permissions panel mentioned above, and continue as described there.
    • If, in an MSSP scenario, you want to run a playbook in a customer tenant from an automation rule created while signed into the service provider tenant, you must grant Microsoft Sentinel permission to run the playbook in both tenants. In the customer tenant, follow the instructions for the multi-tenant deployment in the preceding bullet point. In the service provider tenant, you must add the Azure Security Insights app in your Azure Lighthouse onboarding template:

      1. From the Azure Portal go to Azure Active Directory.
      2. Click on Enterprise Applications.
      3. Select Application Type and filter on Microsoft Applications.
      4. In the search box type Azure Security Insights.
      5. Copy the Object ID field. You will need to add this additional authorization to your existing Azure Lighthouse delegation.

      The Microsoft Sentinel Automation Contributor role has a fixed GUID which is f4c81013-99ee-4d62-a7ee-b3f1f648599a. A sample Azure Lighthouse authorization would look like this in your parameters template:

      {
           "principalId": "<Enter the Azure Security Insights app Object ID>", 
           "roleDefinitionId": "f4c81013-99ee-4d62-a7ee-b3f1f648599a",
           "principalIdDisplayName": "Microsoft Sentinel Automation Contributors" 
      }
      
  7. Set an expiration date for your automation rule if you want it to have one.

  8. Enter a number under Order to determine where in the sequence of automation rules this rule will run.

  9. Click Apply. You're done!

Discover other ways to create automation rules.

Respond to alerts

You use a playbook to respond to an alert by creating an analytics rule, or editing an existing one, that runs when the alert is generated, and selecting your playbook as an automated response in the analytics rule wizard.

  1. From the Analytics blade in the Microsoft Sentinel navigation menu, select the analytics rule for which you want to automate the response, and click Edit in the details pane.

  2. In the Analytics rule wizard - Edit existing rule page, select the Automated response tab.

    Automated response tab

  3. Choose your playbook from the drop-down list. You can choose more than one playbook, but only playbooks using the alert trigger will be available.

  4. In the Review and create tab, select Save.

Run a playbook on demand

You can also run a playbook on demand.

Note

Only playbooks using the alert trigger can be run on-demand.

To run a playbook on-demand:

  1. In the Incidents page, select an incident and click on View full details.

  2. In the Alerts tab, click on the alert you want to run the playbook on, and scroll all the way to the right and click View playbooks and select a playbook to run from the list of available playbooks on the subscription.

Next steps

In this tutorial, you learned how to use playbooks and automation rules in Microsoft Sentinel to respond to threats.