New Year - New Official Azure Sentinel PowerShell Module!

Published Feb 01 2021 04:35 AM 12.9K Views


Happy New Year everyone!

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:

Install-Module -Name Az.SecurityInsights -AllowClobber

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.


Managing Incidents

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:



$ownerObject = @{"AssignedTo" = "Jeff Leatherman"; "Email" = ""; "ObjectId" = "f4e959b4-feda-4345-a1e7-16b4af2fc226";"UserPrincipalName" = ""} 





After you have created the owner object, you can then pass it as a parameter to the cmdlet Update-AzSentinelIncident like this:



Update-AzSentinelIncident -ResourceGroupName <yourResourceGroupName> -WorkspaceName <yourWorkspaceName> -IncidentId a4b586c8-97d8-4cc5-9154-b723c62d26d8 -Owner $ownerObject 




Closing an incident

In case you need to close an incident, you need to make sure that you are passing the valid closing classifications and classification reasons.

Valid closing incident classifications are:

  • Undetermined
  • TruePositive
  • BenignPositive
  • FalsePositive

Valid closing classification reasons are:

  • SuspiciousActivity
  • SuspiciousButExpected
  • IncorrectAlertLogic
  • InaccurateData

Example closing an incident:



Update-AzSentinelIncident -ResourceGroupName <yourResourceGroupName> -WorkspaceName <yourWorkspaceName> -IncidentID "a5977bae-2775-44d1-8381-a28f6f061954" -Classification FalsePositive  -ClassificationComment "my comment" -ClassificationReason InaccurateData -Status Closed 




Configuring data connectors

The cmdlet New-AzSentinelDataConnector supports configuring and enabling Azure Sentinel data connectors. The current supported GA data connectors are:




 Represents AAD (Azure Active Directory Identity Protection)


 Represents AATP (Azure Advanced Threat Protection)


 Represents ASC (Azure Security Center)


 Represents Amazon Web Services CloudTrail


 Represents MCAS (Microsoft Cloud App Security)


 Represents MDATP (Microsoft Defender Advanced Threat Protection)


 Represents Office 365


 Represents threat intelligence data


The following example configures the Office 365 data connector:



New-AzSentinelDataConnector -ResourceGroupName "yourResourceGroupName" -WorkspaceName "yourWorkspaceName" -Office365 -Exchange "Enabled" -SharePoint “Enabled"





Some data connectors require more information, like the Azure Security Center data connector:



New-AzSentinelDataConnector -ResourceGroupName "yourResourceGroupName" -WorkspaceName "yourWorkspaceName" -AzureSecurityCenter -SubscriptionId <yourSubscriptionId> -Alerts Enabled 





Exporting and importing analytics rules

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.



Happy automating!




Happy New Year @Tiander Turpijn Thanks for Sharing with the Community :cool:


Senior Member

It's amazing the possibilities that this offers! 

Thanks for it!

New Contributor

This is great. Keep up the good work.


I get this when I run Install-Module -Name Az.SecurityInsights. It works if I use -AllowClobber

PackageManagement\Install-Package : The following commands are already available on this
system:'Login-AzAccount,Logout-AzAccount,Resolve-Error,Send-Feedback'. This module 'Az.Accounts' may override the
existing commands. If you still want to install this module 'Az.Accounts', use -AllowClobber parameter.

P.S. Module name should be corrected in article above 'The available cmdlets can be explored by using Get-Command -Module Az.SecurityInsigths'


@Tiander Turpijn , Outstanding blog and a great start to the New Year! I was having trouble with the New-AzSentinelAlertRule Command so I wanted to share a few things that were helpful in getting it working

Install-Module -Name Az.Accounts -AllowClobber -Force

Install-Module -Name Az.SecurityInsights -AllowClobber -Force

Update-Module -Name Az.Accounts

Update-Module -Name Az.SecurityInsights
  • Confirm that all alert rule fields are populated (Scheduled, DisplayName, Description, Query, QueryFrequency, QueryPeriod, Severity, TriggerThreshold) or adjust New-AzSentinelAlertRule command syntax as needed. I was having an issue importing a test rule because an optional alert rule (Description) wasn’t included. Adding a description or removing the -Description option from the command resolves the issue.
Senior Member

Is there a way to connect "Azure Active Directory Sign-in logs" only?


@rr-inspark unfortunately not at this point.

@Michael Carrabine  and @TJBanasik thanks for your comments.

New Contributor

@Tiander Turpijn Thanks for sharing the module.

It will certainly be very helpful moving forward as an official module from Microsoft.

I have noticed that when exporting analytics rules that contain some specific characters such as "/", it will return an error on the PowerShell command.


@caiodaruizcorrea Yes, it does. Can you share your rule name, to see an example why you would use a "/" in your rule name?

New Contributor

Hi @Tiander Turpijn,

Thanks for the reply.


There is a template analytics rule called "Known Phosphorus group domains/IP".


We do have others that had the same sort of name convention which also failed due to the "/".


@caiodaruizcorrea thanks for sharing. I will look into it.

Senior Member

Thanks for sharing the module.

Occasional Contributor

Is this expected to replace AzSentinel Module that was released by WORTELL?

@Tiander Turpijn 

Senior Member


Regarding the question about / in the rule name that generates an error in PowerShell, this is related to the fact that a file name in Windows cannot have some special characters and / is one of them. The full list is \ / : * ? " < > |

Senior Member

Thanks for sharing, glad API/automation is on the agenda for Sentinel.


Looking forward to see API work done for playbooks and workbooks.

Occasional Contributor

@Tiander Turpijn . This is really helpful and thanks for sharing with us. 

Senior Member

I'm having many issues with alert rules, including:

  • The updating of alert rules:
    • Documentation is not accurate in some cases (e.g. parameter is -Tactic, not -Tactics) and it is only allowed for scheduled rules.
    • Can't seem to update DisplayNamesExcludeFilter & DisplayNamesFilter in any test I did
    • Updating expects -Enabled & -Disabled parameters while new alert rules are only requiring -Enabled; how are we supposed to update a rule's enabled/disabled state, it never seems to work for me so far


Getting ML Behavior Analytics rules results in an error and therefor possibly not possible to create/updating


@caiodaruizcorrea @AUntilov I've uploaded a sample to export analytics rules to a single file and will update the blog post too.

You can find the sample here: Azure-Sentinel/Tools/Az.SecurityInsights-Samples/Alert Rules/Export Analytics Rules at master · Azur...


@majo01 The Wortell module is a great module, but it is not officially supported by Microsoft. We needed to release an "official" one to get it supported and maintained by engineering. If you are happy with the Wortell module, please continue to use it, we have not released our module with the objective to replace it, but to provide an official supported path. It also integrates with the parent Az. module.


@Sebabulte Thank you for providing your feedback. I'm working on documentation with samples as we speak, which will clarify usage a lot better.

We will add a disabled parameter, good feedback, and will look into your other feedback, thank you 

Currently the ML Behavior Analytics rules are not supported, but will be if we GA our module, which will be soon.

New Contributor

Hi @Tiander Turpijn,

I tested and can confirm that the new sample version you provided to export to a single file does allow us to export all rules including the ones with the unsupported characters on Windows File System (NTFS).


Senior Member

Could you elaborate on why the module is limited in the number of tickets can be managed? It looks like its the last 1500 only and set as a constant.


private const int MaxIncidentsToFetch = 1500;


Also, Update-SentineltIncident cannot work with IncidentNumber as inputparam, but only Incident ID. 


The above leaves this module unable to work with older incidents. Is this on purpose or just some missing development? (Please correct me if i'm wrong)


Hello @Kirederf , since you can have a retention of 2 years in Azure Sentinel, which can contain a lot of incidents (status is not relevant), we have limited this number. What would be your use case to retrieve a higher number and what number would be aligned with your use case?

Would like to learn the use case for managing older incidents.

For your second question, we are dependent on the SecurityInsights API which takes the IncidentId has input parameter, not the Incidentnumber.

Senior Member

@Tiander Turpijn these new Sentinel PowerShell commands are very useful. Are you guys planning on expanding the list of available commands? I would like to be able to use the import/export commands for other Sentinel features like hunting rules, workbooks, and playbooks.

Senior Member

@Tiander Turpijn  In my usecase, i needed to clean-up sentinel for old alerts before moving into production. But in general, not being able to work with older incidents at all seems like an unnatural limitation. At least the number of incidents could be optional or to provide the ability to work with incidents based on numbers would suffice, i guess.

New Contributor



I am having trouble creating a new alertrule using New-AzSentinelAlertRule and passing along the -Tactic parameter:


Cannot convert 'null' to the type 'System.Collections.Generic.IList`1[System.String]' required by parameter 'Tactic'

How can I in my Powershell script create the necessary object to pass along with the Tactic parameter?



Senior Member

@Jaa9H You'll need to convert whatever you have as tactics to the format of IList. I do it like this:


[Collections.Generic.List[String]]$tacticTable = $myNewRuleObject.Tactics
New-AzSentinelAlertRule ... -Tactic $tacticTable
Also, the error you get might just be because you have no Tactics identified in your rule, then you shouldn't pass the -Tactic parameter otherwise the deployment will fail.
This API still needs a lot of work in my opinion, as I have to find many workarounds to make things work and updating rules does not seem to work anymore in this latest API version. Let's hope this is going to be a priority for MS seeing as many clients are embracing automation more and more.

Hey @Tiander Turpijn , great article!


Here's a challenge:


I want to add Mitre TECHNIQUES (not tactics) to my alerts/rules.


I see the Github rules have a field: relevantTechniques - but I don't think that field is usable in a playbook? i.e. it's not passed on as an entity or other field that's seen in the alert?


So the best place I can see to add this is as an alert entity, where I can look it up in a playbook and do something with it like map it to mitre defensive actions.


So how can I write an alert entity using Update-AzSentinelAlertRule?


Get-AzSentinelAlertRule -WorkspaceName xxxx -RuleName "test1"



Here's an exported rule.

How can I use Get-AzSentinelAlertRule to write the entityMappings?


queryFrequency : PT5H queryPeriod : PT5H triggerOperator : GreaterThan
triggerThreshold : 0
eventGroupingSettings : @{aggregationKind=SingleAlert}
severity : Medium
query : SecurityAlert|project technique="T1234"
suppressionDuration : PT5H
suppressionEnabled : False
entityMappings : {@{entityType=URL; fieldMappings=System.Object[]}}
displayName : test
enabled : False
description :
tactics : {}
alertRuleTemplateName :
lastModifiedUtc : 6/25/2021 12:52:20 PM
name : xxx
etag : "xxx"
id : /subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.OperationalInsights/works
kind : Scheduled
createIncident : False
groupingConfiguration : @{enabled=False; reopenClosedIncident=False; lookbackDuration=PT5H; entitiesMatchingMethod=All;
playbookName :


Version history
Last update:
‎Feb 01 2021 04:38 AM
Updated by: