Microsoft Purview

Purpose

AirMDR uses Microsoft Purview during investigations, not for alerting. Darryl can rebuild an account timeline from the unified audit log, scope a phishing campaign across every mailbox, list exactly which messages matched, preserve a user’s mailbox and OneDrive with a legal hold, purge a confirmed malicious email, judge the sensitivity of a file that left the company, and read DLP and Insider Risk Management alerts and activity for a user. Every capability is optional. Grant only the permissions for the capabilities you want; when the connection is saved, AirMDR checks each one and reports which are usable.

Pre-requisites

Microsoft Entra access

Application Administrator or Cloud Application Administrator, to register the app and grant admin consent
For eDiscovery: Compliance Administrator or Organization Management in Purview, to assign Purview roles with PowerShell

Licensing

Audit log search: any Microsoft 365 plan with auditing. Records are kept 180 days, or one year for Entra, Exchange and SharePoint records of E5 users
eDiscovery: Microsoft 365 E5, or E3 with the eDiscovery and Audit add-on. Microsoft allows app-only access only to cases with premium features
Insider Risk activity and alerts: Insider Risk Management licensing, with data sharing to Defender XDR turned on

AirMDR recommends a dedicated app registration for Purview. eDiscovery permissions can search and export every mailbox, SharePoint site and Teams chat in the tenant, so keeping them on their own app lets you grant, audit and revoke them independently of the Microsoft Graph integration. Reusing the Microsoft Graph app also works.

Permissions by capability

Capability	Skills	Microsoft Graph application permission	Also required
Audit log search	Search Microsoft Purview Audit Log	`AuditLogsQuery.Read.All`	None
eDiscovery	Get / Create eDiscovery Case, Run eDiscovery Search, Manage Legal Hold, Export eDiscovery Search	`eDiscovery.ReadWrite.All`	Purview roles for the app (Step 3), premium cases
eDiscovery purge	Purge eDiscovery Search	`eDiscovery.ReadWrite.All`	Search And Purge role (Step 3)
eDiscovery report download	Export eDiscovery Search (report rows)	`eDiscovery.Download.Read` on the MicrosoftPurviewEDiscovery API	Its service principal (Step 4)
Sensitivity labels	Get Microsoft Purview Sensitivity Labels	`SensitivityLabels.Read.All`	None
File sensitivity labels	Get Microsoft Purview File Sensitivity Labels	`Sites.Read.All`	None
DLP and Insider Risk alerts	Get Microsoft Purview Alerts	`SecurityAlert.Read.All`	Insider Risk data sharing (Step 5)
Insider Risk activity	Search Microsoft Purview Insider Risk Activity	`ThreatHunting.Read.All`	Insider Risk data sharing (Step 5)

Setup

In the Microsoft Entra admin center, open Identity → Applications → App registrations → New registration.
Name it, for example AirMDR Purview, choose Single tenant, and click Register.
On the Overview page copy the Application (client) ID and Directory (tenant) ID.
Open Certificates & secrets → New client secret, choose an expiry, and copy the secret Value.
Copy the secret Value, not the Secret ID. It is shown only once.

Grant Microsoft Graph application permissions

Open API permissions → Add a permission → Microsoft Graph → Application permissions.
Add the permissions from the table above for the capabilities you want.
Click Grant admin consent and confirm.

eDiscovery only: give the app Purview roles

Graph permissions alone are not enough for eDiscovery. Find the app’s Object ID under Enterprise applications (it differs from the Application ID), then run:

Install-Module ExchangeOnlineManagement
Connect-IPPSSession
New-ServicePrincipal -AppId <Application ID> -ObjectId <Enterprise app Object ID> -DisplayName "AirMDR Purview"
Add-RoleGroupMember -Identity "eDiscoveryManager" -Member <Enterprise app Object ID>
Add-eDiscoveryCaseAdmin -User <Enterprise app Object ID>

To allow purge, also assign the Search And Purge role, for example through a custom role group that contains it.Then in the Purview portal open eDiscovery → Settings → General and turn on eDiscovery (Premium) as the default for new cases. This applies to new cases only; AirMDR also tries to enable premium features on each case it creates and warns when it cannot.

eDiscovery reports only: allow export downloads

AirMDR reads eDiscovery item reports (subject, sender, recipients, dates, location) so Darryl can see which messages a search matched. Downloads are served by a separate Microsoft application:

Connect-MgGraph -Scopes "Application.ReadWrite.All"
New-MgServicePrincipal -AppId b26e684c-5068-4120-a679-64a5d2c909d9

Then on the app open API permissions → Add a permission → APIs my organization uses → MicrosoftPurviewEDiscovery → Application permissions → eDiscovery.Download.Read, and grant admin consent.

Insider Risk only: share data with Defender XDR

In the Purview portal open Insider risk management → Settings → Data sharing and turn on sharing with Microsoft Defender XDR. Without it, Insider Risk alerts and activity never reach the API.

Usernames that Purview pseudonymizes in its own portal are returned in clear text through the API. Confirm this with your privacy team before enabling.

Add the connection in AirMDR

In AirMDR open Integrations, search for Microsoft Purview and click Add connection.
Enter the Tenant ID, Client ID and Secret Value, and save.
AirMDR requests a token and makes one real read per granted capability. A wrong or expired secret, an unknown tenant, or missing Purview roles are reported by name, and the connection shows which capabilities are usable.

Skills provided by this integration

Skill	What it does	Changes state
Search Microsoft Purview Audit Log	Searches the unified audit log: Exchange mailbox actions and cmdlets, SharePoint and OneDrive file activity, Teams, Entra sign-ins, DLP and label events. Resumable job.	No
Get Microsoft Purview eDiscovery Cases	Lists cases or reads one, including whether it is premium.	No
Create Microsoft Purview eDiscovery Case	Creates a case for an investigation.	Yes
Run Microsoft Purview eDiscovery Search	Searches mailboxes and sites and returns hit counts and sizes.	Yes (creates a search)
Export Microsoft Purview eDiscovery Search	Exports an item report and returns its rows, or exports content as PST or MSG for analysts.	Yes (creates an export)
Manage Microsoft Purview Legal Hold	Lists, creates, extends, retries or deletes legal holds that preserve evidence.	Yes
Purge Microsoft Purview eDiscovery Search	Deletes the items a search matched, up to 100 per mailbox per run. Requires confirmation.	Yes, destructive
Get Microsoft Purview Sensitivity Labels	Resolves label IDs to names and priorities, or lists the taxonomy.	No
Get Microsoft Purview File Sensitivity Labels	Reads the labels and hashes of a SharePoint or OneDrive file from its URL.	No
Get Microsoft Purview Alerts	DLP and Insider Risk Management alerts with their evidence.	No
Search Microsoft Purview Insider Risk Activity	Insider Risk data-handling events and daily behaviour insights per user and device.	No

Limits worth knowing

Audit records appear 60 to 90 minutes after the activity, so a very recent empty result is not proof of no activity.
Microsoft allows 5 eDiscovery requests per minute per app. Searches, exports and purges run as jobs; when one is still running the skill returns an ID and Darryl collects the result on a later call.
Insider Risk activity covers the last 30 days and only users in scope of Insider Risk policies.
The audit log search API is available on the Microsoft global cloud only, not GCC High, DoD or 21Vianet.

Not available through the API

Communication Compliance has no API. Insider Risk Management cases and timelines and retention labels are not reachable with app-only access, and Activity Explorer is available only through Security & Compliance PowerShell, so AirMDR does not offer them.

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Microsoft Purview

Purpose

Pre-requisites

Permissions by capability

Setup

Skills provided by this integration

Limits worth knowing

Not available through the API

​Purpose

​Pre-requisites

​Permissions by capability

​Setup

​Skills provided by this integration

​Limits worth knowing

​Not available through the API

Purpose

Pre-requisites

Permissions by capability

Setup

Skills provided by this integration

Limits worth knowing

Not available through the API