Saturday, June 30, 2018

Create Office 365 Activity Alerts using PowerShell

In a previous article:

Create Office 365 Alerts

I detailed how to create Office 365 Activity alerts using the browser. I will point out how important it is to have appropriate alerts set for your tenant, especially when you generally don’t get many configured . your tenant by default.

Of course doing administration tasks via a browser is the slow way to get things done. A much better approach is to use PowerShell and let the script do the heavy lifting.

The first step in this process is to take a look at the following article:

Search the audit log in the Office 365 Security and Compliance center

and locate the heading – Auditing activities which contains a list of the actions that will trigger an alert. There are plenty of things here so pick those that make the most sense and remember that lots and lots of alerts generally doesn’t improve security, it simply creates information overload.

The alert I’ll chose to illustrate is FileMalwareDetected.

Next step is connect to the Office 365 Security and Compliance Center with PowerShell. I’m not going to show you how to do that here as it is easily located elsewhere like here:

Connect to Office 365 Security & Compliance Center PowerShell

With that done, you can now execute the actual commands to configure activity alerts with PowerShell.

$fileandpagepolicyparams = @{
"Name" = "File and Page Alert";
"operation" = "Filemalwaredetected";
"notifyuser" = $notifyusers;
"userid" = $userids;
"Description" = "SharePoint anti-virus engine detects malware in a file.";
}

$result=New-ActivityAlert @fileandpagepolicyparams

Basically, what I’m doing here is creating an array called $fileandpagepolicyparams that contains all the options required for the command that will set the alert. Doing it this way makes it easier to what’s going on and make any additions if needed in my opinion.

The New-ActivityAlert command takes all those array parameters as inputs when an alert is now created.

The $notifyusers are the users you want to receive emails when alerts occurs. The $userids are the users you wish to trigger alerts. If you leave $userids empty it will apply the alert to all users in the tenant.

image

You can see the result above once that command is run.

Now the idea is to build a script that configures all the activity alerts you desire and then apply them to a tenant.

image

As you can see above, I generally create about a dozen or so alert policies this way that monitor for a range of activities I believe should have alerts configured for. However, you need to decide what makes sense for you.

Now be very, very careful when you configure activity alerts via PowerShell. Ensure you get all the parameters 100% correct and you check the alert policies in the web interface when you are testing your script, because errors in the script don’t get reported and you end configuring an activity alert that does nothing all because you got a parameter wrong!