Email V2

Integration version: 25.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.

Function Default Port Direction Protocol
API Multivalues Outbound IMAP/SMTP

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:

Parameter Display Name Type Default Value Is mandatory Description
Instance Name String N/A No Name of the Instance you intend to configure integration for.
Description String N/A No Description of the instance.
Sender's Address String user@example.com Yes Email address to use in integration, for sending out emails and work with received emails for this email (mailbox)
Sender's Display Name String N/A Yes Display name of the sender.
SMTP Server Address String smtp.hmail.com Not yet configured SMTP server DNS hostname or IP address to connect to. SMTP server configuration is used for sending out emails.
SMTP Port Integer 565 Not yet configured SMTP server port to connect to.
IMAP Server Address String imap.hmail.com Not yet configured IMAP server hostname or IP address to connect to. IMAP is used in actions that work with received emails in the mailbox.
IMAP Port Integer 993 Not yet configured IMAP server port to connect to.
Username String N/A Yes Username to authenticate with on mail server
Password Password N/A Yes A password to authenticate with on email server
SMTP – Use SSL Checkbox Checked No Option to enable SSL/TLS for SMTP connection.
IMAP – Use SSL Checkbox Checked No Option to enable SSL/TLS for IMAP connection.
SMTP – Use Authentication Checkbox Checked No

Option to enable authentication for SMTP connection.

Used in cases when SMTP server is not working in "open relay" configuration and require authentication for sending out emails.

Run Remotely Checkbox Unchecked No Check the field in order to run the configured integration remotely. Once checked, the option appears to select the remote user (agent).

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
Script Result Name Value Options Example
is_success True/False is_success:False
Case wall
Result Type Value / Description Type
Output message*
  • If successful: print "Successfully connected to the email server with the provided connection parameters!"
  • If not successful IMAP: print "Failed to connect to the IMAP server! Error is {0}".format(exception.stacktrace)
  • If not successful SMTP: print "Failed to connect to the SMTP server! Error is {0}".format(exception.stacktrace)
  • If both SMTP and IMAP unsuccessful: print both errors for SMTP and IMAP
  • If both SMTP and IMAP are not configured - ping should return error.
  • For both SMTP and IMAP ping should do a separate check with separate message.
  • If at least SMTP or IMAP is configured - ping should return success, saying that it tested that is configured (IMAP or SMTP), skipped not configured part.
General

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

Parameter Type Default Value Is Mandatory Description
Recipients String N/A Yes Recipient email address. Multiple addresses can be separated by commas.
CC String N/A No CC email address. Multiple addresses can be separated by commas.
Bcc String N/A No Bcc email address. Multiple addresses can be separated by commas.
Subject String N/A Yes The subject of the email.
Content String N/A Yes The body of the email.
Attachments Paths String N/A No Comma-separated list of attachments file paths stored on the server for addition to the email.
Return message id for the sent email Checkbox Unchecked No If selected, action returns the message ID for the sent email in technical JSON result. This message ID when can be used for the "Wait for Email from user" action to process user response.

Use cases

Send notification email to list of recipients.

Use case workflow

Run on

This action runs on all entities.

Action results

Script result
Script Result Name Value Options Example
is_success True/False is_success:False
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
Result Type Value / Description Type
Output message*
  • If email sent successfully: "Mail sent successfully."
  • If email sent successfully and "Return message ID for the sent email" is enabled: "Mail sent successfully. Mail message ID is: {0}".format(message_id)
  • If error: print "Failed to send email! The Error is {0}".format(exception.stacktrace)
General

Forward Email

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

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Message ID of the email to forward String N/A Yes message_id value of the email to forward.
Folder Name String Inbox No

Mailbox folder to search email in. Parameter should also accept a comma-separated list of folders to check the user response in multiple folders.

Note that you can set mail-specific folders, for example "[Gmail]/All Mail" to search in all of the folders of Gmail mailbox. Additionally, the folder name should match exactly the IMAP folder. If a folder name contains spaces, it must be wrapped in double quotes.

Recipients CSV N/A Yes Arbitrary comma-separated list of email addresses for the email recipients.
CC CSV N/A No Arbitrary comma-separated list of email addresses to be put in the CC field of email.
BCC CSV N/A No BCC email address. Multiple addresses can be separated by commas.
Subject String N/A Yes The email subject part
Content String N/A No The email body part.
Attachment Paths String N/A No Comma-separated list of attachments file paths stored on the server for addition to the email.
Return message id for the forwarded email Checkbox Unchecked No If selected, action returns the message ID for the forwarded email in JSON technical result.

Run on

This action doesn't run on entities.

Action results

Script result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON result
{
   Date
   message_id
   Recipient
}
Case wall
Result Type Value / Description Type
Output message*

If email forwarded successfully: "Email was forwarded successfully."

If email was forwarded successfully and "Return message ID for the forwarded email" is enabled: "Mail was forwarded successfully. Mail message ID is: {0}".format(message_id)

If error: print "Failed to forward the email! The Error is {0}".format(exception.stacktrace)

General

Wait for Email From User

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

Parameters

Parameter Type Default Value Is Mandatory Description
Message ID to check replies for String N/A Yes Action should take as an input a message ID to know for which email it should track the response.
Wait for all recipients to reply? Checkbox Checked No If there are multiple recipients, parameter can be used to define that the Action should wait for responses from all of recipients to proceed or should wait for the first reply to proceed.
How long to wait for recipient reply (minutes) Integer 1440 Yes How long in minutes to wait for the user's reply before marking it timed out.
Wait stage exclude pattern String N/A No Regular expression to exclude specific replies from the wait stage. Works with body part of email. Example is, to exclude automatic Out-Of-Office emails to be considered as recipient reply, and instead wait for actual user reply.
Folder to check for reply String Inbox No Parameter can be used to specify mailbox email folder (mailbox that was used to send the email with question) to search for the user reply in this folder. Parameter should also accept comma-separated list of folders to check the user response in multiple folders. Parameter is case-sensitive.
Fetch Response Attachments Checkbox Unchecked No If selected, if recipient replies with an attachment, fetch the recipient response and add it as attachment for the action result.

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.

Use case
workflow

Run on

This action runs on all entities.

Action results

Script result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON result
{
    "Responses":
    {[
     "user1@example.com": "Approved",
     "user2@example.com": "",
     "user3@example.com": ""
     ]}
}
Case wall
Result Type Value / Description Type
Output message*
  • If email sent successfully: "Mail sent successfully."
  • If email sent successfully and "Return message ID for the sent email" is enabled: "Mail sent successfully. Mail message ID is: {0}".format(message_id)
  • If error: print "Failed to send email! The Error is {0}".format(exception.stacktrace)
General

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

Parameter Type Default Value Is Mandatory Description
Folder Name String Inbox Yes Mailbox folder to search email in. Parameter should also accept a comma-separated list of folders to check the user response in multiple folders.
Subject Filter String N/A No Filter condition, specify what subject to search for emails.
Sender Filter String N/A No Filter condition, specify who should be the sender of needed emails.
Recipient Filter String N/A No Filter condition, specify who should be the recipient of needed emails.
Time frame (minutes) String N/A No Filter condition, specify in what timeframe in minutes should search look for emails.
Only Unread Checkbox Unchecked No Filter condition, specify if search should look only for unread emails.
Max Emails To Return Integer 100 Yes Maximum number of emails to return as an action result.

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.

Use case
workflow

Run on

This action runs on all entities.

Action results

Script result
Script Result Name Value Options Example
is_success True/False is_success:False
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
Result Type Value / Description Type
Output message*
  • If successful: print "Search found {0} emails based on the provided search criteria".format(count([email_ids]))
  • If nothing found: print "Search didn't found any matching emails"
  • If error: print "Search didn't completed successfully due to error: {0}".format(exception.stacktrace)
General

Move Email to Folder

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

Parameters

Parameter Type Default Value Is Mandatory Description
Source Folder Name String N/A Yes Source folder to move emails from.
Destination Folder Name String N/A Yes Destination folder to move emails to.
Message IDs String N/A No Filter condition, specify emails with which email IDs to find. Should accept a comma-separated multiple message IDs. If message ID is provided, subject filter is ignored.
Subject Filter String N/A No Filter condition, specify what subject to search for emails.
Only Unread Checkbox Unchecked No Filter condition, specify if search should look only for unread emails.

Use cases

Move email processed in playbook to the archive folder:

Use case
workflow

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

Use case
workflow

Run on

This action runs on all entities.

Action results

Script result
Script Result Name Value Options Example
is_success True/False is_success:False
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
Result Type Value / Description Type
Output message*
  • If successful (email were found by the search criteria, move operation was successful): print message: "{0} mails were successfully moved from {1} to {2}". format(emails_count, srs_folder, dst_folder)
  • if no emails were found: print "No mails were found matching the search criteria!"
  • if error: print "Error search emails: {0}".format(exception.stacktrace)
General

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

Parameter Type Default Value Is Mandatory Description
Folder Name String N/A Yes Mailbox folder to search email in. Parameter should also accept a comma-separated list of folders to check the user response in multiple folders.
Message IDs String N/A No Filter condition, specify emails with which email IDs to find. Should accept comma-separated list of message ids to search for. If message ID is provided, subject, sender and recipient filters are ignored.
Subject Filter String N/A No Filter condition, specify subject to search for emails.
Sender Filter String N/A No Filter condition, specify who should be the sender of needed emails.
Recipient Filter String N/A No Filter condition, specify who should be the recipient of needed emails.
Delete all matching emails Checkbox Unchecked No Filter condition, specify if action should delete all matched by criteria emails from the mailbox or delete only first match.
Days Back String 0 No Filter condition, specify in what timeframe in days should action look for emails to delete. Note - Action works in days granularity only. 0 means it will search for mails from today.

Use cases

Send notification email to list of recipients.

Use case
workflow

Run on

This action runs on all entities.

Action results

Script result
Script Result Name Value Options Example
is_success True/False is_success:False
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
Result Type Value / Description Type
Output message*
  • If successful (email were found by the search criteria, delete operation was successful): print message "{0} email(s) were deleted successfully".format(email_count)
  • if no emails were found to delete: "Failed to find emails for deletion!"
  • if error : print "Error deleting emails {0}".format(exception.stacktrace)
General

Save Email Attachments to Case

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

Parameters

Parameter Type Default Value Is Mandatory Description
Folder Name String N/A Yes Mailbox folder to search email in. Parameter should also accept a comma-separated list of folders to check the user response in multiple folders.
Message ID String N/A No Message ID to find an email to download attachments from.
Attachment name String N/A No If parameter is not specified - save all email attachments to the case wall. If parameter specified - save only matching attachment to the case wall.

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
Script Result Name Value Options Example
is_success True/False is_success:False
JSON result

Mail Object

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

Case wall
Result Type Value / Description Type
Output message*
  • If successful: "Successfully saved the following attachments from the email {0}: {1}".format(message_id, attachments list).
  • If error: print "Failed to save the email attachments to the case, the error is: {0}".format(exception.stacktrace)
General

Download Email Attachments

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

Parameters

Parameter Type Default Value Is Mandatory Description
Folder Name String Inbox Yes Mailbox folder to search email in. Parameter should also accept a comma-separated list of folders to check the user response in multiple folders.
Download Path String N/A Yes Save message attachment to the given download path.
Message ID String N/A No Download attachments from specific email using its ID. For example, example@mail.gmail.com.
Subject filter String N/A No Filter condition to search emails by specific subject.

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.

Use case
workflow

Run on

This action runs on all entities.

Action results

Script result
Script Result Name Example
attachments_local_paths Script result returns string of comma-separated full paths to the saved attachments.
Case wall
Result Type Value / Description Type
Output message*
  • If successful: "Downloaded {0} attachments. \n\nFiles:\n{1}".format(len(attachments_local_paths), "\n".join(attachments_local_paths)".
  • If error: print "failed to download email attachments, the error is: {0}".format(exception.stacktrace)
General

Send Thread Reply

Send a message as a reply to the email thread.

Parameters

Name Default Value Is Mandatory Description
Message ID Yes Specify the ID of the message to which you want to send a reply.
Folder Name Inbox Yes Specify a comma-separated list of mailbox folders in which action should search for email. Note: you can set mail-specific folders, for example, "[Gmail]/All Mail" to search in all of the folders of Gmail mailbox. Additionally, folder name should match exactly the IMAP folder. If the folder name contains spaces, it must be wrapped in double quotes.
Content Yes Specify the content of the reply.
Attachment Paths No Specify a comma-separated list of attachments file paths stored on the server for addition to the email.
Reply All True No If enabled, action will send a reply to all recipients related to the original email. Note: this parameter has priority over "Reply To" parameter.
Reply To Specify a comma-separated list of emails to which you want to send this reply. If nothing is provided and "Reply All" is disabled, action will only send a reply to the sender of the email. If "Reply All" is enabled, action will ignore this parameter.

Run on

This action doesn't run on entities.

Action results

Script result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON result
{
    "message_id": "<162556278608.14165.480701790user@example>",
    "recipients": "test@example.com"
}
Case wall
Case Success Fail Message
Successful Yes No Successfully sent reply to the message with ID {message ID} in Exchange.
Fatal error, invalid creds, API root No Yes Error executing action "Send Thread Reply". Reason: {error traceback}

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:

Parameter Display Name Type Default Value Is Mandatory Description
Default Environment String N/A No Select the required environment. For example, "Customer One".
Run Every Integer 00:00:10:00 No Select the time to run the connection. For example, "every day".
Product Field Name String device_product Yes Framework parameter must be set for every connector. Describes the name of the field where the product name is stored.
Event Field Name String event_name_mail_type Yes The field name used to determine the event name (sub-type).
Additional headers to extract from emails String N/A No Extract the additional header from the email.
Script Timeout (Seconds) Integer 60 Yes The timeout limit (in seconds) for the python process running current script.
IMAP Server Address IP_OR_HOST N/A Yes IMAP Server Address to connect to.
IMAP Port Integer N/A Yes IMAP Port to connect to.
Username String N/A Yes Username for the mailbox to pull emails from, for example, user@example.com.
Password Password N/A Yes Password for the email mailbox to pull emails from.
Folder to check for emails String Inbox Yes Parameter can be used to specify email folder on the mailbox to search for the emails. Parameter should also accept comma-separated list of folders to check the user response in multiple folders. Parameter is case sensitive.
Server Time Zone String UTC No The timezone configured in the server, examples (1. UTC, 2. Asia/Jerusalem).
Environment Regex Pattern String N/A No If defined, the connector extracts the environment from the specified event field. You can manipulate the field data using the regular expression pattern field to extract a specific string.
IMAP USE SSL Checkbox Checked No Indicates whether to use ssl on connection or not.
Unread Emails Only Checkbox Checked No If checked, pull only unread mails.
Mark Emails as Read Checkbox Checked No If checked, mark mails as read after pulling them.
Attach Original EML Checkbox Unchecked No If checked, attach the original message as eml file.
Regex expressions to handle forwarded emails String N/A No Parameter could be used to specify a JSON one liner string to handle forwarded emails - to search for subject, from and to fields of original email in forwarded email.
Exclusion Body Regex String N/A No Exclude emails for which body matches specified regular expression. For example, ([N|n]ewsletter)|([O|o]ut of office) finds all emails containing 'Newsletter' or 'Out of office' keywords.
Exclusion Subject Regex String N/A No Exclude emails for which subject matches specified. For example, ([N|n]ewsletter)|([O|o]ut of office) finds all emails containing 'Newsletter' or 'Out of office' keywords.
Offset Time In Days Integer 5 Yes

Max number of days to fetch mails since.

Max Emails Per Cycle Integer 10 Yes Max count of mails to pull in one cycle.
Proxy Server Address IP_OR_HOST N/A No The address of the proxy server to use.
Proxy Username String N/A No The proxy username to authenticate with.
Proxy Password Password N/A No The proxy password to authenticate with.
Create a Separate Siemplify Alert per Attached Mail File? Checkbox Unchecked No if enabled, connector will create multiple alerts, 1 alert for every attached email file. This behavior can be useful when processing email with multiple email files attached and Google Security Operations SOAR event mapping set to create entities from an attached email file.
Original Received Mail Prefix String orig No Prefix to add to the extracted keys (to, from, subject,…) from the original email received in the monitored mailbox.
Attached Mail File Prefix String attach No Prefix to add to the extracted keys (to, from, subject,…) from the attached mail file received with the email in the monitored mailbox.

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.

Use case example

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.