Working with Analytics rules Part 4 – Create Microsoft Security Rule

Introduction

In this last post of the series, we will look at creating a Microsoft Security Analytics rule.  These are the ones that will raise an alert that has been generated from a different Azure security product.  As of right now, those products are:

• Azure Active Directory Identity Protection
• Microsoft Defender Advanced Threat Protection
• Azure Security Center
• Microsoft Cloud App Security
• Azure Advanced Threat Protection

I expect as additional security products are released, like Security Center for IoT, those products will be added to this list.

Rule Template Rule Type

The rule type for these rules are “MicrosoftSecurityIncidentCreation“.   There is not a separate rule type for each product you are using, that is set in a different field in the text you are sending as part of the body.

When creating a new rule there are 3 things we need to do differently than when listing rules

Create a new Microsoft Security rule

For those that have not read the previous post on creating a Fusion / ML rule type, I will include all the steps here.  If you have read it then you just need to skip down to where the body is being setup to note the differences.

1. We will need to create GUID that will be part of the URL we use to make the REST call
2. We will be using the PUT method when making the REST calls
3. Because of this we need something to PUT.  We will be setting up a variable that contains all the needed data.

For item #1, we will need to create a GUID, store it in a variable, and use that variable in the URL.  First, to create a GUID and store it in a variable, use

$guid = (New-Guid).Guid

We then use that to state which alertRule we are looking at. So, in this case, the URL would be

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/alertrules/$($guid)?api-version=2019-01-01-preview

making all the needed replacements for {subscriptionId}, {resourceGroupName}, and {workspaceName}.  Notice the $($guid) which is needed to translate the variable inside quotes (which are not shown in the code segment above but when you set the URL to a variable you will need to use them.  See the full listing below)

Item #2 is easy enough.  When we make the call to Invoke-RestMethod we change the Method parameter to Put.

For item #3, we will need to create a variable that holds the information to pass into the body of the REST call and pass that in.  To pass it in, we will use the Body parameters and pass in the variable after converting it to JSON (see the code below).

We are going to be really creative and use $body as the variable for the body.  There are four fields that we need to have in the body; kind, enabled, productFilter, and displayName keeping in mind that the last three are part of the properties variable.  It is pretty easy to create the variable as shown below:

$body=@{    
   "kind"="MicrosoftSecurityIncidentCreation"    
   "properties"=@{ 
      "enabled"="true"       
      "productFilter"="AzureActiveDirectoryIdentityProtection"       
      "displayName"="GaryADTest"    
   } 
}

In this case we are creating a new Microsoft Security rule based on the Azure Active Directory Identity Protection product.  It should be noted that this is just the most basic body that can be used.  You can add additional fields like severity filter and displayname filter.  Take a look at the examples at: https://github.com/Azure/azure-rest-api-specs/tree/master/specification/securityinsights/resource-manager/Microsoft.SecurityInsights/preview/2019-01-01-preview for more information. Now we call the PowerShell command to use the REST API: 

Invoke-RestMethod -Uri $uri -Method Put -Headers $authHeader -Body ($body | ConvertTo-Json -EnumsAsStrings)

making sure to translate the $body string to JSON. The full listing would be like below.  This was taken from VSCode which is the editor I usually use for PowerShell. 

 $context = Get-AzContext
 $profile = [Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
 $profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($profile)
 $token = $profileClient.AcquireAccessToken($context.Subscription.TenantId)
 $authHeader = @{
     'Content-Type'  = 'application/json' 
     'Authorization' = 'Bearer ' + $token.AccessToken 
 }
 #Microsoft Security Rule
 $body = @{
     "kind"       = "MicrosoftSecurityIncidentCreation"
     "properties" = @{
         "enabled"       = "true"
         "productFilter" = "Azure Active Directory Identity Protection"
         "displayName"   = "Gary AD Test"
     }
 }
 $guid = (New-Guid).Guid
 $uri = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/rg-sentinel-beta/providers/Microsoft.OperationalInsights/workspaces/la-sentinel-beta/providers/Microsoft.SecurityInsights/alertRules/($guid)?api-version=2019-01-01-preview"
 try {
     $result = Invoke-RestMethod -Uri $uri -Method Put -Headers $authHeader -Body ($body | ConvertTo-Json -EnumsAsStrings)
     Write-Output "Successfully updated rule with status: $($result.StatusDescription)"
     Write-Output ($body.Properties | Format-List | Format-Table | Out-String)
 }
 catch {
     $errorReturn = $_
     Write-Error $errorReturn
     #Write-Error "Unable to invoke webrequest with error message: $($errorResult.message)" -ErrorAction Stop
 }