When using workbooks in Microsoft Sentinel, it is possible to visualize and monitor your data. This helps make workbooks a popular feature, not only for reporting but also for investigating events and incidents in Microsoft Sentinel. But what if you need to react to a specific incident from the workbook itself during the investigation?
Microsoft Sentinel now supports the running of playbooks from a workbook for incidents on-demand! With this feature, you can add an option to trigger a playbook within workbooks that have an incident context. The workbook only needs to supply the incident ARM Id and Logic App workflow ARM Id. Playbooks will then input the complete incident schema, including alerts and entities. Only analysts with sufficient permissions on the incident and the playbook will be able to run it.
Running playbooks from workbooks is possible thanks to a new feature that allows SOC analysts to manually run playbooks on incidents on-demand. In addition to running playbooks on incidents while investigating them in Azure Portal, it also provides a new API endpoint which can be leveraged in workbooks.
When to use this feature:
This new API is best used when triaging or responding to incidents. Previously the flow to run playbooks while investigating an incident would be:
- Open incident page within Microsoft Sentinel to review the details.
- Go into logs to review events around entities or visit entity pages.
- Go back to the incident to review the alerts.
- View the playbooks available in each alert and click run.
With the introduction of the API, this process can now be streamlined to be more efficient. While investigating the incident, it is possible to run the playbook from:
- Incident pane with right click on incident and choosing Run playbook,
- Incident pane by selecting the incident, clicking on Actions and choosing Run playbook, or
- Incident Overview pane by clicking on Actions and choosing Run playbook.
Also, with the workbook configured, incidents, relevant logs, and playbooks can be available within one location without having to shuffle between blades. This would allow analysts to just open the workbook and have the information of interest available in order to begin investigating an incident or hunting in their data. A few examples for playbooks to run from a workbook would be:
- Confirm-AAD-RiskyUser
- Block-AAD-User
- Get-VirusTotal-Report
- Get-WhoIS-Report
- And more.
How to configure a workbook to run a playbook:
The workbook needs to use the ARM Action (in Public preview) option to call API path. This API path will then run the playbook for us! Here is the API template:
HTTP Method:
POST
API path:
Body:
{
"LogicAppsResourceId":"/subscriptions/{subscriptionId}/resourceGroups/{PlaybookResourceGroup}/providers/Microsoft.Logic/workflows/{PlaybookName}",
"TenantId":"{TenantID}"
}
You can use tools like Postman to test this API in the environment as well.
A workbook named “Run Playbook from the Workbook” is a simple example how this can be configured and used in the Microsoft Sentinel. You can use this specific workbook or use the logic to add this feature to the any existing workbook.
The template of the workbook can be found on following link.
How to deploy the template:
- Go to your Microsoft Sentinel instance, click on “Workbooks”, and then on “Add workbook”.
- Click on “Edit” and then on “Advanced Editor”.
- Replace the code with one from the link and click on “Apply”.
- Click on “Save” and save the workbook in your environment.
Walkthrough for the template workbook:
First, get a list of incidents and select the incident on which we want to run the playbook:
After that, select the playbook that will be run on the specific incident and click on Run Microsoft Sentinel Playbook:
The next step is to confirm the run of the ARM action. In the same window, POST API request details are shown.
After clicking on the Run ARM action, the selected playbook will run in the background.
Here is the example of the whole process:
How to add this feature to the existing workbook?
To edit the existing workbook in the Microsoft Sentinel environment, additional fields need to be added in that workbook.
- Open the workbook and enter edit mode.
- Click on “Add” and select “Add group”.
- In the group, click on “Add” and then on “Add parameters”.
- Configure these parameters (NOTE: if these parameters are configured earlier in the workbook, you can skip this step. If playbooks are across multiple subscriptions/resource groups – follow these steps)
- For "Playbook Resource Group" choose Resource Group where the Playbook you want to run.
- "Playbook Name" is the Playbook you want to run.
- "Trigger Name" is the trigger that will be run. Please note that only the incident trigger is supported! (Selection must be "Microsoft_Sentinel_Incident") Trigger run on alert is not supported!
- "Tenant ID" is the tenant where the Subscription is on.
- To get more info on how to get specific data, please use the template.
- Click done editing.
- In the same group, click again on “Add” and select “Add links/tabs”.
- Enter the name of the tab (“Run Microsoft Sentinel Playbook”), and from “Action” select “ARM Action (Preview)”.
- From Style select Button or Link (the outlook of the tab)
- Click on Configure under Settings and enter API details. Enter ARM path, HTTP method, and the body needed to run the Playbook. In the API path, use parameters so that it’s possible to change different playbooks that can be run.
- Click on “Save and Close” and then on “Done editing” and save the workbook.
After selecting the incident and clicking on “Run Microsoft Sentinel Playbook”, the selected playbook will run in the background.
Go on and try out this new API for running incident playbooks on demand! If you run into any issues, use the template workbook as guidance to learn and implement this new feature.
We hope you found this article useful. Please leave us your feedback and questions in the comments section.
Thanks to @Matt_Lowe and @liortamir for help in creating and testing the solutions and on blog proofreading.