Osprey is a PowerShell module that is used to gather information for investigating Microsoft 365 Business Email Compromise incidents. The module performs limited analysis of the data, but you can pair it with this guide for more guidance on how to do an investigation.

Get Started

You can install Osprey two ways:

  • Open up a PowerShell terminal and type the command ‘Install-Module -Name Osprey’ and follow the prompts to install.
  • Download the installation script from the GitHub repository and run it.

Prerequisite Modules

Osprey requires the following modules be installed. Installing Osprey using the Install-Module command will automatically install the prerequisites. If not, you need to use Install-Module and install the following modules:

  • PSFramework (minimum version 1.9.310)
  • PSAppInsights (min. vers. 0.9.6)
  • ExchangeOnlineManagement (min. vers. 3.4.0)
  • Microsoft.Graph.Authentication (min. vers. 2.19.0)
  • Microsoft.Graph.Identity.DirectoryManagement (min. vers. 2.19.0)
  • Microsoft.Graph.Applications (min. vers. 2.19.0)
  • Microsoft.Graph.Authentication (min. vers. 2.19.0)
  • Microsoft.Graph.Users (min. vers. 2.19.0)
Create Folder

Next, create the folder where you want the Osprey module to store data. I suggest something easy, like c:\osprey.

Run Osprey

Depending on how you installed Osprey, you may need to load it into your PowerShell session with ‘Import-Module -Name Osprey’. You may need to import the prerequisite modules as well, if you get an error.

Next, you just have to run Start-Osprey and initialization will begin. You will need to agree to the EULA, and then you will be prompted to connect to the required modules with an M365 account with administrative permissions to the tenant you need to investigate. What permissions? Uh, I’ll get back to you about that. Global Admin for now, sorry.

After connecting to Exchange Online and consenting to the Graph scope, you just need to choose the timeframe you are investigating, then you’re good! Osprey should be initialized.

You can change the investigation parameters or investigate a different tenant by rerunning Start-Osprey and following the prompts.

If your investigations are going into the wrong tenant folder or you are running into issues with the graph commands, you may have not been connected with your intended tenant. This happens if you are investigating different tenants often. Simply rerun Start-Osprey and choose to rerun with another tenant. This will clear all your existing module connections.