Edit

Share via

Create and publish playbooks for Microsoft Sentinel solutions

Playbooks in Microsoft Sentinel are sets of procedures that can respond to incidents, alerts, or specific entities. They help automate responses and can be set to run automatically when certain alerts or incidents occur. Playbooks can also be run manually.

This article uses example scenarios to walk you through the process of creating and publishing playbooks for Microsoft Sentinel solutions.

Use cases for Microsoft Sentinel playbooks

Due to the growing number of alerts and incidents, security operations center (SOC) analysts can't manually handle everything. To maximize the benefits of Microsoft Sentinel, it's crucial to determine which automations help SOC analysts with each detection in your solution. Here are some of the common scenarios for playbooks:

  • Incident enrichment: Enhance alerts with additional information for efficient investigation and resolution. Example: Collect more data on IP addresses associated with an incident.
  • Sync with ticketing systems: Synchronize Microsoft Sentinel incidents with other systems (like ServiceNow) bidirectionally. Example: On incident creation, sync details with a ServiceNow ticket. For more information, see the ServiceNow connector reference.
  • Automated response: Take automated actions in response to suspicious activities. Example: Send a Teams message to the user for confirmation if a suspicious action is detected.

To understand more about potential use cases for playbooks, see Recommended playbook use cases, templates, and examples.

Create and publish playbooks for example scenarios

Microsoft Sentinel playbooks are based on Azure Logic Apps, a cloud platform that enables the creation and execution of automated workflows with minimal to no coding. You can use the visual designer and select prebuilt operations to efficiently build workflows that integrate and manage your applications, data, services, and systems. For more information, see What is Azure Logic Apps?.

Logic Apps includes numerous out-of-the-box connectors, such as Salesforce, Office 365, and SQL Server. These connectors offer no-code options for various functions. For example, the Office 365 Outlook connector includes built-in actions for sending emails without needing any code. If the out-of-the-box connectors don't cover specific actions that a playbook requires, you need to create a custom connector.

Scenario: Playbook that uses built-in connectors

Create the playbook

If your playbook doesn't require any custom actions outside the actions that the built-in connectors already provide, you can use the Logic Apps UI in Microsoft Sentinel to create the playbook. No other code is required.

For detailed instructions on how to create playbooks from the Azure portal or the Microsoft Defender portal, see Create and manage Microsoft Sentinel playbooks.

Generate the ARM template for the playbook

On the Code view tab of the Logic Apps editor, you can access the JSON Azure Resource Manager template (ARM template). Remove any organizational details, like tenant ID and subscription info, for privacy and security. Follow these steps to get a sanitized version of your playbook ARM template:

  1. Download the PowerShell script.

  2. Extract the folder and open playbook_ARM_Template_Generator.ps1 in Visual Studio Code, Windows PowerShell, or PowerShell Core.

    Note

    Run the script from your machine. Allow PowerShell script execution by running this command in PowerShell: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass.

  3. Enter your Azure tenant ID when you're prompted.

  4. Authenticate with your credentials, and then select Subscription > playbooks.

  5. Select a location on your local drive to save the sanitized ARM template as azuredeploy.json. The tool converts Microsoft Sentinel connections to Microsoft Software Installer (MSI) during export. For more information, see the demonstration video Export your SOAR playbooks with ease.

  6. Update the metadata section of the azuredeploy.json file with your playbook's specific details.

    Screenshot of playbook metadata that needs to be updated.

  7. We recommend that you use a managed service identity rather than a user-assigned identity for connecting Azure services (such as Microsoft Sentinel, Azure Key Vault, and Azure Storage) with playbooks. Update the authentication type under connectionProperties to "ManagedServiceIdentity".

    Screenshot of playbook identity updates.

  8. Update Microsoft.Web/connections resources.

    Screenshot of playbook web connections metadata.

For more information, see the azuredeploy.json file on GitHub.

Scenario: Playbook that uses custom connectors

Custom connectors extend Azure Logic Apps by integrating with APIs or services that built-in connectors don't cover. They're useful for connecting your logic apps to specific use cases, such as:

  • Internal APIs within your organization.
  • Third-party services that Azure doesn't directly support.
  • Custom-built applications with a REST or SOAP API.

For more information, see Custom connectors overview.

Create the playbook

To create a custom connector, describe the API so that the connector understands its operations and data structures. This example uses an OpenAPI definition for the Cognitive Services Text Analytics Sentiment API. For more information on creating custom connectors, see Create a custom connector from an OpenAPI definition.

After you create the custom connector, you can use it to build a playbook by using Azure Logic Apps. For step-by-step instructions on how to use custom connectors in a playbook, see Use a custom connector in a logic app workflow.

Generate the ARM template for the playbook

On the Code view tab of the Azure Logic Apps editor, you can access the JSON ARM template. Remove any organizational details, like tenant ID and subscription info, for privacy and security. Follow these steps to get a sanitized version of your playbook ARM template:

  1. Download the PowerShell script.

  2. Extract the folder and open playbook_ARM_Template_Generator.ps1 in Visual Studio Code, Windows PowerShell, or PowerShell Core.

    Note

    Run the script from your machine. Allow PowerShell script execution by running this command in PowerShell: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass.

  3. Enter your Azure tenant ID when you're prompted.

  4. Authenticate with your credentials, and then select Subscription > playbooks.

  5. Select a location on your local drive to save the sanitized ARM template as azuredeploy.json. The tool converts Microsoft Sentinel connections to MSI during export. For more information, see the demonstration video Export your SOAR playbooks with ease.

  6. Update the metadata section of the azuredeploy.json file with your playbook's specific details.

    Screenshot of playbook metadata that needs to be updated.

  7. We recommend that you use a managed service identity rather than a user-assigned identity for connecting Azure services (such as Microsoft Sentinel, Azure Key Vault, and Azure Storage) with playbooks. Update the authentication type under connectionProperties to "ManagedServiceIdentity".

    Screenshot of playbook identity updates.

  8. Update Microsoft.Web/connections resources.

    Screenshot of playbook web connections metadata.

For more information, see the azuredeploy.json file on GitHub.

Generate the ARM template for the Logic Apps custom connector

  1. Go to the Azure portal.

  2. Search for Logic Apps Custom Connector.

  3. Open the connector. Under Automation, select Export template.

    Screenshot that shows a template to export.

  4. Select Copy template and save the contents in a JSON file on your local computer.

  5. In the JSON that you created in step 4, remove the runtimeUrls, apiDefinitions, and wsdlDefinition fields.

  6. Select Overview, and then select Download. This step downloads the file that contains Swagger attributes.

    Screenshot of selections for downloading a Swagger file.

  7. Update the JSON file that you created in step 4 with the swagger and backendService values that you obtained from the Swagger file that you downloaded in step 6.

  8. Validate the host, basePath, and schemes parameters in the Swagger file, and update them as needed.

    Screenshot that shows Swagger fields.

  9. Update the parameters section of the ARM template file for the custom connector.

    Screenshot that shows updated parameters.

For reference or comparison to determine which other fields you need to modify in the ARM template, see the azuredeploy.json file on GitHub.

Directory structure for playbook and custom connector contributions

Before you make a pull request to the Microsoft Sentinel GitHub repo, follow the proper directory structure. The ARM template file must be named azuredeploy.json. Also include a Readme.md file for all custom connectors and playbooks, to detail configuration steps during and after deployment.

Here are Readme.md file references:

Screenshot of the playbook folder structure in GitHub.