Hackernoon logoIntroduction to The Hawk PowerShell Module: Office 365 Auditing by@adamtheautomator

Introduction to The Hawk PowerShell Module: Office 365 Auditing

Adam Bertram Hacker Noon profile picture

@adamtheautomatorAdam Bertram

Adam is an online business professional, Microsoft MVP, blogger, trainer, and published author.

Microsoft Azure provides several tools to monitor and investigate security incidents within Office 365 including Cloud App Security, Microsoft Defender Advanced Threat Protection, and Security Center. However, these tools often require additional costs and licenses. Also, the Office 365 audit log has a ton of info, but it can be hard to find what you're looking for.

Introducing the free Hawk PowerShell module.

The Hawk PowerShell module scans the Office 365 audit log, gathers all the information, and puts it in a single location on the local drive. The main goal of Hawk is to quickly retrieve data that is needed to review and analyze various logs.

In this article, you will learn how to install Hawk, connect to the Office 365 tenant, run scans against the tenant and users, and start the investigation of a security breach.


This article will be a tutorial on how to use the Hawk PowerShell module. If you'd like to follow along, please be sure you have the following prerequisites in place before starting.

  1. Windows PowerShell v5 or higher - the Hawk module is not compatible with PowerShell 6+.
  2. Internet connection.
  3. Windows 7 with Service Pack 1 or higher
  4. Office 365 Tenant Subscription

Microsoft offers a free 25-user Office 365 Developer lab which includes 25 user licenses to use. Be sure to install the User and Mail Sample packs. The sample packs will add 16 fictitious users with licenses and mailboxes, including names, metadata, and photos for each user, and add Outlook email conversations and calendar events for each of the 16 sample users.

Installing The Hawk Module

Before you can begin sleuthing in the Office 365 Audit logs with the Hawk module, you'll need to get it installed first. To do so, launch Windows PowerShell as administrator and enter the following:

Install-Module -Name Hawk 

This will take a few minutes as Hawk has several dependencies that are installed automatically when you install it. The additional modules are listed below:

Tip: If you want to see which modules are installed, add the verbose flag to the command. Example: Install-Module -Name Hawk-Verbose

Understanding The Hawk PowerShell Module

The Hawk module cmdlets are split into two main categories, tenant-based cmdlets, and user-based cmdlets. Tenant-based cmdlets gather auditing data such as user forwarding rules, global mailbox permission, and simple mailbox permissions for all your users. User-based cmdlets focus on individual user account data such as individual forwarding rules, mailbox changes, and message tracking.

Both the tenant-based and the user-based cmdlets are executed by running the main Start-HawkTenantInvestigation **or **Start-HawkUserInvestigation **command, depending on the area you wish to investigate. Executing the commands will call the appropriate cmdlets and begin to gather the data. Linked below are the cmdlets used in the Hawk Module.

Let's walk through an Office 365 audit and what it will look like.

The Office 365 Audit Log and Hawk

Auditing your Office 365 tenant begins with running the Hawk Tenant Investigation command as shown below:

PS51> Start-HawkTenantInvestigation

After checking for updates and initializing the modules, Hawk will log into MSOnline as seen below. Log in with your Tenant Global Administrator account to continue.

Enter Y to agree to the disclaimer as shown below.

Next, provide a directory where all of the logs and data will be stored. Hawk creates several audit logs and it is a good idea to create a separate directory to store them. In this example, all data will go to the C:\Hawk directory.

Hawk will then ask for a search window of which days you want to audit. Hitting Enter here will set the default start date of the search window to the current day minus 90 days. For the last day of the search window, hitting Enter will set the default of the current date.

To reduce the amount of data you have to review, try to limit the search window to as few days as possible.

Once you provide a search window to audit, Hawk begins the scan the exchange online tenant to gather the tenant-based logs. Log in to Exchange online with your tenant global administrator account as you did previously with MSOnline.

Once you're authenticated to Microsoft Online (MSOnline) and Exchange Online (EXO), Hawk begins to gather auditing data and write several logs and data files to your local drive. Hawk creates folders labeled with the date and time of the scan under the C:\Hawk folder in this example.

Each time you run Hawk, it will create a folder with the current time and date and store all the logs and data in the folder as shown below.

If running multiple scans or running scans over a series of days, Hawk will use a time/date stamp as folder names to make it easier to locate the data quickly. As you can see below, the first four numbers are the year are followed by a two-digit month, two-digit day and then the time expressed in military format.

Narrowing the Scope

With the tenant scan completed, the next step is to start reviewing the auditing data that the Hawk module produced. A good first file is to review

log file. The
file is a log report all the email forwarding rules for the tenant. Shown below is a sample

Forwarding email is a security risk because users may be forwarding sensitive information to vulnerable accounts. It could also potentially be used by spammers as a mail relay and cause damage to your companies reputation.

The next log you should review is the

file. This log details the changes in the different areas of the tenant the last time it was run. Look for any changes that seem suspicious. Some common items are:

  • Assigning permission changes to user accounts
  • Implementing inbox rule changes
  • Implementing user role changes (i.e. a standard user role changed to an administration role)

In the sample audit log below, the highlighted section shows that Hawk found eighteen changes in mailbox permissions. This deserves a closer look.

The next line in the log shows the location of the CSV file to review to get more details. In this case, the log file is located at


Auditing Users

Like tenants, Hawk can also audit user and admin activity for potential security breaches. With this information, you can narrow your focus to a few suspicious accounts.

Individual accounts are audited using the following command.

Start-HawkUserInvestigation -UserPrincipalName [email protected]_name.com


command will call all the
cmdlets and perform several actions against the user including auditing of:

  • User configuration
  • Mailbox rules
  • Forwarding rules
  • Folder Statistics
  • Mailbox statistics

As you can see below,

creates a folder labeled with the username and stores all the user-focused log files in that folder.

Many of the files created by the Hawk PowerShell Module are in CSV format. For information on how to use PowerShell to parse CSV files, be sure to read Managing CSV Files in PowerShell.


Investigating a security breach requires gathering as much data as you can and it can be a difficult task with lots of logs to review and data to collect. Hawk makes it easier by gathering the necessary logs into a single location. This article showed how you can use Hawk to automate log collection and aid the investigation.

Further Reading

Hawk PowerShell Module on GitHub

Managing CSV Files in PowerShell

How to connect to Office 365 With PowerShell

Originally published on adamtheautomator.com by writer Jeff Christman.


Join Hacker Noon

Create your free account to unlock your custom reading experience.