The Problem
When a phishing message reaches multiple mailboxes, or a trusted third party notifies us that one of their accounts has been compromised and used to send mail into our tenant, the priority is removing those messages from user mailboxes as quickly as possible. Doing that manually through Purview means building the content search by hand, waiting on it, and stepping through the purge workflow. For a handful of mailboxes that is roughly 5 to 15 minutes of hands-on work per incident, and it scales badly as the number of affected recipients grows. Speed matters, because every minute the message sits in an inbox is another chance someone interacts with it.
What I Built
An interactive PowerShell tool for tenant-wide search and purge of malicious email. It collects the sender, exact subject, and date range, builds a compliance search across all mailboxes, previews the matches, and then soft-deletes them on explicit confirmation. The tool is deliberately built with guardrails at every destructive step, because it operates across the entire tenant.
Safety and Controls
- Just-in-time privilege enforcement: before doing anything, the script queries Microsoft Graph to verify that Global Administrator is actively elevated through Entra PIM for the running user. If the role is not active, the script refuses to continue. Standing privilege is never assumed.
- Mandatory non-destructive preview: a preview action always runs before any purge is possible, so matches can be reviewed in Purview first.
- Typed confirmation: the purge requires typing an exact confirmation phrase, and any other input loops rather than proceeding. Accidental keypresses cannot trigger a deletion.
- Soft delete rather than hard delete, so removed messages remain recoverable.
- Dual audit logging: every run writes both a CSV and a JSON record capturing the operator, the exact search query used, the date range, item count, whether the purge was confirmed, the machine it ran from, and the script version. This produces a defensible record of who removed what and when.
- Pinned module versions imported by explicit path, so a module update cannot silently change the behavior of a tool that deletes mail tenant-wide.
- Unique timestamped search names per run, and a search-only session for the compliance connection.
- Input validation on all fields, including UPN and email format checks and date range sanity checking, before any connection is made.
How It Runs
Run on demand by a Global Administrator, since the required Purview roles are intentionally restricted to that group. It is used for incidents where more than a handful of messages were delivered, where manual cleanup would be impractical.
Impact
- Reduces tenant-wide phishing containment from a manual multi-step Purview workflow to a single guided run
- Removes malicious mail from every affected mailbox in one operation rather than one at a time
- Enforces just-in-time privilege and produces a complete audit trail for every destructive action
- Keeps removed messages recoverable through soft delete