Mass Delete with PowerShell

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

Depending on the level of security needed by your organization, you can execute the Mass Delete PowerShell script on your orchestrator’s machine 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 Office365 dependencies
  2. Choose which machine should execute the PowerShell script: one of your local machines or an orchestrator
  3. Set up the mass delete script on either machine, and any dependencies
  4. Configure the PowerShell plugin in InsightConnect

Set Up Office365 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 this user, you need to be logged in to an Office365 administrator account.

To set up a new user in Office365:

  1. Log in to Office365 as an administrator at https://office.com.
  2. Go to the admin center. In the “Apps” section that appears after login, click on the Admin quick link. If this button is unavailable upon login, you can click on the nine-tiled App Launcher icon in the top-left corner, then click on the Admin button.
  3. In the “Microsoft 365 admin center,” click on the Users option or the person icon in the left-hand navigation, then click on Active users.
  4. Click on the + Add a user option at the top of the “Active users” page.
  5. Configure the following required fields:
  • “Display Name”: We recommend naming this user something that will instantly tell you what it was created for. Consider something like “Rapid7 MassDelete” for the display name.
  • “Username”: You will use this username to configure a connection for the PowerShell plugin in InsightConnect. Consider using rapid7massdelete for easy reference. Microsoft Office will automatically append the username with your organization’s email domain.
  • “Password”: You will use this password to configure connections to PowerShell in InsightConnect or for your remote host.
  • “Roles”: Select Customized admin for now. You’ll configure any remaining permissions in the next section.
  • “Product Licenses”: Provide the service account with one of your Office365 licenses.
  1. Click Add to create the new user.

Set Up Role Groups for the PowerShell User Account

The user account you created in Office365 for use with the InsightConnect PowerShell plugin needs certain permissions. The user account needs to be a member of the following three Office365 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.

To 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.

To 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, then Save.

To 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, then 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 a Local Server

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 Office365 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 Office365 instance.

When configuring a PowerShell plugin action step:

  1. Choose PowerShell String 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.

Field

Configuration Instructions

Credentials

Leave this blank. You completed the required setup while configuring the mass delete script on your host server.

Port

This is the port number to use when connecting to your organization’s host server. PowerShell uses two defaults: 5986 for HTTPS connections or 5985 for HTTP connections. If your organization has special port configurations or you don’t know which of the default ports to use, contact your IT team for the correct port number.

Auth Type

Choose between NTLM or Kerberos, whichever you used when setting up the script on your host server.

Kerberos

If you selected Kerberos for the “Auth Type” field, you must configure this section. In the “KDC” field, add the IP address of your Active Directory server. In the “Domain Name” field, provide the fully qualified domain name (FQDN) of your host server.

  1. Click Continue after setting up and selecting the appropriate connection.
  2. Name the action step.
  3. 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.
  4. In the “Address” field, add the IP address of the host server where you saved the mass delete script.
  5. In the “Host Name” field, add the case-sensitive FQDN for the host server where you saved the mass delete script.
  6. Click Continue to save the step.

Set Up Mass Delete with an Orchestrator

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.

Whitelist the Orchestrator IP

If you don’t whitelist connections from the orchestrator IP, the PowerShell plugin will not be able to connect to the online Microsoft Exchange server.

  1. 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>”,`
  1. 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.

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.

Field

Configuration Instructions

Credentials

Add a new credential, naming it something that indicates to you that the credential is for mass delete actions. In the “Password” field, add the password you created for the Office365 user you set up earlier. In the “Username” field, add the full username (which should look like “username@organization.domain”) you created for the Office365 user you set up earlier.

Port

Set this field to 5986.

Auth Type

Select None for this field.

Kerberos

Leave this field blank. You don’t need to configure this field if you saved the mass delete script to an orchestrator.

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