Microsoft Secure Tech Accelerator
Apr 03 2024, 07:00 AM - 11:00 AM (PDT)
Microsoft Tech Community
New Year - New Official Azure Sentinel PowerShell Module!
Published Feb 01 2021 04:35 AM 21.8K Views
Microsoft

 

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

 

Get-SecurityInsights-cmdlets.png

 

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:

Incident.png

 

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" = "JeffL@contoso.com"; "ObjectId" = "f4e959b4-feda-4345-a1e7-16b4af2fc226";"UserPrincipalName" = "JeffL@contoso.com"} 

 

 

 

 

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:

Name

 Description

AADDataConnector

 Represents AAD (Azure Active Directory Identity Protection)

AATPDataConnector

 Represents AATP (Azure Advanced Threat Protection)

ASCDataConnector

 Represents ASC (Azure Security Center)

AwsCloudTrailDataConnector

 Represents Amazon Web Services CloudTrail

MCASDataConnector

 Represents MCAS (Microsoft Cloud App Security)

MDATPDataConnector

 Represents MDATP (Microsoft Defender Advanced Threat Protection)

OfficeDataConnector

 Represents Office 365

TIDataConnector

 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

 

 

Export-Rules.png

 

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!

 

 

30 Comments

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

Cheers 

Copper Contributor

It's amazing the possibilities that this offers! 

Thanks for it!

Brass 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'

Microsoft

@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.
Copper Contributor

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

Microsoft

@rr-inspark unfortunately not at this point.

@Michael Carrabine  and @TJBanasik thanks for your comments.

Brass 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.

Microsoft

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

Brass 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 "/".

Microsoft

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

Copper Contributor

Thanks for sharing the module.

Brass Contributor

Is this expected to replace AzSentinel Module that was released by WORTELL? https://github.com/wortell/AZSentinel

@Tiander Turpijn 

Copper Contributor

HI!

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 \ / : * ? " < > |

Copper Contributor

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

 

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

Brass Contributor

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

Copper Contributor

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

Microsoft

@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...

Microsoft

@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.

Microsoft

@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.

Brass 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).

 

Copper Contributor

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)

Microsoft

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.

Copper Contributor

@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.

Copper Contributor

@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.

Copper Contributor

Hi.

 

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?

 

Jaa9

Copper Contributor

@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.
Iron Contributor

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?

eg:

Get-AzSentinelAlertRule -WorkspaceName xxxx -RuleName "test1"

bobsyouruncle_0-1624625992083.png

 

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
paces/3psiem/providers/Microsoft.SecurityInsights/alertRules/xxx
kind : Scheduled
createIncident : False
groupingConfiguration : @{enabled=False; reopenClosedIncident=False; lookbackDuration=PT5H; entitiesMatchingMethod=All;
groupByEntities=System.Object[]}
playbookName :

 

Copper Contributor

Hi!!

Really interesting material!

One question, i'm trying to use Update-AzSentinelIncident to close around 1500 incidents in Sentinel, the problem is that when i try with one, for example, it closes correctly but dissappear from the Azure Sentinel Dashboard.

Is normal that?

Brass Contributor

Hi @Grimka,

Have you checked the filter on the status of incidents on the dashboard you are looking at? By default, Azure Sentinel only shows "New" and "Active" so if you closed the incident via the PowerShell module, it wouldn't be visible unless you add the "Closed" status to the filtered view.

 

Copper Contributor

Hi @Tiander Turpijn and everyone,

This article pin points how to export all rules as a JSON with powershell, but how do you import the same with powershell? The portal gui only allows for import of 50 rules at a time and the powershell doesn't have a restriction to 50 rules on one export. There is also the fact that the export from powershell vs export from portal gui seem to both be JSON, but with different schema.

Version history
Last update:
‎Nov 02 2021 06:33 PM
Updated by: