Hawk - Tooling for Office 365 Log Gathering

Table of Contents

When responding to an incident involving compromised O365 credentials, the hardest part can often be gathering all the logs required to determine the root cause.

Responding to O365 Incidents #

While you may quickly discover the damage an attacker has caused to your environment through a compromised Office 365 account, finding out how they initially got in and the entirety of their activity can lead to some frustration. I have found this to be especially true using the default Microsoft tools available for pulling down logs from O365.

If your current logging configuration for O365 is not sending the information you need to some kind of centralised log management system, the Hawk PowerShell module created by Canthv0 is extremely helpful for extracting logs from Office 365. It’s a whole world better compared to messing around with Search-UnifiedAuditLog and it makes life a lot easier if you’re dealing with a large subscription since it pulls logs for individual users into their own folder and organises them by type, depending on the cmdlet you use.

While Hawk is not an official Microsoft tool, it is developed and maintained by a few Microsoft support engineers. Since it is written completely in PowerShell, it makes it easy for O365 admins to pick up and understand. I would recommend anyone that regularly needs to retrieve O365 events add this to their arsenal of tools for O365 log extraction.

Handling Multi-Domain Tenants #

If you ever need to perform exclusions for specific domains within an O365 tenant, see the snippet below that can be used to specify a domain for extraction:

$AllUsers = (Get-MsolUser -domainname "yourcompanydomain.com").UserPrincipalName

If you are extracting a large amount of user logs and you get interrupted half-way through, it can slow you down when trying to get the full list of user’s logs. You can exclude your extraction based on the user folders generated already to avoid pulling logs twice.

$ExcludedUsers = (Get-ChildItem).Name
$MissingUserlogs = ForEach ($u in $AllUsers) { Get-MsolUser -UserPrincipalName $u | Where { $_.UserPrincipalName -NotIn $ExcludedUsers }}

You can then check the output of $MissingUserLogs to ensure you are going to pull the correct list users of users on the next Hawk run. Run the next line to gather authentication logs for the remaining users:

Get-HawkUserAuthHistory -UserPrincipalName $MissingUserlogs.UserPrincipalName

Non-American Date Issue #

As of 14 September 2020, Hawk does not support using non-US date formats when specifying date ranges, but a pull request has been submitted to the main repo to resolve this issue.

This is specifically in reference to using shortcuts noted in the documentation like today or a number of days (e.g. 90). If you use a long-form date like 31-Oct-2019, you can get around problems that come from handling none US date formats.