> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Purview

> Use Microsoft Purview as a forensic evidence source in AirMDR investigations: unified audit log search, eDiscovery searches, item reports, legal holds and purge, sensitivity labels, and DLP and Insider Risk alerts and activity.

### 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

> [!TIP]
>
> **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

> [!TIP]
>
> **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

> [!WARNING]
>
> 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

**1. Register an app for AirMDR**

1. In the [Microsoft Entra admin center](https://entra.microsoft.com), open **Identity** → **Applications** → **App registrations** → **New registration**.
2. Name it, for example `AirMDR Purview`, choose **Single tenant**, and click **Register**.
3. On the **Overview** page copy the **Application (client) ID** and **Directory (tenant) ID**.
4. Open **Certificates & secrets** → **New client secret**, choose an expiry, and copy the secret **Value**.

   > [!WARNING]
   >
   > Copy the secret **Value**, not the Secret ID. It is shown only once.

**2. Grant Microsoft Graph application permissions**

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

**3. 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:

```powershell theme={null}
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.

**4. 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:

```powershell theme={null}
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.

**5. 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.

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

**6. Add the connection in AirMDR**

1. In AirMDR open **Integrations**, search for **Microsoft Purview** and click **Add connection**.
2. Enter the **Tenant ID**, **Client ID** and **Secret Value**, and save.
3. 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.