With the new year comes a new Azure Sentinel PowerShell module!
Based on the Azure SDK for .NET and part of the Azure (Az) module, we are announcing the public preview release of the Az.SecurityInsights PowerShell module.
Because this is an official supported PowerShell module when we release it, the cmdlets are based on the Generally Available (GA) 2020-01-01 SecurityInsights API. As soon as features hit GA, we will update the Az.SecurityInsights module to reflect that.
How to download and test
Prerequisites: the Az.SecurityInsights module requires at a minimum PowerShell version 5.1 and relies on Az.Accounts for Azure authentication.
You can download the Az.SecurityInsights PowerShell module from the PowerShellGallery and install it by using the PowerShell command:
The available cmdlets can be explored by using Get-Command -Module Az.SecurityInsights
The Az.SecurityInsights module supports the most common use cases, like interacting with incidents to change status, severity, owner, etc. But also, to add comments and labels to incidents and creating bookmarks.
Although using ARM templates is the preferred way for your CI/CD pipeline, the Az.SecurityInsights module can be very useful for post deployment tasks and is specifically targeted to Security Operations Center (SOC) automation tasks. These tasks can vary from configuring data connectors, creating analytics rules, adding automation actions to analytics rules, etc.
Using the Az.SecurityInsights module is straightforward and is parameter driven as most of the PowerShell modules. The common parameters are your Azure Sentinel workspace and resource group name. You can retrieve all your incidents using Get-AzSentinelIncident -ResourceGroupName $resourceGroupName -WorkspaceName $workspaceName or retrieve a specific incident by adding the parameter -IncidentId <yourIncidentId>
Note: the IncidentId is derived from the Name field as depicted below:
Assign an Incident Owner
Most of the cmdlets accept a string as a parameter, but some cmdlets require an input object. For example, to assign an owner to an incident you would first need to create the owner object.
The owner object requires the following mandatory object parameters:
AssignedTo - the owner full name
Email - the email address of the owner
ObjectId - the Azure Active Directory objectId of the owner
UserPrincipalName - the user principal name of the owner
There are a couple of ways to create an owner object, for example:
The most common asked question that we get is how to export analytics rules and import those in another Azure Sentinel environment. This use case is specifically valid in a Dev-Test scenario where you want to have automation support to import your created analytics rules into production. To export your analytics rules you can leverage the Get-AzSentinelAlertRule cmdlet.
A sample script how to export rules can be downloaded from here
This will export your analytics rules into a folder as one single JSON formatted file.
You can then edit the analytics rules or just import those into another Azure Sentinel environment. A sample will be posted soon.