This blog is part of a multi-series
Part 2: Playbooks – this blog
Part 3: Send email notification options
Part 4: Dynamic content and expressions – coming soon
Playbooks
A playbook is a collection of response and remediation actions and logic that can be run from Microsoft Sentinel as a routine. A playbook can help automate and orchestrate your threat response, integrate with other internal and external systems, and be set to run automatically in response to specific alerts or incidents triggered by an analytics rule or an automation rule. It can also be run on-demand manually from the incidents page in response to alerts.
Here are some tips & tricks that can be helpful when creating playbooks:
Run playbooks on incidents manually
Running playbooks on incidents using automation rules provides a fantastic management point. But sometimes, we need to run a playbook with incident trigger manually. With a new API endpoint, that is possible, and now you can run playbooks on the incident from the incident overview page, and you can even mark favorite ones to be on the top of the list.
More details about running playbooks on demand you can find on this blog:
What's new: run playbooks on incidents on demand - Microsoft Tech Community
Run playbooks from workbooks
With the option to run playbooks with incident trigger on-demand using a new API endpoint, we also got the possibility to use ARM action in workbooks to run incident trigger playbooks from workbooks on-demand.
To get details on how to use this functionality in workbooks, please check this blog:
Run Microsoft Sentinel playbooks from workbooks on-demand - Microsoft Tech Community
Nested playbooks - Run new playbooks as an action in the playbook
Using the same API endpoint in running incident trigger playbooks from workbooks, we can run the playbook as an action in the existing playbook. To make it work, the first playbook must have the Logic App Contributor role assigned to the service principal or managed identity used to authorize HTTP action.
HTTP Method:
POST
API path:
https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/incidents/{incidentId}/runPlaybook?api-version=2019-01-01-preview
Body:
{
"LogicAppsResourceId":"/subscriptions/{subscriptionId}/resourceGroups/{PlaybookResourceGroup}/providers/Microsoft.Logic/workflows/{PlaybookName}",
"TenantId":"{TenantID}"
}
Create ARM template from the existing playbook
Many organizations are using development instances of Microsoft Sentinel, where they test analytic rules, playbooks, etc., before deploying them into production instance. Creating playbook template manually can be time consuming job. That is why Sreedhar Ande had created ARM template generator, that is automating most of the things needed to create playbook template. The same tool can be used to create playbook to contribute to Microsoft Sentinel official GitHub repository.
On this blog, you can find info how to deploy and used this tool:
Export Microsoft Sentinel Playbooks or Azure Logic Apps with Ease - Microsoft Tech Community
How to authorize Logic App connector and what identity to use
Playbooks are using power of Logic App to automate SOC actions on incidents. Every Logic App action is using API in the background, which needs to be authorized. To authorize Logic App connector, it is possible to use 3 different identities:
- Managed Identity
- Service principal (Azure AD application registration)
- User identity
In this blog you can find more details about each type of identity and when to use each:
API connections and permissions for Microsoft Sentinel Playbooks
In this article you can find more details about authenticating playbooks in Microsoft Sentinel:
Authenticate playbooks to Microsoft Sentinel | Microsoft Docs
Assign API permissions to managed identity using PowerShell
System-assigned managed identity is the preferred method of authorizing Logic App connectors because organizations don’t need to manage keys, and only that Logic App can use permissions. No other Logic App can use it, as with service principal or user identity.
Assigning Azure RBAC controls or Azure AD roles are straightforward and can be done quickly from the GUI, like with service principal or user identity.
But sometimes, we need to assign specific API permissions to get the least privileged access. This can be done using Powershell. When we deploy the playbook, we need to ensure the system-assigned managed identity is enabled and copy the GUID of managed identity as we need it.
We open PowerShell, and we need to run these commands:
Set-ExecutionPolicy unrestrictedInstall-Module AzureADImport-Module AzureAD
After we are sure the Azure AD module is installed, we can connect to Azure AD.
Connect-AzureAD
And then, we run a PowerShell script that will assign specific API permissions. For example, we will use the playbook Block-AADUser.
First, we need GUID from managed identity, application ID, and permissions.
Managed Identity GUID you can find after deploying the playbook under “Identity”.
Application ID can be found on the Azure AD admin portal under Enterprise applications. Under filter, choose All applications. We will search for the application regarding the API we are using: Microsoft Graph, Microsoft Defender for Endpoint, etc.
The most common application IDs will be:
Azure AD (Microsoft Graph) - 00000003-0000-0000-c000-000000000000
Microsoft Defender for Endpoint - fc780465-2017-40d4-a0c5-307022471b92
Microsoft 365 Defender - 8ee8fdad-f234-4243-8f3b-15c294843740
Permissions will depend on the action we need to perform, whether we need to get the user, update the user, get the machine, isolate the machine, etc. Depending on API documentation, you can find specific API permissions needed to be assigned to perform the action. In this specific playbook, we need to assign these API permissions:
- User.Read.All
- User.ReadWrite.All
- Directory.Read.All
- Directory.ReadWrite.All
PowerShell code would look like this:
PowerShell code would look like this:
$MIGuid = "<Enter your managed identity guid here>"
$MI = Get-AzureADServicePrincipal -ObjectId $MIGuid
$GraphAppId = "00000003-0000-0000-c000-000000000000"
$PermissionName1 = "User.Read.All"
$PermissionName2 = "User.ReadWrite.All"
$PermissionName3 = "Directory.Read.All"
$PermissionName4 = "Directory.ReadWrite.All"
$GraphServicePrincipal = Get-AzureADServicePrincipal -Filter "appId eq '$GraphAppId'"
$AppRole1 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName1 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole1.Id
$AppRole2 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName2 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole2.Id
$AppRole3 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName3 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole3.Id
$AppRole4 = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionName4 -and $_.AllowedMemberTypes -contains "Application"}
New-AzureAdServiceAppRoleAssignment -ObjectId $MI.ObjectId -PrincipalId $MI.ObjectId `
-ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole4.Id
We need to run it and have API permissions assigned to the managed identity!
Continue with playbook when action fails
Sometimes failure of an action in playbook is expected and we don’t want that whole playbook run fails as well. This is possible to configure in playbooks by configuring “run after” option.
Use case would be using “Get a watchlist by alias” to check is watchlist available or not, before using action to create a new watchlist. Action is returning status code 200 and 400, depending on is watchlist available or not. By configuring condition action to be triggered even if “Get a watchlist by alias” fails, you are able to check status code and if it’s 400 (watchlist not available), continue creating new watchlist.
