Docs · Microsoft Extractor Suite

Microsoft Extractor Suite

A PowerShell module for acquiring evidence from Microsoft 365, Entra ID and Azure: the Unified Audit Log, mailbox audit and message trace logs, inbox rules, OAuth permissions, and Entra ID sign-in and audit logs.

On this page

What you get 

  • The whole log, past the 5,000-record cap. Get-UAL narrows its time window until no call returns more than 5,000 records, and iterates until every window is collected.
  • Files you choose the shape of. CSV or JSON, and SOF-ELK format for several log functions, set per function. Get-UAL also writes JSONL and can merge its output into one file.
  • Microsoft 365 and Entra ID from one module. Audit, mail flow, mailbox, consent and sign-in evidence, plus configuration such as conditional access policies and role assignments.
  • Per-file SHA-256 hashes written at acquisition
  • Automatic backoff and resume against Microsoft API throttling
  • Module signing on the PowerShell Gallery

Figure 3 · What the suite collects

Functions in the public documentation, by area

Microsoft 365

  • Unified Audit Log
  • Admin Audit Log
  • Mailbox Audit Log
  • Message Trace Log
  • Inbox Rules
  • Transport Rules
  • MailItemsAccessed
  • E-mails and attachments
  • Mailbox audit status
  • Mailbox delegated permissions

Azure and Entra ID

  • Activity Logs
  • Directory Activity Logs
  • Entra ID Sign-in Logs
  • Entra ID Audit Logs
  • Conditional Access Policies
  • Device information
  • OAuth Permissions
  • User information
  • Identity Protection
  • Group information
  • License information
  • Role management
  • Security alerts
  • Secure Score
  • Start here
  • Covered on this page
  • In the documentation, not yet on this site
Grouped as in the documentation’s navigation (version 4.1.0).

Install 

Install the suite and the three Microsoft modules it relies on. Each is installed separately.

PowerShell
Install-Module -Name Microsoft-Extractor-Suite
Install-Module -Name Microsoft.Graph            # Graph API functions
Install-Module -Name ExchangeOnlineManagement   # Microsoft 365 functions
Install-Module -Name Az                         # Azure Activity log

Allow script execution for your user:

PowerShell
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Use Windows. PowerShell on macOS and Linux has known compatibility issues with the suite; a native Windows environment is strongly recommended.

If Install-Module reports that commands already exist, add -AllowClobber.

Authenticate 

Connect to the services you will collect from. Delegated sign-in uses your own permissions:

PowerShell
Connect-M365      # or Connect-ExchangeOnline · Microsoft 365
Connect-AzureAZ   # or Connect-AzAccount · Azure Resource Manager

# Microsoft Graph, for example for OAuth permissions
Connect-MgGraph -Scopes "Directory.Read.All","Application.Read.All"

Application authentication, with an app registered in Entra ID, is needed for organization-wide collection and for permissions marked “Application only”. An admin account is needed once, to consent to the Graph API scopes.

Ask for the least access that does the job. During our investigations we often ask for a Global Reader account with the View-Only Audit Logs role. An administrator account works, but it is more access than collection needs.

A few functions need more: acquiring email content through Graph uses Mail.ReadWrite, which carries write permission. It is optional; email can be acquired by other means.

Functions 

Functions on this page

Scroll horizontally on narrow screens.

Function

What it collects

Get-UAL

The Unified Audit Log: user, group, application, domain and directory activity across Microsoft 365 workloads. The primary source for a Microsoft 365 compromise. Read the entry →

Get-MailboxAuditLog

Actions on items in each audited mailbox. Now retrieved through Search-UnifiedAuditLog with RecordType ExchangeItem.

Get-MessageTraceLog

Mail flow into and out of the tenant, for up to 90 days, through Get-MessageTraceV2.

Get-MailboxRules

Inbox rules across mailboxes, written to CSV. Show-MailboxRules displays them instead. Forwarding and deletion rules surface here.

Get-OAuthPermissionsGraph

Delegated permissions and application permissions granted in the tenant.

Get-GraphEntraSignInLogs

Entra ID sign-ins: interactive, non-interactive, service principal and managed identity, all at once or by type.

Get-GraphEntraAuditLogs

The Entra ID audit log.

Start wide with Get-UAL across the window of interest, then pull mailbox, message trace and consent detail for the identities it implicates.

The 5,000-record cap 

Figure 2 · The 5,000-record cap · illustrative shape, not measured data

A single query stops at 5,000 records. Get-UAL keeps narrowing the window until nothing is left behind.

One query, whole windowSearch-UnifiedAuditLog5,000Ignored,silentlyReturnedTime windowGet-UAL, window split into intervalsEach interval stays under the capCap 5,000 per callDefault target 3,000 per intervalSame time windowevery record keptOne query, whole windowSearch-UnifiedAuditLog5,000Ignored,silentlyReturnedTime windowGet-UAL, window split into intervalsEach interval stays under the cap5,0003,000Same time windowevery record kept
The finding: Search-UnifiedAuditLog returns at most 5,000 records per call and ignores the rest without saying so. Get-UAL sizes each interval toward a target of 3,000 records (the default for -TargetEventsPerWindow) and iterates until the window is complete. Bar heights show the shape only.

The cost is time: for each interval, Get-UAL typically makes two or three API calls to make sure the interval is complete, so a large tenant takes a while.

Output layout 

Text
Output\
├─ UnifiedAuditLog\    UAL-[start].csv
├─ MailboxAuditLog\    MailboxAuditLog-[timestamp].csv
├─ MessageTrace\
├─ Rules\              [date]-MailboxRules.csv
├─ OAuthPermissions\   OAuthPermissions.csv
└─ EntraID\            sign-in and audit log JSON

Default folders, as documented. Each function takes -OutputDir to write elsewhere.

Gotchas 

The 5,000-record cap is silent. A plain Search-UnifiedAuditLog export stops at 5,000 records per query and does not report what it dropped. An export of exactly 5,000 rows is truncated, not complete.

Retention decides what is left. Audit (Standard) keeps records created on or after 17 October 2025 for 180 days, and older records for 90 days. Audit (Premium) keeps them for 365 days. Acquire before you scope.

Turning on mailbox auditing now does not recover history. New events can take up to 24 hours to appear.

Entra ID audit output is overwritten. Each run of Get-GraphEntraAuditLogs replaces the previous JSON file. Set -OutputDir per run to keep earlier acquisitions.

Times are UTC. Audit logs are recorded and exported in UTC. A date without a time means midnight.

Documentation

Pulled the logs and not sure what you're looking at?

A responder can read them with you.