Using the Microsoft Graph PowerShell for Security Alerts

Microsoft 365 provides deep insight into the configuration, analytics, and usage, as well as security notifications and alerts. Multiple locations within the various admin centers surface these alerts, and some of these get emailed to the administrators to make it easy to review and action. Alerts, for example, are based on specific policies and controls, and you can view or update alerts as needed.

The easiest way to manage these alerts is to use PowerShell. As always, the Microsoft Graph PowerShell modules provide the capabilities for this. For this example, we will perform the following:

• Connect to Microsoft 365 using the Graph PowerShell
• Retrieve current Alerts
• Update existing Alerts

To get started, let’s first ensure we have the correct module installed; if not, then install it.

Get-InstalledModule "*Graph*"

If you see a long list of “Microsoft.Graph” modules, then you are ready to execute commands. If not, then you need to install and import the modules.

Install-Module Microsoft.Graph
Select-MgProfile -Name "beta"
Import-Module Microsoft.Graph

Next, connect to Microsoft using the following scopes.

Connect-MgGraph -Scopes `
		"SecurityActions.ReadWrite.All", `
		"SecurityEvents.ReadWrite.All", `
		"Policy.Read.All", `
		"Application.ReadWrite.All"

Once connected, you can execute the required commands. The first command to run can retrieve any existing security alerts (Get-MgSecurityAlert).

Get-MgSecurityAlert

You can also check the current security actions by executing this command (Get-MgSecurityAction):

Get-MgSecurityAction

If you are using a new tenant, then you may not return any values at all. If the command returns values, it will just be a long list of GUIDs, and you won’t decipher it correctly. To make it easier to read, you can run the following command:

Get-MgSecurityAlert | `
	Select-Object `
		Title, `
		Description, `
		Category, Id | `
			Out-GridView

The output will now be easier to view and read. You could also export the values as needed using something like the
“Export-Csv” command.

Get-MgSecurityAlert | `
	Select-Object `
		Title, `
		Description, `
		Category, Id | `
			Export-Csv

To view an individual security alert, you can pass an ID.

# Retrieve Security Alert using an ID
Get-MgSecurityAlert `
	-AlertID 665436434b4bc232eee67

# Retrieve Security Alert using an ID, then show all fields
Get-MgSecurityAlert `
	-AlertID 665436434b4bc232eee67 | `
		Select-Object *

If you need to filter and search specific values, the current PowerShell commands do not work as expected. However, you can use the “Invoke-MgGraphRequest” command. If you are querying the graph directly, you need to use this type of query:

https://graph.microsoft.com/beta/security/alerts?$filter=title eq ‘Activity from infrequent country’

The PowerShell equivalent is this:

$graphversion = "beta"
$url = "https://graph.microsoft.com"
$endpoint = "security/alerts"
$filter = "title eq 'Activity from infrequent country'"
$body = @{}

$uri = "$url/$graphversion/$endpoint"

$alerts = Invoke-MgGraphRequest `
    -Uri $uri `
    -Method GET `
    -Body $body

When retrieving values using the graph directly, it is often harder to view the values you need to see. To ease this, you can loop the results and output in a different format. An example could be:

$alertslist = New-Object System.Collections.ArrayList

$graphversion = "beta"
$url = "https://graph.microsoft.com"
$endpoint = "security/alerts?`$filter="
$query = "Category eq 'ThreatManagement'"

$body = @{}

$uri = "$url/$graphversion/$endpoint$query"
 
$alerts = Invoke-MgGraphRequest `
    -Uri $uri `
    -Method GET `
    -Body $body

$alerts.value | ForEach-Object {
	$alertslist.Add(@{ `
		"ID"=$_.Id; `
		"Title"=$_.Title; `
		"Category"=$_.Category; `
		"Description"=$_.Description; `
		"Severity"=$_.Severity;
	}) `
}

$alertslist

As you can see, the Microsoft Graph PowerShell commands enhance our ability to query and synchronize the alerts into other applications as needed. For example, you could connect to the graph alerts, format as required, then synchronize directly to a SharePoint Online List, SQL Database, Export as CSV files, or even send notifications using something like Flow.

The capabilities don’t stop there either; you can update an alert, usually completed within the specific administrative center.

$graphversion = "beta"
$url = "https://graph.microsoft.com"
$endpoint = "security/alerts"
$alertid = "6164759135113312b8becc18"

$uri = "$url/$graphversion/$endpoint/$alertid"

$body = '{
	"assignedTo": "admin@m365x969864.onmicrosoft.com",
	"comments": [
		"Updated by PowerShell",
	],
	"tags": [
		"Graph",
		"PowerShell"
	],
	"status": "resolved",
	"vendorInformation": {
		"provider": "MCAS",
		"vendor": "Microsoft"
	}
}'

Invoke-MgGraphRequest `
    -Uri $uri  `
    -Method PATCH `
    -Body $body

This command updates the existing alert with the various property changes as required. As you can see, it is very straightforward to retrieve and update alerts as needed, allowing updating from outside of the Administrative centers. It makes Graph PowerShell an excellent integration tool, especially when you can use outside logic and rules for investigations, then updates using easy commands.