Ctrlk
Go to Workbench
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Google Workspace (Formerly G Suite): Remove Malicious Email

This guide helps you set up your Google Workspace device and grant necessary permissions so that you can enable the Remove Malicious Email auto remediation in Workbench.

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.

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.

The remediation runs per recipient mailbox (domain-wide delegation, impersonates each user). The messages are moved to Trash, where they are recoverable, rather than being permanently deleted.

Endpoints Used

Gmail API

gmail/v1 via the google-api-python-client SDK, messages located via BigQuery Gmail logs

Method
Endpoint
Purpose

Query

BigQuery Gmail logs (gmail_logs_dataset)

Find recipients and candidate messages by subject, sender, time window

GET (messages.list)

gmail/v1/users/me/messages?q=rfc822msgid:{id}

Search the recipient's mailbox for the exact message

GET (messages.get)

gmail/v1/users/me/messages/{id}

Read labels, thread ID, headers (skip if already trashed)

POST (messages.trash)

gmail/v1/users/me/messages/{id}/trash

Move the message to Trash

Reversible via messages.modify and removing the TRASH label.

Step 1: Allow Appropriate Permissions

  1. Make sure you assign all API permissions in the Google Workspace (formerly G Suite) Setup for Workbench guide.

  2. From the same project you created during onboarding for Google Workspace, search for Gmail API and select it.

    Gmail API search result in the Google Workplace Marketplace.

  3. Enable the Gmail API permissions for the project by selecting Enable.

  4. In the Google Workspace admin console, navigate to Domain-wide Delegation: https://admin.google.com/ac/owl/domainwidedelegation.

  5. Locate the API Client created for the Service Account during onboarding, and then select Edit.

    API client list shows the service account.

  6. Add the following OAuth scope:

    • https://www.googleapis.com/auth/gmail.modify

      The OAuth scope is added to the Edit scopes list.

  7. Select AUTHORIZE.

Step 2: Enable Google Workspace Logs in BigQuery

  1. Confirm you are signed in to the Google Admin console with a super administrator account. You cannot complete these steps without super admin permissions.

  2. Navigate to Reporting > Data integrations.

  3. Choose the BigQuery Export card and select Edit.

  4. To activate BigQuery logs, select the Enable Google Workspace data export to Google BigQuery checkbox.

    1. Under BigQuery project ID, select the project created for the Google Workspace integration.

    2. Under New dataset within the project, enter gmail_logs_dataset as the name for the new BigQuery dataset. If you require a custom dataset name, please reach out to Expel Support for assistance. Providing the custom name allows us to properly configure this feature.

  5. Select Save.

  6. In the same project for the Google Workspace integration, navigate to the IAM & Admin console. Find the previously created service account, select the pencil icon, and then add the role BigQuery Job User to the service account.

    IAM and Admin Permissions list shows the service account.

  7. Search for and add BigQuery Job User, and then select Save.

    BigQuery Job User role is selected on the Edit permissions screen.

  8. In the Google Cloud console, navigate to BigQuery: https://console.cloud.google.com/bigquery

  9. Find the gmail_logs_dataset created in Step 2.

  10. Open the dropdown menu using the three dots on the right, and then select Open.

  11. On the Dataset info screen, select EDIT DETAILS in the top right.

    gmail_logs_dataset info details page.

  12. Select Enable table expiration. Enter the length of time to retain the log tables, and then select SAVE. Default retention is set to 60 days, but we recommend 30 days.

    Enable table expiration box is checked and 30 is entered into the Default maximum table age field.

  13. Select SHARING > Permissions.

    gmail_logs_dataset info details screen with Permissions selected.

  14. Select Add principal.

  15. Under New principals, add the service account, and then select the role BigQuery Data Viewer.

    The service account and BigQuery Data Viewer role are added.

  16. Select SAVE.

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 Google Workspace 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.

Last updated

Was this helpful?