Deploy Microsoft Sentinel using Bicep

Bicep is a domain-specific language that uses declarative syntax to deploy Azure resources. It offers advantages over Azure Resource Management (ARM) templates, including smaller file sizes, integrated parameter files, and better support for tools such as Visual Studio Code. To learn more about Bicep, visit: What are biceps?

To learn more about what you can do with Microsoft Sentinel by Bicep, go to: Microsoft Sentinel Bicep Resources. The top-level item (still incorrectly called “Azure Sentinel”) does not have a direct link, so this link will take you to “Aggregations”. If you select something like “Alert Rule” you will see the format of the Bicep resource definition and one or more examples of how to use it. Very convenient.

I created the Bicep resource and parameter files with the help of this page, a few others selected from the menu on the left side of the page, and Internet users including Kevin Hemelrijk and Mark Palmer. Due to some limitations in Bicep resources, a PowerShell file is also called.

resource group

You can use a bicep file to create a resource group, but because of the way the file is called, a resource group must exist first. You can do this using any process you like, including the Azure CLI commands listed below.

az group create --location  --resource-group 

for example

az group create --location eastus --resource-group testRG

biceps file

The first thing done in the bicep file is to set the parameters and some variables to be read from the parameter file (more on this later). “Subscription” and “resourceGroup” are embedded variables that refer to the environment in which this Bicep file runs.

@description('Specifies the name of the client who needs Sentinel.')
param workspaceName string

@description('Specifies the number of days to retain data.')
param retentionInDays int

@description('Which solutions to deploy automatically')
param contentSolutions string[]

var subscriptionId = subscription().id
var location  = resourceGroup().location
//Sentinel Contributor role GUID
var roleDefinitionId = 'ab8e14d6-4a74-4a29-9ba8-549422addade'

Parameters have an associated type. This is another check to ensure that the correct type of data is passed as a parameter. Restrictions such as maximum length or allowed item selection may apply. Learn more about parameters later in this article.

The last parameter is an array containing the solution names of the content hubs to be deployed. Please note that the name displayed in the Azure portal may not be the correct name to use here as some names may have changed. The best way to get a proper name is to call the Microsoft Sentinel “contentProductPackages” REST API. More information about this can be found here: Microsoft Sentinel content package. After calling it, you can check “.properties.displayName” to get the appropriate name.

Let’s look at the Bicep call to create a Log Analytics workspace.

resource workspace 'Microsoft.OperationalInsights/workspaces@2022-10-01' = {
  name: workspaceName
  location: location
  properties: {
    retentionInDays: retentionInDays
  }
}

• Line 1 begins with “resource” to indicate that Bicep is distributing a resource as opposed to a loop. The word “workspace” is then called the symbolic name and is later used to refer to the resource. For example, when you create a Microsoft Sentinel instance, one of its properties is “workspaceResourceId”, which you can reference by passing “workspace.id”.
• The second line is the name of the resource. In this case, a parameter called “workspaceName” is used.
• Line 3 is the location of the workspace. Variable positions are passed here.
• Line 4 begins the required properties. In this case, only retention time (days) is used. Each resource has different properties.

These are the calls to create a workspace, a Microsoft Sentinel instance, and to complete Microsoft Sentinel onboarding.

// Create the Log Analytics Workspace
resource workspace 'Microsoft.OperationalInsights/workspaces@2022-10-01' = {
  name: workspaceName
  location: location
  properties: {
    retentionInDays: retentionInDays
  }
}

// Create Microsoft Sentinel on the Log Analytics Workspace
resource sentinel 'Microsoft.OperationsManagement/solutions@2015-11-01-preview' = {
  name: 'SecurityInsights(${workspaceName})'
  location: location
  properties: {
    workspaceResourceId: workspace.id
  }
  plan: {
    name: 'SecurityInsights(${workspaceName})'
    product: 'OMSGallery/SecurityInsights'
    promotionCode: ''
    publisher: 'Microsoft'
  }
}

// Onboard Sentinel after it has been created
resource onboardingStates 'Microsoft.SecurityInsights/onboardingStates@2022-12-01-preview' = {
  scope: workspace
  name: 'default'
}

After your Microsoft Sentinel instance is set up, there are several settings you can apply, including Entity Behavior Directory Service (in this case, Azure Entra Id (still called “AzureActiveDirectory” in code)) and Data Source.

// Enable the Entity Behavior directory service
resource EntityAnalytics 'Microsoft.SecurityInsights/settings@2023-02-01-preview' = {
  name: 'EntityAnalytics'
  kind: 'EntityAnalytics'
  scope: workspace
  properties: {
    entityProviders: ['AzureActiveDirectory']
  }
  dependsOn: [
    onboardingStates
  ]
}

// Enable the additional UEBA data sources
resource uebaAnalytics 'Microsoft.SecurityInsights/settings@2023-02-01-preview' = {
  name: 'Ueba'
  kind: 'Ueba'
  scope: workspace
  properties: {
    dataSources: ['AuditLogs', 'AzureActivity', 'SigninLogs', 'SecurityEvent']
  }
  dependsOn: [
    EntityAnalytics
  ]
}

Bicep provides a way to deploy the solution, but it doesn’t work correctly. This is because the underlying REST API is not working correctly. Also, since Bicep is used to create resources, you cannot use Bicep to get the list of solutions to deploy, hence the parameter mentioned earlier. Fortunately, we provide a way to call PowerShell to help you deploy your solution.

Because PowerShell interacts with Azure, a user ID must be created. This identity will then need Microsoft Sentinel Contributor, the appropriate permissions on the resource group. There is a 5 minute pause between these calls to allow ID times to propagate. How to call a PowerShell script is detailed below.

//Create the user identity to interact with Azure
@description('The user identity for the deployment script.')
resource scriptIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
  name: 'script-identity'
  location: location
}

//Pausing for 5 minutes to allow the new user identity to propagate
resource pauseScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'pauseScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '12.2.0'
    scriptContent: 'Start-Sleep -Seconds 300'
    timeout: 'PT30M'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'PT1H'
  }
  dependsOn: [
    scriptIdentity
  ]
}

//Assign the Sentinel Contributor rights on the Resource Group to the User Identity that was just created
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(resourceGroup().name, roleDefinitionId)
  properties: {
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    principalId: scriptIdentity.properties.principalId
  }
  dependsOn: [
    pauseScript
  ]
}

Finally, the PowerShell script Create-NewSolutionAndRulesFromList.ps1 is called to deploy the passed solution and create a rule from the rule template. This code is taken from the Microsoft Sentinel All-In-One V2 product and will not be covered in detail here. The only exception is that “Connect-AzAccount” is configured to pass the ID because the user ID account makes all calls to Azure.

Connect-AzAccount -Identity -AccountId $Identity

Where $Identity is the client ID passed as a parameter.

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'deploySolutionsScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${scriptIdentity.id}': {}
    }
  }
  properties: {
    azPowerShellVersion: '12.2.0'
    arguments: '-ResourceGroup ${resourceGroup().name} -Workspace ${workspaceName} -Region ${resourceGroup().location} -Solutions ${contentSolutions} -SubscriptionId ${subscriptionId} -TenantId ${subscription().tenantId} -Identity ${scriptIdentity.properties.clientId} '
    scriptContent: loadTextContent('./Create-NewSolutionAndRulesFromList.ps1')
    timeout: 'PT30M'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
  }
  dependsOn: [
    roleAssignment
  ]
}

Here are some things to note from this call:

• Lines 5-10: Because we are calling Azure, this resource call requires an ID.
• Line 12: At the time of this writing, we are set to the latest version of PowerShell. You may be able to use a lower version, but the logs may say that you have a newer version.
• Line 13: These are all the arguments passed to the PowerShell script. It must be read as a parameter in the script.
• Line 14: Location of the script. You can include the code inline, as was done for the “pauseScript” call above.
• Line 15: Time to allow the script to run. Keep this in mind if many solutions are delivered.
• Line 16: Cleanup preferences when the script runs. Other options include “Always” and “On Expires.”
• Line 17: How long the script resource will remain after execution is complete.
• Line 19: “dependentOn” indicates that this resource will not begin execution until after another resource, in this case “roleAssignment”. It ends. There are other instances of this throughout the file. If the resource uses data from a previous resource, “dependentOn” is not needed. For example, the “sentinel” resource uses “workspace.id”, so “dependentOn” is not required.

parameter file

Bicep can use two different formats for parameter files. This can be either JSON or a Bicep parameter file (with the “bicepparam” file extension). Bicep parameter files have advantages over regular JSON files.

The biggest advantage is that it references the Bicep file, so editors like Visual Studio Code can tell if there are parameters missing from the parameter file or the Bicep file.

In the case of the Bicep file in this document, it is a parameter file.

using './Sentinel.bicep'

param workspaceName="demo7"
param retentionInDays = 90
param contentSolutions = [
  'Amazon Web Services'
  'Microsoft Entra ID'
  'Azure Logic Apps'
]

Except for the first line, most of it is self-explanatory. This is a reference to the Bicep file to which this file sends data. This allows editors like Visual Studio Code to ensure that all parameters are taken into account in both the parameter file and the Bicep file. For more information about the Bicep parameter file, see: Biceps parameter file

Deploying Bicep Files

Using the Azure CLI, you can deploy the Bicep file by making the following call:

az deployment group create --name  --template-file  --parameters  --resource-group 

for example

az deployment group create --name testDeploy --template-file .\sentinel.bicep --parameters .\sentinelParams.bicepparam --resource-group rgTest

summation

This article shows you how to create a Microsoft Sentinel instance, add some settings, and deploy a solution and analysis rule template using the Bicep template. You can set up commitment tiers, configure some Microsoft data connectors like Entra ID or Azure Data Logs, set limits on parameters, and much more.

You can save these templates as part of your CI/CD for Microsoft Sentinel, and if you need to deploy multiple instances of Microsoft Sentinel, you can reuse them with minor modifications to the parameters file.