Microsoft Entra ID via Event Hub: Remove Malicious Email

This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the Enable an Auto Remediation in Workbench guide to finish your setup.

This guide helps you set up your Microsoft Entra ID via Event Hub device so that you can enable the Remove Malicious Email auto remediation in Workbench. During the setup process, you will grant Expel all necessary permissions for the remediation to work.

How It Works

If our SOC identifies an email that must be removed, Workbench completes the action automatically unless it is specifically called out as a "Never remove" asset (the inboxes must first be added as context and then configured in Workbench; see Step 3). Quarantine inboxes are often called out as "Never remove" assets.

Endpoints Used

Microsoft Graph API

v1.0, messages located depending on the tenant (Exchange Online PowerShell for migrated tenants or the Reporting Web Service for legacy tenants)

Method	Endpoint	Purpose
GET	v1.0/servicePrincipals(appId='{client-id}')/appRoleAssignments	Detect migrated vs. legacy tenant (picks the message trace path)
Powershell	Connect-ExchangeOnline, Get-MessageTraceV2, Disconnect-ExchangeOnline	For migrated tenants. Open an Exchange Online session using the Graph-issued access token; locate delivered messages by sender, time range, and subject; use this info to build the recipient list; close the Exchange Online session
GET	reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace?$filter=SenderAddress eq '{sender}' and StartDate eq datetime'{start}' and EndDate eq datetime'{end}'&$format=json	For legacy tenants (fallback). Locate delivered messages by sender and time; use this info to build the recipient list
GET	v1.0/users?$filter=mail eq '{recipient}'	Use recipient email to find the username
GET	v1.0/users/{user}/messages?$filter=internetMessageId eq '{id}'	Find the message in the mailbox
GET	v1.0/users/{user}/messages?$filter=receivedDateTime ge {received-25h} and receivedDateTime le {received+25h}&$select=id,subject,parentFolderId,from,receivedDateTime	Fallback when the exact message ID lookup returns nothing; page the mailbox and match subjects carrying a prepended tag
GET	v1.0/users/{user}/mailFolders/deleteditems	Get the Deleted Items folder ID
POST	v1.0/users/{user}/mailFolders/{folder}/messages/{msgId}/move	Move the message to Deleted Items

Reversible via the revert capability, which moves the message back to its original folder.

Prerequisites

1. You must install and activate Microsoft 365 Message Trace so that we can automatically remove the malicious email from other inboxes. For instructions, see Microsoft 365 Message Trace Setup.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.
3. You must have already completed all of the steps in Microsoft Entra ID via Event Hub Setup for Workbench.

Step 1: Assign the SecurityReader Role

The SecurityReader role allows us to perform a message trace or search your instance when we identify an email that needs remediation. This role provides read-only access.

1. Log in to the Azure portal.
2. Navigate to the Microsoft Entra ID service.
3. Go to Manage > Roles and administrators.
4. Use the search bar to locate the Security Reader role, then select it to view its assignments.
5. Select Add assignments.
6. Use the search box under Select member(s) to locate your custom app. You are searching for the app's service principal, which usually has the same name as the app registration.
7. Select your app, then choose Add. You should now see the app's service principal listed as an active member of the Security Reader role.

Step 2: Add Additional API Permissions

The Exchange.ManageAsApp permission allows us to connect to PowerShell to run the necessary commands to remove an email. The Mail.ReadWrite permission supports our fallback code for if/when email removal via the Exchange method fails.

1. Navigate to the App registrations page in the Azure portal: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade
2. Find and select the custom app you created when you set up your security device.
3. In the left menu, go to Manage > API permissions.
4. Select Add a permission.
5. Locate the Office 365 Exchange Online API and add the following two permissions as application permissions (not as delegated permissions):

   • Exchange.ManageAsApp
   • Mail.ReadWrite
6. Make sure to Grant admin consent for both permissions.

Step 3: Update Your Context

If you do not want to specify any inboxes for a "do not remove" list, skip to Step 4. Quarantine inboxes are often called out as "Never remove" assets.

Working with your Customer Success Manager (CSM), add any inboxes that should be on the "do not remove" list as org context for your environment. You will then be able to select those inboxes as "Never remove" assets when you enable the auto remediation in Workbench.

If our SOC identifies an email that must be removed, any emails from inboxes added as "Never remove" assets are assigned to you as actions rather than being removed automatically.

Step 4: Return to the Main Setup Guide

Your Microsoft Entra ID via Event Hub device is now ready for the Remove Malicious Email auto remediation. You should now do one of the following:

• If you do not need to set up any other devices for this auto remediation, you can return to the Enable an Auto Remediation in Workbench guide to finish Step 2 of the process.
• If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations, be sure to complete those setup guides as well before returning to the Enable an Auto Remediation in Workbench guide to finish Step 2 of the process. Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.