Introduction of the Microsoft 365 Extractor suite

31.5.2022

De blogs zijn enkel beschikbaar in het Engels.

If you already know and used the Office 365 Extractor you have come to the right place. The tool was a hit and is still heavily used to acquire the Unified Audit Log (UAL). Since then the original developers Joey Rentenaar and myself have left PwC where we developed it. Therefore, it’s time for an updated version, called the Microsoft 365 Extractor. This blog contains all the details.

The Microsoft 365 Extractor Suite

Why?

There were some issues with missing support for multi factor authentication (MFA), mainly due to the way credentials were requested and used in the script. Additionally, the script was a bit big and required some updating in general. Finally, Office 365 is gone, it is now called Microsoft 365. Find the most important changes below:

  • MFA, the script uses the Connect-ExchangeOnline PowerShell cmdlet to authenticate and uses modern authentication and supports both MFA and non-MFA enabled accounts;
  • RecordTypes, to access the Unified Audit Log, the Search-UnifiedAuditLog PowerShell cmdlet is used to grab all types of logs. The Office365 Extractor grabs 76 RecordTypes, the Microsoft365 Extractor Suite grabs 100 RecordTypes;
  • Light version, a new version that is just a lightweight version of the script that simply grabs all the logs for all users;
  • Interval, the reason for the script is that we cannot simply acquire all logs in one go. The limit is 5k records per PowerShell session and for most environments this is way too small. Therefore the script uses an interval to acquire logs in a given timeframe. E.g. if you have a period of 1 month that you want to acquire and the interval is set to 60 the script will use that interval to search for logs in a period of 60 minutes and then move on to the next 60 minutes until the complete month is acquired. As you can imagine this might take some time and the script is smart enough to lower the interval if it finds more than 5k records for a given period. Therefore we have decided to set the initial interval to 480(1 day) which should speed up the acquisition especially for smaller environments.
  • Documentation, updates to the documentation and added some known issues mostly around using the script in a non-Windows environment. Which can cause some weird errors, we suggest you to run this in a Windows (virtual) environment.

What?

This suite of scripts contains two different scripts that can be used to acquire the Microsoft 365 Unified Audit Log

Microsoft365_Extractor, the original script originates from the Office 365 Extractor and provides all features and complete customization. Choose this if you’re not sure what to use.Microsoft365_Extractor_light, lightweight version of the Microsoft365_Extractor that requires minimal configuration and grabs all available logging for the defined period.Getting StartedSimply follow the steps as described on our GitHub page for the Microsoft 365 Extractor suite. In short get an account with sufficient permissions, execute the script and that’s it!

Examples

Log overview
First up we will use Microsoft365 Extractor to get an overview of the available logging as shown in the video below.


Log acquisition
Next we will use the new lightweight version of the script to simply acquire all logs for a defined period.

Complete process
Finally the complete process from beginning until the end of an acquisition using the Microsoft 365 Extractor suite. The video describes how to setup a user account with the required permissions and how you can use both scripts.

Important

Please leave suggestions, comments or a request on GitHub so we can make sure the script remains relevant and useful for a long period of time.

Further reading

You want to know how to analyse the UAL, we’ve got you covered there. You can use the Splunk Blue team app for Office 365 and Azure download here or here. You can also watch my talk from the SANS DFIR Summit here.