Email V2

Integration version: 32.0

Prerequisites

The example described in this section is based on Gmail that provides several options to access the mailbox data from third-party applications:

1. More secure app access, enabled by default, where one could sign into a Google Account without exposing the password, and see what data the third party app will have access to and more.

   How more secure apps help protect your account

2. App password. An App password is a 16-digit passcode that gives the third-party app access to Gmail mailbox. App Passwords can only be used with accounts that have 2-Step Verification turned on.

   Sign in with app passwords

3. Less secure apps usually is for third party apps that don't follow the Google security standards for some reason. If this option is not enabled, third-party app access attempt that don't follow Google security standards to Gmail mailbox will be blocked. Enablement of this option makes Gmail account less secure, so this option should be used with caution.

   Less secure apps & your Google Account

Network Access to IMAP/SMTP

Accessing mail using IMAP and sending mail using SMTP is done using a configured account.

Configuration details: Account: Turn on access for less secure apps.

Configure Email V2 integration in Google Security Operations SOAR

For detailed instructions on how to configure an integration in Google Security Operations SOAR, see Configure integrations.

Integration parameters

Use the following parameters to configure the integration:

You can make changes at a later stage if needed. Once configured, the Instances can be used in Playbooks. For detailed information on configuring and supporting multiple instances, see Supporting multiple instances.

Actions

Ping

Test connectivity to the email server with parameters provided at the integration configuration page.

Use cases

Test connectivity to the IMAP and SMTP mail servers using the configuration parameters from the integration settings.

Run on

This action runs on all entities.

Action results

Script result

Case wall

Send Email

You may send emails from a single mailbox to a number of random recipients with this action. Users may be alerted of the outcome of such alerts by the respective alerts generated by Google Security Operations SOAR or users. The action can return the email message ID so that you will be able to use the message ID to monitor username response of this email in your "Wait for User E-mail" action. It is used to ask the user a playbook question and to operate on the playbook according to the user's answer.

Parameters

Use cases

Send notification email to list of recipients.

Run on

This action runs on all entities.

Action results

Script result

JSON result

Action returns the Mail Object technical JSON result.

If the "Return message ID for the sent email" is enabled, the action returns message_id for the sent email in technical JSON result. If the "Return message ID for the sent email" is not set, it is not required to return the message_id for the sent email.

{
    "message_id": "<4f1e50e8f4027d187a2385a39b83cde46e5b53c1-10013525-100078757@example.com>"
}

Case wall

Forward Email

Forward email including previous messages. Message_id of the email to forward needs to be provided as an action input parameter.

Parameters

Run on

This action doesn't run on entities.

Action results

Script result

JSON result

{
   Date
   message_id
   Recipient
}

Case wall

Wait for Email From User

Wait for user's response based on an email sent using the Send Email action.

Parameters

Use cases

Wait for user reply to the previously sent email by the Send Email action.

Once response is found – analyze the response in the playbook, and run additional steps if applicable.

Run on

This action runs on all entities.

Action results

Script result

JSON result

{
    "Responses":
    {[
     "user1@example.com": "Approved",
     "user2@example.com": "",
     "user3@example.com": ""
     ]}
}

Case wall

Search Emails

Search for specific mailbox emails with various search criteria given. Operation recovers details about everything in a JSON file in the mailbox. The data may be subsequently used for automatic or manual analysis.

Parameters

Use cases

Search for suspicious emails to see whether the email or similar emails were previously received for inspection from other users on the monitored mailbox.

Run on

This action runs on all entities.

Action results

Script result

JSON result

Action should return a Mail Object JSON technical result for each found email. If no emails were found- then return to "null".

{
    "emails": {
        "email_1": {
            "message id": "<CAJP=A_uGkttoWc1eahvP43rWVEsdk77nMu1FomhgRjRSmySLLg@mail.example.com>",
            "received": "Mon, 26 Aug 2019 03:20:13 -0700 (PDT)",
            "sender": "user@test.example",
            "recipients": "user1@example.com,user2@example.com",
            "subject": "Cool offer",
            "plaintext_body": "Hi, ...",
            "attachmment_1": "pdfdocument.pdf",
            "attachment_1_file_hash_md5": "3bd4a36cc0ed0bfc12ae5e2ece929e82"
        },
        "email_2": {
            "message id": "<WEAA=D_uGkttoWc1eahvP43rWVEsdk77nMu1FomhgRjRSmySLLg@mail.example.com>",
            "received": "Wen, 21 Aug 2019 03:20:13 -0700 (PDT)",
            "sender": "user@test.example",
            "recipients": "user3@example.com",
            "subject": "Cool offer",
            "plaintext_body": "Hi, ...",
            "attachmment_1": "photo.jpg",        "attachment_1_file_hash_md5": "3bd4a36cc0ed0bfc12ae5e2ece929e82",
            "attachmment_2": "word_document.docx",
            "attachment_2_file_hash_md5": "3bd4a36cc0ed0bfc12ae5e2ece929e82"
        }
    }
}

Case wall

Move Email to Folder

Move one or multiple emails from the source email folder to another folder in mailbox.

Parameters

Use cases

Move email processed in playbook to the archive folder:

Move email that was determined to be suspicious from inbox to spam:

Run on

This action runs on all entities.

Action results

Script result

JSON result

Action should return a Mail Object JSON technical result for each found and moved email. If no emails were found, null is returned.

Case wall

Delete Email

Delete one or multiple emails from the mailbox that matches the search criteria. Deletion can be done for the first email that matched the search criteria, or it can be done for all matching emails.

Parameters

Use cases

Send notification email to list of recipients.

Run on

This action runs on all entities.

Action results

Script result

JSON result

Mail Object

Action should return a Mail Object JSON technical result for each found and deleted email. If no emails were found – then return to "null".

Case wall

Save Email Attachments to Case

Save email attachments from emails stored in the monitored mailbox to the Case Wall.

Parameters

Use cases

For data retention purposes due to company standards or procedures, and due to the regulatory requirements, save the email attachments that were found to be malicious to the case wall.

Run on

This action runs on all entities.

Action results

Script result

JSON result

Mail Object

Action should return a Mail Object JSON technical result for the email from which attachments were saved.

Case wall

Download Email Attachments

Download email attachments from email to a specific path on Google Security Operations SOAR server.

Parameters

Use cases

Download attachments from email.

If the email looks malicious and file hashes for email attachment are not yet scored in VirusTotal, upload email attachments for analysis to the sandbox environment.

Run on

This action runs on all entities.

Action results

Script result

Case wall

Send Thread Reply

Send a message as a reply to the email thread.

Parameters

Run on

This action doesn't run on entities.

Action results

Script result

JSON result

{
    "message_id": "<162556278608.14165.480701790user@example>",
    "recipients": "test@example.com"
}

Case wall

Connectors

For detailed instructions on how to configure a connector in Google Security Operations SOAR, see Configuring the connector.

Generic IMAP Email Connector

The connector connects to the mail server periodically to check for new emails in a particular mailbox. If a new connector is present, an email will be sent out and a new alert will be created, which will be added with information from this email by Google Security Operations SOAR.

This topic illustrates the mechanism and configuration by which Google Security Operations SOAR connects and integrates to the IMAP/SMTP email along with supported working flows and actions taken within the platform. This topic refers to communicating with servers that support IMAP such as Gmail, Outlook.com and Yahoo! Mail.

Known issues and limitations

1. The official Python library for email, doesn't support specific attachments that are sent with the Microsoft Outlook Application. This is caused due to Outlook conversion of .msg into .eml, which results in a situation where necessary headers are missing when extracting converted .eml. Connector will catch the error and leave the following log:

   Error Code 1: Encountered an email object with missing headers. Please
   visit documentation portal for more details.
   

   Google Security Operations SOAR will still create an alert for the email, but it won't contain a Google Security Operations SOAR event based on this attachment.

2. In Generic IMAP Email Connector, when processing emails with attached mail files, if the original email attachment did not contain a filename in the Content-Disposition header, or in any other header, the following attachment filename will be assigned so it could successfully appear as an event in Google Security Operations SOAR: Undefined_{UUID}.eml.

Email case forwarding

Google Security Operations SOAR will communicate with an email server for searching emails in near real-time, and forward them to be translated and contextualized as alerts for cases.

Connector parameters

Use the following parameters to configure the connector:

In the dynamic list area, add the following rule in order to extract specific values from the email using the regular expression in the following format: Desire display name: matching regex.

For example, to extract URLs from the email, insert the following:

urls: http[s]?://(?:[a-zA-Z]|[0-9]|[$-_@.&+]|[!*(),]|(?:%0-9a-fA-F))+

Use cases

Monitor a specific mailbox for new emails for ingestion to the Google Security Operations SOAR server as alerts.

Connector rules

• The connector supports encrypted communications for email server communications (SSL/TLS).

• The connector supports connection to the mail server using proxy for both IMAP and IMAPS traffic.

• The connector has a parameter to specify the mailbox email folder to search for emails. The parameter accepts a comma-separated list of folders to check the user response in multiple folders. The parameter is case-sensitive.

• The connector supports Unicode encoding for emails processed as end user communications, which could be in a language other than English.