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:
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.
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.
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.
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* |
|
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.
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* |
|
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.
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* |
|
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.
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* |
|
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:
Move email that was determined to be suspicious from inbox to spam:
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* |
|
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.
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* |
|
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* |
|
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.
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* |
|
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
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.
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.
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.