Skip to main content
Lantern Home

 

Splunk Lantern

Setting up a Google Workspace abuse mailbox asset in Enterprise Security using the IMAP v2 app

  1. Last updated
  2. Save as PDF

When employees report suspected phishing emails, security teams must quickly distinguish genuine threats from spam and false positives. As reporting volumes grow, manual triage can delay the identification of malicious messages and increase the risk of account compromise and data loss.

This article shows you how to install and configure the IMAP v2 app asset used by Automated Threat Analysis (ATA) in Splunk Enterprise Security to ingest user-reported phishing messages from a Google Workspace mailbox through IMAP and OAuth. After configuration, messages in the selected mailbox folder are polled and analyzed automatically, with the results and sandbox screenshots surfaced as findings in Splunk Mission Control, so analysts can prioritize credible threats and respond consistently.

Prerequisites

  • Splunk Enterprise Security Premier Cloud version 8.5 or later.
  • Permission to install Splunk SOAR apps and configure assets from Splunk Enterprise Security.
  • IMAP and OAuth access allowed on the target Google Workspace mailbox.
  • Existing Google Cloud project for the mailbox integration, with the Google Auth Platform OAuth consent configuration already prepared.
  • Appropriate permissions to create OAuth clients in Google Cloud.

If you have an existing configured asset and are upgrading to a newer app version, select Clone Asset from the asset's three-dot menu. Cloning carries forward the current asset configuration, so you do not need to re-enter credentials or other settings. The cloned asset also exposes the new options available in the updated app version.
clipboard_f89b7c8f-6754-4ded-b138-c78f8621568d.png

Step 1: Install the IMAP v2 app from Splunk SOAR

► Click to expand
  1. Log in to Splunk Enterprise Security and navigate to Configure > Splunk SOAR > Apps.
  2. Search for the IMAP v2 app.
    • If the app appears, proceed to Step 2.
    • If the app does not appear, installation must be completed in Splunk SOAR. Continue with the steps below.
  3. In Splunk SOAR, navigate to Home > Apps.
  4. Search for IMAP v2 in the Configured Apps and Unconfigured Apps tabs.

    clipboard_a6137621-9048-4c5d-99cc-0596938658b2.png

  5. If there are no results under either tab, click New Apps.

    clipboard_99b0f970-b3c4-4579-bfac-62840752dbbc.png

  6. Search for IMAP v2 and click Install.

After installation is complete, the IMAP v2 asset configuration takes place within Splunk Enterprise Security.

Step 2: Configure the IMAP v2 asset in Enterprise Security

► Click to expand
  1. Navigate to Enterprise Security > Mission Control.
  2. From the top menu bar, click Configure > Splunk SOAR.

    clipboard_c9a287c4-7a74-44a1-8e5c-c63e2848a5fb.png

  3. In the left menu, click Apps.
  4. Search for IMAP v2 and click View to access the asset configuration page.

    clipboard_3b3c2429-c7a7-43aa-ad14-a3bac8653feb.png

  5. Click Configure New Asset.

    clipboard_cd5c5db7-f080-4e99-8d02-3e88e0b0380f.png

  6. On Asset Settings, fill in the required mailbox fields.
    Field Value
    Asset Name A descriptive name, such as abuse_mailbox
    Server IP/Hostname imap.gmail.com
    Username The Google Workspace mailbox address to poll for incoming abuse messages
    Folder to ingest mails from The folder within the mailbox where abuse-reported messages are routed, for example inbox
    How to ingest oldest first in the new-asset flow
    Maximum emails to poll first time for schedule and interval polling 2000
    Maximum emails to poll 50
  7. Stop when you reach Configuration Settings and open a new browser tab to continue with Step 3.

Step 3: Create a Google OAuth client

► Click to expand
  1. Open the Google Cloud Console and confirm that you are in the correct Google Cloud project.
  2. Search for Clients in the top search bar.
  3. Click Create client.

    clipboard_c004c466-fa11-4960-9458-e7b2f85f09dd.png

  4. For Application type, click Web application.

    clipboard_bca28638-5ccc-4f21-9bdf-6e0dd971d58b.png

  5. Enter a descriptive client name, such as Splunk_ES_Abuse_Mailbox_Ingest.
  6. Leave Authorized JavaScript origins empty unless your environment specifically requires one.
  7. Leave Authorized redirect URIs blank for now. You will add the URI after running Test Connectivity.
  8. Click Create.

    clipboard_9e159b40-9b25-459c-826a-7536d0cec33e.png

  9. After the client is created:
    • Note the Client ID.
    • Note the Client secret.
    • Click Download JSON to save the credentials.

      clipboard_6ba1b2a2-66b0-44bf-bb71-c35404d1d491.png

Step 4: Complete OAuth settings in Enterprise Security

► Click to expand

Return to the IMAP v2 asset in Splunk Enterprise Security. Under Configuration Settings, fill in the following fields using the values from the Google OAuth client you created.

Field Value
Authentication mechanism to use OAuth
Password Leave blank for OAuth
OAuth Client ID Client ID from Google Cloud
OAuth Client Secret Client secret from Google Cloud
OAuth Authorization URL https://accounts.google.com/o/oauth2/auth
OAuth Token URL https://oauth2.googleapis.com/token
OAuth API Scope (JSON formatted list) ["https://mail.google.com/"]

clipboard_f5386053-87e1-4368-b3e7-0558b0c89b05.png

Step 5: Configure ingest settings in Enterprise Security

► Click to expand
  1. To move to Ingest Settings, click Next.
  2. Select the desired values for Investigation type, Security domain, and Urgency. Creating an Investigation type of phishing is recommended to distinguish these incoming findings.
  3. Set your polling preferences.
  4. Under Additional settings, confirm that the following options are selected:
    • Run threat analysis: When selected, polled messages are sent to ATA for sandboxing and analysis.
    • Launch automation after threat analysis is complete: When selected, associated Splunk SOAR automation playbooks run after ATA analysis is complete.

      clipboard_417a43a9-a0f0-4b93-b12e-0eb437448958.png

Step 6: Review optional asset tabs in Enterprise Security

► Click to expand

The asset configuration page includes the following optional tabs. Review them and configure any that apply to your environment before saving the asset.

  • Automation Broker: Specify whether the asset must run through a specific automation broker.
  • Additional Settings: Optionally add an asset description or tags.
  • Access and Approvals: Configure secondary approvers only if your process requires them.

Step 7: Activate the webhook service in Splunk SOAR

This step is only required if you configured OAuth authentication in Step 3. If you used a different authentication type, this step is optional.

► Click to expand
  1. In Splunk SOAR, navigate to Home > Administration.
  2. Navigate to Administration Settings > Webhook Settings and confirm that webhooks are enabled.

    clipboard_488f4bf0-2fe2-4ff1-ada6-a05112d4a309.png

Step 8: Enable webhooks for the asset in Enterprise Security

This step is only required if you configured OAuth authentication in Step 3. If you used a different authentication type, this step is optional.

► Click to expand
  1. Back in the IMAP v2 asset configuration in Splunk Enterprise Security, click Next to advance to Webhook Settings. If you closed the ES tab, refer to Step 2 for navigation instructions.
  2. Select Enable webhooks for this asset.
  3. Click Save.

    clipboard_6c7be1cb-ac83-4f1e-9173-1142a27f70a1.png

Step 9: Retrieve the URI via Test Connectivity in Enterprise Security

► Click to expand
  1. Click Save and then click Test Connectivity. The URI is presented in a new modal.

    clipboard_a546f6cf-6735-41cd-90e9-de34662c4b2f.png

  2. Note the URI and click Close.

The URI is also visible in the asset configuration under the Webhook Settings section after saving.

Step 10: Add the URI to the Google OAuth client

► Click to expand
  1. Navigate back to the Google OAuth client you created in Step 3.
  2. Select the asset and click Add URI.
  3. Paste the URI from the previous step.
  4. Click Save.

    clipboard_7f0c7e61-ccd0-40a6-8fca-7f243a1f1a41.png

Step 11: Complete Test Connectivity and verify polling in Enterprise Security

► Click to expand
  1. Navigate back to the IMAP v2 asset in Splunk Enterprise Security and click Test Connectivity.
  2. From the pop-up, copy the Google Consent prompt URL and open it in a new browser tab.

    clipboard_3d0938d4-ceaa-4723-9c5b-2d2da8a1fa50.png

  3. Sign in to the abuse mailbox you specified in the asset configuration.

    clipboard_72446dc5-6847-4810-b4ee-4bcce72d3e14.png

  4. Click Allow.

    clipboard_b3fe0f27-b231-4c2a-be1b-79098ac538e2.png

  5. Confirm that you are redirected to an Authorization successful page.

    clipboard_13387acc-0fd0-4dfb-9c69-5da012ac2688.png

The asset configuration is now complete. The specified abuse mailbox is polled based on the interval or schedule you defined.

clipboard_db7683ff-010c-4bd6-a2e5-a2c8b0f86f70.png

Troubleshooting

  • If Google rejects the redirect, confirm that the authorized redirect URI exactly matches the SOAR-generated URI, including host, port, path, generated ID, asset ID, and trailing /result.
  • If OAuth consent fails, confirm that the mailbox user is allowed to use the Google Cloud OAuth app.
  • If IMAP login fails, confirm that IMAP is activated for the mailbox and allowed by Google Workspace admin policy.
  • If polling succeeds but no emails appear, confirm that the folder name (for example, inbox) is correct, and adjust the first-poll and maximum-poll values.
  • If Gmail blocks access, verify that the scope is exactly ["https://mail.google.com/"] and that the OAuth client secret was copied from the same Google client used in the asset.

Next steps

You might find the following resources useful for implementing the guidance in this article: