Mass Delete with PowerShell

You can use the PowerShell plugin and a script written by the InsightConnect team to mass-delete items in your Office 365 instance.

You may choose to execute the Mass Delete PowerShell script on your Insight Orchestrator or on a separate server owned by your organization.

To use the PowerShell plugin with the InsightConnect mass delete script, you need to:

1. Set Up all Dependencies in Office 365
2. Choose which machine should execute the PowerShell script: your Insight Orchestrator or another server in your environment
3. Set up the mass delete script on either machine, and any dependencies
4. Configure the PowerShell plugin in InsightConnect

Set Up Office 365 Dependencies

Before you run the Mass Delete script in InsightConnect, you need to set up dependencies for Office 365.

Set Up a New User for Office 365

You will need to create a new user in your Office 365 instance that has the appropriate permissions in order to communicate with InsightConnect. To create user, please reffer to this document Microsoft Office 365 Email Security Plugin Setup Guide as this is also relevant for Powershell plugin configuration.

Set Up Role Groups for the PowerShell User Account

The user account you created in Office 365 for use with the InsightConnect PowerShell plugin needs certain permissions. The user account needs to be a member of the following three Office 365 role groups:

• eDiscovery Manager
• Compliance Administrator
• Organization Management

Learn more about these groups at https://docs.microsoft.com/en-us/office365/securitycompliance/permissions-in-the-security-and-compliance-center

To assign this user the correct permissions in the Microsoft 365 admin center:

1. Click on the down arrow on the Admin centers option in the left navigation panel, then click on Security & compliance.
2. In the Office 365 Security & Compliance admin center, click on the Permissions option in the left navigation panel.
3. Check the list of permissions role groups for eDiscovery Manager, Compliance Administrator, and Organization Management. These are default role groups set up by Microsoft. Then add members to each role group following the instructions below.

Configure the eDiscovery Manager role group

1. Click on eDiscovery Manager in the list to open a side panel with that role’s details, then click the Edit role group button at the top of the panel.
2. Click on the eDiscovery Manager tab in the list of editing options.
3. Click on the Choose eDiscovery Manager link, then click the Add button. Locate the new user you created earlier and check the box next to their name. If you used our suggested Display Name, this will be Rapid7 Mass Delete.
4. Click Add, then Done, then Save to save these settings.
5. Then click on the X in the upper right corner of the configuration panel to complete editing the eDiscovery Manager role group.

Configure the Compliance Administrator group

1. Click on the group name in the list of permissions, then click the Edit role group button at the top of the configuration panel that appears. Then click on the Edit link.
2. Click the Add button, find the user you created earlier, then check on the box to add that user to this role group.
3. Click the Add button, then Done, and Save.

Configure the Organization Management group

1. Click on the group name in the list of permissions, then click the Edit role group button at the top of the configuration panel that appears. Then select the Choose members option and click the Choose members link.
2. Click the + Add button, find the user you created earlier, then check on the box to add that user to this role group.
3. Click the Add button, then Done, and Save.

After adding your new user to each of the three Office 365 role groups, you can exit out of the Office 365 Security & Compliance admin center.

Set Up Mass Delete with an Orchestrator (option 1)

Alternatively, you can execute the mass delete script on an orchestrator you provisioned for InsightConnect. This saves you more time and resources during setup, but isn’t as secure as executing the script with your own local server.

To use the mass delete script with your orchestrator:

1. Whitelist the orchestrator IP on any multifactor authentication services you use.

2. Edit the mass delete PowerShell script after getting the script at https://gist.github.com/jschipp-r7/56bf75a86a121fcf959e821055ba0348. Enter the username and password on their respective lines in the param section of the script according to this example:

 
1
param (
2
    [string]$Username = "<O365 service user username>",
3
    [string]$Password = ''<O365 service user password>”,`

3. Next, add the sender address and subject line details for the emails you’d like to mass delete from your organization. Paste these into the $ContentMatchQuery line in the script according to this example:

 
1
$ContentMatchQuery = '(from='+ $Sender + “<sender email address>” ')(subject="' + $Subject + “<email subject line>” '")'

Now you’re ready to use the PowerShell plugin to mass delete items in your Office365 instance.

Configure the PowerShell Plugin for Mass Delete

When configuring a PowerShell plugin action step:

1. Choose PowerShell Script for the step’s action.
2. If you don’t already have a mass delete-specific connection for the PowerShell plugin, click + Add a New Connection to create one. Configure this connection according to the instructions in this table.

3. Click Continue after setting up and selecting the appropriate connection.
4. Name the action step.
5. In the “Script" field, paste the Mass Delete script you edited earlier.
6. Leave the “Address” field blank.
7. Leave the “Host Name” field blank.
8. Click Continue to save the step.

Set Up Mass Delete with a Local Server (option 2)

Executing the script using your organization's local server allows you to secure your service account credentials on the server itself.

To use the mass delete script with your local server:

1. Use Microsoft’s New Technology LAN Manager (NTLM) protocols or Kerberos to authenticate to a remote host.
2. Secure credentials for your Office 365 account on your local server with the instructions at https://practical365.com/blog/saving-credentials-for-office-365-powershell-scripts-and-scheduled-tasks/.
3. Save the mass delete PowerShell script to the server. Get a copy of the script at https://gist.github.com/jschipp-r7/56bf75a86a121fcf959e821055ba0348.
4. Edit the script to use the secured credentials you set up in Step 2.
5. Find and take note of this server’s IP address and hostname.

Now you’re ready to use the PowerShell plugin to mass delete items in your Office 365 instance.

Configure the PowerShell Plugin for Mass Delete

When configuring a PowerShell plugin action step:

1. Choose PowerShell Script for the step’s action.
2. If you don’t already have a mass delete-specific connection for the PowerShell plugin, click + Add a New Connection to create one. Configure this connection according to the instructions in this table.

3. Click Continue after setting up and selecting the appropriate connection.
4. Name the action step.
5. In the “Script” field, add the command needed to run the Mass Delete script on the remote server. The command will differ depending on how you set up your server, but it should use the format <path to script> -Subject <subject> -Sender <sender>, replacing the variables with the subject line and sender address of the email you want to mass delete from your Exchange servers.
6. In the “Address” field, add the IP address of the host server where you saved the mass delete script.
7. In the “Host Name” field, add the case-sensitive FQDN for the host server where you saved the mass delete script.
8. Click Continue to save the step.