Exchange

Integration version: 100.0

Configure the integration to work with Exchange Server and Google Security Operations SOAR

Integration configuration prerequisites

Configure Exchange Server authentication

Depending on whether the integration is configured for the Exchange Server (on-premises version) or Exchange Online (cloud service), the configuration steps are different.

Exchange Server uses basic authentication with username and password for the authentication.

Complete the following steps to set up basic authentication:

  1. Determine that Exchange Server (one of the servers in the cluster) is accessible from the Google Security Operations SOAR server. Verify if:

    • Exchange Server DNS name is resolving

    • Exchange Server IP address is accessible (pings, has open ports)

    • Exchange Web Services (EWS) is used for the integration, which is usually hosted on the 443 port (HTTPS). Make sure that EWS is enabled and hosted on a port accessible to the Google Security Operations SOAR server.

    If the Exchange Server is not accessible from Google Security Operations SOAR server, consider using the remote agent.

  2. Provide the integration with a working username (user mailbox) and respective password. Choose the user you want to use in the integration.

  3. For actions that can be performed on other mailboxes that the user have access to through delegated/impersonated permissions:

    1. Verify that the configured mailbox has delegated/impersonated access to the needed mailboxes. We recommend you to configure the access with impersonated permissions. For more information about impersonated permission, see Impersonation and EWS in Exchange.

    2. Make sure that the user (mailbox) configured for the integration has the following Exchange Roles to access other mailboxes:

Integration installation and configuration

Install and configure the integration

For instructions about how to install and configure the integration on Google Security Operations SOAR, see Configure Integrations.

Integration configuration parameters

Use the following parameters to configure the integration to work with Exchange Server:

Parameter name Type Required Description Example value
Mail Server Address String Yes Mail server address (hostname or IP) to connect to. 172.30.202.26
Mail address String Yes Mail address used in the integration to work with sent and received emails in the mailbox. exchange_onprem_test@exlab.local
Username String Yes Username to authenticate with on the mail server. exchange_onprem_test@exlab.local
Password Password Yes Password to authenticate with on the mail server. <user password>

To successfully configure the integration:

  • provide the Username parameter as exchange_onprem_test and set exlab.local as a domain

  • select the Use Domain for Authentication checkbox

Configure the integration to work with Exchange Online and Google Security Operations SOAR

Integration configuration prerequisites

Configure Exchange Online authentication

Depending on whether the integration is configured for the Exchange Server (on-premises version) or Exchange Online (cloud service), the configuration steps are different.

The integration for Exchange Online only supports OAuth delegated authentication with delegated tokens, which requires additional configuration.

Complete the following steps to set up OAuth delegated authentication:

  1. Determine that Exchange Online is accessible from the Google Security Operations SOAR server. Verify if:

    • Exchange Online DNS name is resolving.

    • Exchange Web Services (EWS) is used for the integration, which is usually hosted on the 443 port (HTTPS). Make sure that EWS is enabled and hosted on a port accessible to the Google Security Operations SOAR server.

    If the Exchange Server is not accessible from Google Security Operations SOAR server, consider using the remote agent.

  2. Provide the integration with a working username (user mailbox). Choose the user you want to use in the integration. To impersonate the user, create an Azure application.

  3. Make sure that the user (mailbox) has an Microsoft 365 license assigned. For example: Microsoft 365 E5 license.

  4. For actions that can be performed on other mailboxes that the user have access to through delegated/impersonated permissions:

  5. Verify that the configured mailbox has delegated/impersonated access to the needed mailboxes. We recommend you to configure the access with impersonated permissions. For more information about impersonated permission, see Impersonation and EWS in Exchange.

  6. Make sure that the user (mailbox) configured for the integration has the following Exchange Roles to access other mailboxes:

  7. Create an Azure application that will be used to impersonate the desired user:

    1. Navigate to Azure Active Directory in the Azure portal.

    2. Go to App registrations and click New registration.

    3. Enter the name of the app, select suitable Supported account types, add Redirect URI - platform: Web, redirect URL: http://localhost.

    4. Create the application.

    5. In the Overview tab of the application, you will find the Application (client) ID and Directory (tenant) ID parameters. These parameters are used as the Client ID and Tenant ID parameters in the integration configuration dialog.

    6. Go to the API Permissions tab and click Add a permission.

    7. Select Microsoft Graph to add permissions and then select Delegated permissions.

    8. In the Select Permissions dialog, scroll to the EWS section and select Ews.AccessAsUser.All.

    9. Grant Admin Consent for the added permissions.

    10. Navigate to Certificates and secrets, scroll down and click New client secret.

    11. Create a new secret. Copy the value of the client secret and not the secret ID. Copied value is used as the Client Secret parameter in the configuration dialog.

    12. Next configure the Exchange integration with the following parameters from the previous steps: Client (Application) ID, Tenant (Directory) ID, Client Secret and Redirect URI.

  8. We recommended you to create a custom scope for the assignment of the ApplicationImpersonation role so the configured application could impersonate only specific Microsoft 365 users (mailboxes). For more information, see Configure impersonation. Here is an example of how to assign the ApplicationImpersonation role with a custom scope filter using following commands:

    1. New-ManagementScope -Name:scopeJB -RecipientRestrictionFilter:"Alias -eq 'user.alias'"
    2. New-ManagementRoleAssignment -Name:impersonationAssignmentTestJB -Role:ApplicationImpersonation -User:user.alias@company.onmicrosoft.com -CustomRecipientWriteScope:scopeJB

The authentication configuration is completed. Use the created Azure Application to generate a refresh token that is required to configure the integration in the Google Security Operations SOAR platform.

Integration installation and configuration

Install and configure the integration

For instructions about how to install and configure the integration on Google Security Operations SOAR, see Configure Integrations.

Integration configuration parameters

Use the following parameters to initially configure the integration to work with Exchange Online:

Initial configuration parameters

Parameter name Type Required Description Example value
Mail Server Address String Yes Mail server address (hostname or IP) to connect to. outlook.office365.com
Mail address String Yes Mail address to use in the integration to work with sent and received emails in this mailbox. exchange_onprem_test@exlab.local
Client ID String Yes Client (Application) ID of the Azure Active Directory app that is used for the integration. For more information about how to get this parameter value, see Configure Exchange Online authentication. d9a0333a-3786-4499-8170-x0x00000x000
Client Secret Secret Yes Secret that is generated during creating the Azure Active Directory app used for the integration. For more information about how to get this parameter value, see Configure Exchange Online authentication. _mM8Q~CL8dJB8yONYResC6imBrJGMby3XXX~XXXX
Tenant (Directory) ID String Yes Tenant (Directory) ID of the Azure Active Directory app that is used for the integration. For more information about how to get this parameter value, see Configure Exchange Online authentication. d48f52ca-5b1a-4708-8ed0-xxx00x00x00x
Redirect URL String Yes Redirect URI that is configured in the Azure Active Directory app used for the integration. For more information about how to get this parameter value, see Configure Exchange Online authentication. Keep default to http://localhost

Generate a refresh token

  1. Run the Get Authorization action. Use a test Google Security Operations SOAR case to run the action as manual.

    1. Go to the Cases tab, click Add Case > Simulate Cases, and select the case to add.

    2. Select Manual Action > Exchange > Get Authorization. This action returns an authorization link that is used to interactively sign in as the user you want to use for the integration.

    3. To clear all of the cookies, open a new browser window in the incognito mode.

    4. To open the Azure sign in page, use the generated authorization URL.

    5. Sign in with the user you want to use for integration.

      After signing in, your browser should be redirected with a code in the address bar. It is normal for the browser to display an error as our app redirects to http://localhost.

    6. Copy the whole URL with the access code from the browser window.

  2. Go back to the Google Security Operations SOAR platform and run the Generate Token action.

    1. In the Authorization URL field, enter the whole URL with the access code copied in the previous step and run the action.

    2. Once the action is successfully completed, go to the Case Wall page, and click View Result to see the generated refresh token.

    3. In the action dialog, click Show more to see the full token value.

    4. Copy the whole value of the token.

  3. Go back to the integration configuration dialog and enter the refresh token value in the Refresh Token field to complete the integration configuration.

Actions

Send Vote Mail

Description

Send emails with easy answering options, to allow stakeholders to be combined in the automated processes without accessing the Google Security Operations SOAR UI.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Subject String N/A Yes The mail subject part.
Send To String N/A Yes

Arbitrary comma-separated list of email addresses for the email recipients.

Example: user1@example.com, user2@example.com
CC String N/A No

Arbitrary comma-separated list of email addresses to be put in the CC field of email.

Format is the same as for the "Send to" parameter.
BCC String N/A No

Arbitrary comma-separated list of email addresses to be put in the BCC field of email.

Format is the same as for the "Send to" parameter.
Attachments Paths String N/A No

A comma-separated list of attachments file paths stored on the server for addition to the email.

Example: C:\<Siemplify work dir>\file1.pdf, C:\<Siemplify work dir>\image2.jpg
Question or Decision Description String N/A Yes The question you would like to ask, or describe the decision you would like the recipient to be able to respond to.
Structure of voting options DDL

Yes/No

Possible Values:

  • Yes/No
  • Approve/Reject
 Yes Choose the structure of the vote to be sent to the recipients

Run On

This action doesn't run on entities.

Action Results

Script Result
Script Result Name Value Options Example
success True/False success:False
JSON Result
{

…

"message_id": "x@google.com>",

"email_date": "1583916838"

...

}
Case Wall
Case Success Message
Vote Mail Sent successfully for at least one mailbox Yes "Vote Mail was sent successfully"
Vote Mail was not sent successfully for at least one mailbox Yes "Could not send vote mail for the following mailboxes: "+unseuccessfull_mailboxes_list
Could not send mail to any of the recipients No "Could not send vote mail to any of the provided mailboxes. Please check the action parameters and try again"

Wait for Vote Mail Results

Description

Use this action to fetch the responses of a vote mail sent by the "Send Vote Mail" action, in order to wait for the responses and get them inside Google Security Operations SOAR.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Vote Mail message_id String N/A Yes

Message_id of the vote email, which current action would be waiting for.

If message is sent using the Send Vote Mail action, select SendVoteMail.JSONResult.message_id as a placeholder.
Mail Recipients String N/A Yes

A comma-separated list of recipient emails, response from which current action would be waiting for.

Select SendVoteMail.JSONResult.to_recipients as a placeholder.
Folder to Check for Reply String Inbox Yes

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.

The parameter also accepts a comma-separated list of folders to check the user response in multiple folders. The parameter is case-sensitive.
Folder to check for Sent Mail String Sent Items Yes

Parameter can be used to specify mailbox email folder (mailbox that was used to send the email with question) to search for the sent mail in this folder.

The parameter also accepts a comma-separated list of folders to check the user response in multiple folders.

The parameter is case-sensitive.
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 for All Recipients to Reply? Checkbox Checked No

Parameter can be used to define if there are multiple recipients.

The action waits for responses from all recipients until it times out, or for the first reply to proceed.

Run On

This action doesn't run on entities.

Action Results

Script Result
Script Result Name Value Options Example
success True/False success:False
JSON Result
{
    "Responses": [{
        "recipient": "x@example.com",
        "content": "Approve"
    }]
}
Case Wall
Case Success Message
action completed successfully (all mails received, no timeouts) V

For each mail address:
"Found the user... reply"
timeout

For each mail address,:

"Timeout getting reply from user..."
bad mail recipients - at least one V "Could not perform action on the following mailboxes: "+unseuccessfull_mailboxes_list
bad mail recipients -all of them "Could not perform action on any of the provided mailboxes. Please check the action parameters and try again"

Delete mail

Description

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

The minimal required set of Exchange roles allowing to delete an email from other mailboxes is the following:

  • ApplicationImpersonation
  • Mailbox Search

Aside from permissions, if users are offline it's possible that the action won't delete the message from their outlook client until they reconnect and synchronize their mailbox.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Folder Name String Inbox No

Mailbox folder to search email in.

The parameter also accepts 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.

The parameter also accepts a comma-separated list of message IDs to search for.

If message ID is provided the subject, sender and recipient filters are ignored.
Subject Filter String N/A No Filter condition, specify the 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 the action deletes all matched by criteria emails from the mailbox or deletes only first match.
Delete from all mailboxes Checkbox Unchecked No If enabled, delete emails in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 25 Yes

If "Delete from all mailboxes" is checked, the action works in batches.

This parameter controls how many mailboxes action should process in a single batch (single connection to mail server).
Time Frame (minutes) Integer N/A No Filter condition, specify the time frame in minutes during which the action looks for emails.

Use Cases

Use Case 1a. Delete processed Email from the mailbox.

Use case workflow

Run On

This action should be provided with mandatory parameter folder name to where to search for emails for deletion (either as a placeholder or manually provided by user).

Action Results

Script Result
Script Result Name Value Options Example
success True/False success:False
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (email is found by the search criteria, delete operation is successful): "{0) email(s) were deleted successfully".format(email_count)

If no emails for deletion are found: "Failed to find emails for deletion!"

Action should fail and stop playbook execution only if it encounters a technical problem (connection lost, wrong credentials):

If an error is reported: "Error deleting emails {0}".format(exception.stacktrace)

 General

Download Attachments

Description

Download email attachments from an email to a specific file path on the Google Security Operations SOAR server. If the downloaded attachments have the "/" or "" characters in the names, those are replaced with the "_" character.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Folder Name String Inbox No

Mailbox folder to search email in.

The parameter also accepts a comma-separated list of folders to check the user response in multiple folders.
Download Path String N/A Yes File path on the server where to download the email attachments.
Message IDs String N/A No

Filter condition to specify emails with which email IDs to find.

The parameter also accepts a comma-separated multiple message IDs.

If a message ID is provided, the subject filter is ignored.
Subject Filter String N/A No Filter condition to search emails by the specific subject.
Sender Filter String N/A No Filter condition to search emails by the specific sender.
Only Unread Checkbox Unchecked No If checked, download attachments only from unread emails.
Download Attachments from EML Checkbox Unchecked No If checked, download attachments also from attached EML files.
Download Attachments to unique path? Checkbox Unchecked No If checked, download attachments to a unique path under the file path provided in the "Download Path" parameter to avoid previously downloaded attachments overwrite.
Search in all mailboxes Checkbox Unchecked No If checked, search in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 25 No

If "Search in all mailboxes" is checked, the action works in batches.

This parameter controls how many mailboxes the action processes in a single batch (single connection to mail server).
Mailboxes CSV N/A No

Specify a comma-separated list of mailboxes that need to be searched.

This parameter has priority over "Search in all mailboxes".

Use Cases

Use Case 1. Download Attachments from Email. If the email looks malicious and file hashes for the email attachment are not yet scored in Virus Total, upload the email attachments for analysis in the Sandbox environment.

Use case workflow

Run On

This action should be provided with the mandatory parameters folder name and download path to download attachments (either as a placeholder or manually provided by the user).

Action Result

Script Result
Script Result Name Value Options Example
file_paths Script result returns String of comma-separated full paths to the saved attachments. N/A
JSON Result
[
   {
       "attachment_name": "xxx.xxx",
       "downloaded_path": "C:\\<xxx_xxx_xxx>\\xxx.xxx"
   },
   {
       "attachment_name": "xxx.xxx",
       "downloaded_path": "C:\\<xxx_xxx_xxx>\\xxx.xxx"
   }
]
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful: "Downloaded {0} attachments. \n\nFiles:\n{1}".format(len(attachments_local_paths), "\n".join(attachments_local_paths)".

Action should fail and stop playbook execution only if it encounters a technical problem (connection lost, wrong credentials):

If an error is reported: "Failed to download email attachments, the error is: {0}".format(exception.stacktrace)

 General

Save Mail Attachments To The Case

Description

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

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Folder Name String Inbox Yes

Mailbox folder to search email in.

The parameter also accepts a comma-separated list of folders to check the user response in multiple folders
Message ID String N/A Yes Message ID to find an email to download attachments from.
Attachment To Save String N/A No

If the parameter is not specified, the action saves all email attachments to the case wall.

If the parameter is specified, the action saves only matching attachment to the case wall.

Use Cases

Use Case 1. For data retention purposes due to the Company standards/procedures and Regulatory requirements, save the email attachments that were found to be malicious to the Case Wall.

Use case workflow

Run On

This action should be provided with a mandatory parameter folder name to save attachments (either as a placeholder or manually provided by the user).

Action Result

Script Result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON Result

This 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*

Action should not fail and not stop playbook execution:

If successful: "Successfully saved the following attachments from the email {0}: {1}".format(message_id, attachments list).

If the email does not have attachments: "No attachments found in email {0}".format(message_id)

Action should fail and stop playbook execution only if it encounters a technical problem (connection lost, wrong credentials):

If an error is reported: "Failed to save the email attachments to the case, the error is: {0}".format(exception.stacktrace)

 General

Extract EML Data

Description

Extract data from an emails EML attachments.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Folder Name String Inbox No Folder to fetch from. Default is Inbox.
Message ID String N/A Yes Example: 1701cf01ba314032b2f1df43262a7723@gmail.com
Regex Map JSON String N/A No Example: {ips: \b\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\b}

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
eml_data N/A N/A
JSON Result
[
    {
        "count": 3,
        "files": {
            "mxtoolbox_test_case.case": "090a131a0726dea8f5b0c2205ffc9527"
        },
        "from": "Exam <x@test.com>",
        "text": "hello eml test", "regex": {

        },
        "to": "Test Test <x@test.com>",
        "html": "<html><div></div></html>",
        "date": "Wed, 12 Sep 2018 12:36:17 +0300",
        "subject": "eml test"
    }
]

Get Mail EML File

Description

Fetch a message EML file.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Folder Name String Inbox No Folder to fetch from.
Message ID String N/A Yes Example: 1701cf01ba314032b2f1df43262a7723@gmail.com
Base64 Encode Checkbox Unchecked No N/A

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
eml_info N/A N/A

Move Mail to Folder

Description

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

Depending on the use case, the action returns a different amount of information on processed emails in the JSON result:

  • If "Limit the amount of information in the JSON result" checkbox is checked, the action JSON result contains only the following fields about an email: datetime_received, message_id, sender, subject, to_recipients.
  • If "Limit the amount of information in the JSON result" checkbox is unchecked, the action JSON result returns all available information on the processed email.
  • If "Disable the Action JSON Result" is checked, the action does not return JSON result at all.

Parameters

Parameter Display Name 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.
Subject Filter String N/A No Filter condition to specify the subject to search for emails.
Message IDs String N/A No

Filter condition to specify emails with which email ids to find.

The parameter also accepts a comma-separated multiple message IDs.

If a message ID is provided, the subject filter is ignored.
Only Unread Checkbox Unchecked No Filter condition to specify if search should look only for unread emails
Move In All Mailboxes Checkbox Unchecked No If checked, the action searches and moves emails in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 25 Yes

If "Move in all mailboxes" is checked, the action works in batches.

This parameter controls how many mailboxes the action processes in a single batch (single connection to mail server).
Time Frame (minutes) Integer N/A No Filter condition to specify the time frame in minutes in which the action looks for emails.
Limit the Amount of Information Returned in the JSON Result Checkbox Checked No If enabled, the amount of information returned by the action is limited only to the key email fields.
Disable the Action JSON Result Checkbox Unchecked No If enabled, the action does not return the JSON result.

Use Cases

Use case 1a. Move email processed in playbook to archive folder.

Use case workflow

Use case 1b. Move email that was determined to be suspicious from inbox to spam.

Use case workflow

Run On

This action should be provided with mandatory parameters to from and to where move email (s) (either as a placeholder or manually provided by user).

Action Results

Script Result
Script Result Name Value Options Example
success True/False success:False
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (email is found by the search criteria, move operation is successful): "{0} mails were successfully moved from {1} to {2}". format(emails_count, srs_folder, dst_folder)

If no emails are found: "No mails were found matching the search criteria!"

Action should fail and stop playbook execution only if it encounters a technical problem (connection lost, wrong credentials):

If an error is reported: "Error search emails: {0}".format(exception.stacktrace)

 General

Ping

Description

Test connectivity to the Microsoft Exchange instance with parameters provided at the integration configuration page in the Google Security Operations Marketplace tab.

Parameters

N/A

Use cases

Action is used to test connectivity at the integration configuration page in the Google Security Operations Marketplace tab, and can be executed as manual action,which is not a part of playbooks.

Run On

This action doesn't run on entities, nor has mandatory input parameters.

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*

Action should not fail and not stop playbook execution:

If successful: "Successfully connected to the Microsoft Exchange server with the provided connection parameters!".

Action should fail and stop playbook execution only if it encounters a technical problem (connection lost, wrong credentials):

If not successful: "Failed to connect to the Microsoft Exchange server! Error is {0}".format(exception.stacktrace).

 General

Search Mails

Description

Search for specific emails in a configured mailbox using multiple provided search criteria. This action returns information on emails found in mailbox in the JSON format.

The minimal required set of Exchange roles allowing to search in all mailboxes is the following:

  • ApplicationImpersonation
  • Mailbox Search

Parameters

Parameter Type Default Value Is Mandatory Description
Folder Name String Inbox No

Mailbox folder to search email in.

The parameter also accepts a comma-separated list of folders to check the user response in multiple folders.
Subject Filter String N/A No Filter condition to specify the subject to search for emails.
Sender Filter String N/A No Filter condition to specify who should be the sender of needed emails.
Recipient Filter String N/A No Filter condition to specify who should be the recipient of needed emails.
Time Frame (Minutes) String N/A No Filter condition to specify the time frame in minutes in which the actions look for emails.
Only Unread Checkbox Unchecked No Filter condition to specify if search should look only for unread emails.
Max Emails To Return Integer N/A No Return maximum X emails as an action result.
Search in all mailboxes Checkbox Unchecked No If checked, the action searches in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 25 Yes

If "Search in all mailboxes" is checked, the action works in batches.

This parameter controls how many mailboxes the action processes in a single batch (single connection to mail server).
Start Time String N/A No

Specify the start time for the email search.

Format: ISO 8601

This parameter has a priority over the "Time Frame (minutes)" parameter.
End Time String N/A No

Specify the end time for the email search.

Format: ISO 8601

If nothing is provided and "Start Time" is valid then this parameter uses current time.
Mailboxes CSV N/A No

Specify a comma-separated list of mailboxes that need to be searched.

This parameter has priority over the "Search in all mailboxes" parameters.
Message IDs CSV N/A No

Specify a comma-separated list of message IDs that need to be searched.

Note: This filter has priority over the other ones.
Body Regex Filter String N/A No Specify a regex pattern that needs to be searched in the body part of the email.

Use Cases

Use Case 1. Search for suspicious emails to see if the email in question or similar emails were received for inspection on monitored mailbox previously from other users.

Use case workflow

Run On

This action should be provided with a mandatory parameter folder name to where to search emails (either as a placeholder or manually provided by user).

Action Results

Script Result
Script Result Name Value Options Example
mails_json N/A N/A
JSON Result
[
    {
        "body": "Mail Body",
        "subject": "Mail Subject",
        "author": "xxx@example.com"
    }, {
        "body": " ",
        "subject": "Mail Subject",
        "author": "xxx@example.com"
    }
]
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful: "Search found {0} emails based on the provided search criteria".format(count([email_ids]))

If nothing is found: "Search didn't found any matching emails"

If some mailboxes aren't found and the action continues to search in the found mailboxes: "The following mailboxes were not found in the Mail Server: {0}".format(not found mailboxes list)"

Action should fail and stop playbook execution only if it encounters a technical problem (connection lost, wrong credentials):

If an error is reported: "Search didn't completed successfully due to error: {0}".format(exception.stacktrace)

If at least one mailbox is not found because an invalid mailbox was provided (mails_json=false): Error executing action "Exchange - Search Mails". Reason: the following mailboxes were not found: {mailboxes}. Please check the spelling.

 General
Table

Table title: Matching Mails

Table Columns:

  • Message_id
  • Received Date
  • Sender
  • Recipients
  • Subject
  • Email body
  • Attachment names (comma-separated list of attachment names)

Optional: If "Search in all mailboxes" is checked, add a column titled "Found in mailbox" to indicate in which mailbox the email was found.

 General

JSON Viewer

(Only if table is not optional)

JSON is used to present search results to user (output uses a subset of the data from the Mail Object technical result JSON):

{

"emails": {

"email_1": {

"message id": "<CAJP=A_uGkttoWc1eahvP43rWVEsdk77nMu1FomhgRjRSmySLLg@mail.gmail.com>",

"received": "Mon, 26 Aug 2019 03:20:13 -0700 (PDT)",

"sender": "user@test.domain",

"recipients": "user1@example.com,user2@example.com",

"subject": "Cool offer",

"plaintext_body": "Hi, ...",

"attachmment_1": "pdfdocument.pdf",

"attachment_1_file_hash_md5": "3bd4a36cc0ed0bfc12ae5e2ece929e82",

"found_in":"user1@example.com"

},

"email_2": {

"message id": "<WEAA=D_uGkttoWc1eahvP43rWVEsdk77nMu1FomhgRjRSmySLLg@mail.gmail.com>",

"received": "Wen, 21 Aug 2019 03:20:13 -0700 (PDT)",

"sender": "user@test.domain",

"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",

"found_in":"user1@example.com"

}

}

}

 General

Send Email and Wait - Deprecated

Description

Send email and wait action. Thr Send to field is comma-separated. Sender's display name can be configured in the client under the account settings.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Subject String N/A Yes The subject of the email.
Send to String user@example.com Yes

Recipient email address.

Multiple addresses can be separated by commas.
CC String user@example.com 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.
Mail content String N/A Yes Email body.
Fetch Response Attachments Checkbox Unchecked No Allows attachment of files from response mail.
Folder to Check for Reply String Inbox No

Parameter can be used to specify the mailbox email folder (mailbox that was used to send the email with question) to search for the user reply in this folder.

The parameter also accepts a comma-separated list of folders to check the user response in multiple folders.

Parameter is case-sensitive.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
Mail_body N/A N/A
JSON Result
[
    {
        "EntityResult": {
            "attachments": [],
            "sensitivity": "Normal",
            "effective_rights": " test",
            "has_attachments": "false",
            "last_modified_name": "mail",
            "is_submitted": "false"
        },
        "Entity": "xxx@mail.com"
    }
]

Send Mail

Description

Send an email from a specific mailbox to an arbitrary list of recipients. This action can be used to inform users about:

  • The specific alerts created in Google Security Operations SOAR
  • The results of specific alerts processing

Parameters

Parameter Type Default Value Is Mandatory Description
Subject String N/A Yes The mail subject part.
Send to String user@example.com Yes

Arbitrary comma-separated list of email addresses for the email recipients.

Example: user1@example.com, user2@example.com
CC String user@example.com No

Arbitrary comma-separated list of email addresses to be put in the CC field of email.

Format is the same as for the "Send to" parameter.
BCC String N/A No

Arbitrary comma-separated list of email addresses to be put in the BCC field of email.

Format is the same as for the "Send to" parameter.
Attachments Paths String N/A No

A comma-separated list of attachments file paths stored on the server for addition to the email.

Example: C:\<Siemplify work dir>\file1.pdf, C:\<Siemplify work dir>\image2.jpg
Mail content String N/A Yes The email body part.
Reply-To Recipients CSV N/A No

Specify a comma-separated list of recipients that is used in the "Reply-To" header.

Note: The Reply-To header is added when the originator of the message wants any replies to the message to go to that particular email address rather than the one in the "From:" address.
Base64 Encoded Certificate Password N/A No

Specify a comma-separated list of recipients that is used in the "Reply-To" header.

Note: The Reply-To header is added when the originator of the message wants any replies to the message to go to that particular email address rather than the one in the "From:" address.
Base64 Encoded Certificate Password N/A No Specify a base64 encoded certificate that is used to encrypt the email.

Use Cases

Send notification email to list of recipients.

Use case workflow

Run On

This action should be provided with information on email to send (either as a placeholder or manually provided by user).

Action Results

Script Result
Script Result Name Value Options Example
Success_Inidicator N/A N/A
JSON Result

Returns Mail Object technical result JSON and additionally, message id, sent date for the sent email (to pass it in the Wait for Mail action from the user if needed):

{
…
"message_id": "<x@google.com>",
"email_date": "1583916838"
...
}
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If an email is sent successfully: "Mail sent successfully."

Action should fail and stop playbook execution only if it encounters a technical problem (connection lost, wrong credentials):

If an error is reported: "Failed to send email! The Error is {0}".format(exception.stacktrace)

 General

Wait for mail from user

Description

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

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Mail message_id String N/A Yes

Message_id of the email, which current action would be waiting for.

If a message is sent using the Send Email action, select the SendEmail.JSONResult.message_id field as a placeholder.
Mail Date String N/A Yes

Send timestamp of the email, which the current action would be waiting for.

If a message is sent using the Send Email action, select the SendEmail.JSONResult.email_date field as a placeholder.
Mail Recipients String N/A Yes

A comma-separated list of recipient emails, response from which current action would be waiting for.

If a message is sent using the Send Email action, select the Select SendEmail.JSONResult.recipients field as a placeholder.
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 for All Recipients to Reply? Checkbox Checked No

Parameter can be used to define if there are multiple recipients.

The action waits for responses from all of recipients until runs into a timeout, or for first reply to proceed.
Wait Stage Exclude pattern String N/A No

Regular expression to exclude specific replies from the wait stage.

Works with the 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.

The parameter also accepts a comma-separated list of folders to check the user response in multiple folders.

The parameter is case-sensitive.
Fetch Response Attachments Checkbox Unchecked No If selected and recipient replies with attachment, the action fetches recipient response and adds it as attachment for the action result

Use Cases

Use case 1. Wait for the user reply to the previously sent email by the Send Email action. Once response is found, analyze the response in playbook, and run additional steps if applicable.

Use case workflow

Run On

This action should be provided with message_id to track reply to (either as a placeholder or manually provided by user).

Action Results

Script Result
Script Result Name Value Options Example
is_succeed True/False is_succeed:False
JSON Result

For JSON result action should return combination of Mail Object JSON for the email that action tracks response for (for which message_id was provided) AND JSON output for the process of tracking responses from users(how to merge output data should be decided at the implementation stage):

Wait for at least one user response to proceed, once got response from first user- update JSON and proceed with action results:

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

Wait for all user responses to proceed, update JSON as getting replies from users or timeout. In this case, if action is waiting for responses from all of the recipients, and if timeout reached waiting for user response, action should return handled_timeout error:

{
"Responses":
{[
    "user1@example.com": "Approved",
    "user2@example.com": "Approved",
    "user3@example.com": "Timeout"
]}
}
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If the reply is found: "Found the user {0 } reply: {1}".format (email_recipient, user_reply)

If run into a timeout: "Timeout getting reply from user: {0}".format(email_recipient)

Action should fail and stop playbook execution only if it encounters a technical problem (connection lost, wrong credentials):

If a "General" error is reported: "Failed to execute action, the error is: {0}".format(error_stacktrace)

If an error is reported: "Failed to get user {0} reply, the error is: {1}".format(email_recipient, error_stacktrace) thethe

General
Attachments

Title, Filename(+extensions), file Content:

title: recipient <recipient_email> reply attachment,

filename: <attachment file name> + <attachment extension>,

fileContent: <content of attached file>

 Entity (recipient who replied to the message id Google Security Operations SOAR server tracks response for)

Send Mail HTML

Description

Send an email with HTML template content. The Send to field is comma-separated.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Subject String N/A Yes The subject of the email.
Send to String user@example.com Yes

Recipient email address.

Multiple addresses can be separated by commas.
CC String user@example.com 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.
Attachments Paths String N/A No

Full path to attachments to be uploaded. Comma-separated.

Example: C:\Desktop\x.txt,C:\Desktop\sample.txt
Mail content String N/A Yes Mail body.

Run On

This action runs on all entities.

Action Results

Script Result
Script Result Name Value Options Example
is_succeed True/False is_succeed:False

Get Account Out Of Facility Settings

Description

Get account out of facility (OOF) settings for the provided Google Security Operations SOAR User entity.

Run On

This action runs on the User entity.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success:False
JSON Result
OofSettings(state='Disabled', external_audience='All', start=EWSDateTime(2020, 10, 1, 3, 0, tzinfo=<UTC>), end=EWSDateTime(2020, 10, 2, 3, 0, tzinfo=<UTC>))
Entity Enrichment
Enrichment Field Name Source (JSON Key) Logic - When to apply
Exchange.oof_settings OofSettings(state='Disabled'.... Should return Disabled or enabled based on the API response.
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If information for the provided entity is found (is_success=true): "Successfully returned OOF settings for {0}".format(entity.Identifier)

If no information is found (is_success=false): "Action wasn't able to find OOF settings for {0} ".format(entity.Identifier)

Action should fail and stop playbook execution:

If a fatal error, like wrong credentials, no connection to the server, other is reported: "Error executing action "Get Account Out Of Facility Settings". Reason: {0}''.format(error.Stacktrace)

 General
Table

Table name: "{0} Out of Facility Settings".format(entity.identifier)

Table columns:

  • Parameter
  • Value
 Entity

Generate Token

Description

For integration configuration with OAuth authentication, get a refresh token using the authorization URL received in the Get Authorization action.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Authorization URL String N/A Yes Use the authorization URL received in the Get Authorization URL action to request a refresh token.

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
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If successfully got the token: "Successfully fetched the refresh token:
{0} Copy this refresh token to the Integration Configuration.

Note: This Token is valid for 90 days only".format(refresh_token)

Action should fail and stop playbook execution:

If an error is reported: "Failed to get the refresh token! The Error is {0}".format(exception.stacktrace)

 General

Get Authorization

Description

For integration configuration with OAuth authentication, run the action and browse to the received URL to get a link with access code. That link needs to be provided to the Generate Token action next to get the refresh token.

Parameters

N/A

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
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If successfully generated authorization URL: "Authorization URL generated successfully. Please navigate to the link below as the user that you want to run integration with, to get a URL with access code. The URL with access code should be provided next in the Generate Token action."

Action should fail and stop playbook execution:

If an error is reported: "Failed to generate authorization URL! The Error is {0}".format(exception.stacktrace)

 General
Links

Display Name: Browse to this authorization link.

Link: authorization link generated by the action.

 General

Send Thread Reply

Description

Send a message as a reply to the email thread.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Message ID String N/A Yes Specify the ID of the message to which you want to send a reply.
Folder Name String 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, the folder name should match exactly the IMAP folder.

If the folder name contains spaces, it must be wrapped in double quotes.
Content String N/A Yes Specify the content of the reply.
Attachment Paths String N/A No Specify a comma-separated list of attachments file paths stored on the server for addition to the email.
Reply All Checkbox Checked No

If enabled, the action sends a reply to all recipients related to the original email.

Note: This parameter has priority over the "Reply To" parameter.
Reply To CSV N/A Yes

Specify a comma-separated list of emails to which you want to send this reply.

If nothing is provided and the "Reply All" parameter is disabled, the action only sends a reply to the sender of the email.

If the "Reply All" parameter is enabled, the action ignores 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
Case Wall
Result Type Value / Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful: "Successfully sent reply to the message with ID {message ID} in Exchange."

Action should fail and stop playbook execution:

If an error, such as Fatal error, invalid credentials, API root is reported: "Error executing action "Send Thread Reply". Reason: {error traceback}"

If the "Reply All" parameter is enabled and only integration email is in the scope: "Error executing action "". Reason: if you want to send a reply only to your own email address, you need to work with "Reply To" parameter."

 General

Exchange Integration – Block Sender and Domain Functionality

One of the most common use cases for email management and security is to contain existing threats, like phishing emails, that are already inside the organization's perimeter, and then block a suspicious sender or a domain from your organization, to protect it from future attacks and prevent future perimeter breaches.

Google Security Operations SOAR Exchange integration is providing you with this functionality in several ways:

  1. Block Sender by Message ID – Add the Sender to the Block List, using the "Mark as Junk" EWS service – Inside the Perimeter protection.
  2. Create Exchange – Google Security Operations SOAR Inbox rules – Add inbox rules on the client level, to prevent those mails from getting into your organization's mailboxes automatically – Outside the Perimeter – First Phase.
  3. Create Exchange-Google Security Operations SOAR Server Inbox rules – Coming Soon – preventing suspicious emails from even getting into the organization - Outside the Perimeter – Second Phase.

Organizations mailboxes diagram

In the first scenario, your organization perimeter was "breached" with an email you now know is a risky mail, and you would like to handle the existing threat.

Organization permimeter breached with phishing mail

In this case, you would like to remediate the threat, handle the compromised mailboxes, and then add a protection from this mail in the other mailboxes as well. First, you need to use the "Block Sender by Message ID" action. This action can get a few parameters, to get this specific mail, and also go through all the mailboxes, or through only the ones you know are compromised and handle the threat there. It will use the Exchange EWS Mark as Junk service, for more information, see Add and remove email addresses from the Blocked Senders List by using EWS in Exchange.

In short, the action can mark this item as Junk, and as a result:

  1. The item is moved to the Junk folder.
  2. The mail sender is added to the blocked sender list of this mailbox.

Pros and cons of this solution:

Pros Cons
Can be easily automated. The mailbox needs to have a mail from the sender to add a sender to the blocklist, which leaves the unaffected mailboxes unprotected from future attempts.
Can handle only specific mailboxes. Domains cannot be added through the API to the blocked Sender's list.
Blocked sender list is the dedicated solution from Microsoft's side. -

Organization permimeter breached with phishing mail

The second phase is to use the set of actions, called "Exchange- Google Security Operations SOAR Inbox rules". This set uses the "Manage Inbox Rules" service, details can be found here.

To help protect every mailbox you have, from every Sender – even ones that haven't yet tried to harm your organization – you can add Inbox rules to protect all mailboxes from those. Google Security Operations SOAR integration has provided the users with a predefined rules for the most common 3 operations: Move to junk, Delete, and permanently delete. Important note – the rules here are handled on the Client side – which means for each mailbox. For exchange sserver inbox rules – you will have to use the third option.

How does it work

In this phase, the rules will be added first to the Admin user, logged in to the Google Security Operations SOAR integration. This was done, in order to always maintain the same list of rules in all of the mailboxes, add senders, remove senders, etc.

So, for every CRUD operation – you will update the inbox rules for the admin account. Then, when you would like the changes to be applied to all of your organization's mailboxes – you can run the operations on all mailboxes. This operation will basically take the current state of the rules in the logged in account and will replicate them so that all mailboxes will have the exact same rules like the logged in user.

To Achieve the above, we have come up with a list of 6 rules for the main use cases, that will be the only rules we are going to update and work with, to avoid creation of huge amount of rules and maintain a stable list of the organization's protection layer. All of the possible rules you can create using the actions:

  • Siemplify - Senders List - Move To Junk
  • Siemplify - Senders List - Delete
  • Siemplify - Senders List - Permanently Delete
  • Siemplify - Domains List - Move To Junk
  • Siemplify - Domains List - Delete
  • Siemplify - Domains List - Permanently Delete

So, let's have an example with the action names you will be using here. Let's say you have a suspicious email sender you know is attacking similar organizations these days. Sender is phishing@phishing.com .You want to prevent this user from ever sending a mail into one of your organization's mailboxes.

For the example – you want to permanently delete it once it gets to your mailbox.

So, you will do the following:

  1. Run "Add Senders to Exchange-Siemplify Inbox Rule", with the sender phishing@phishing.com

  2. According to the action you would like to perform with the mail (if it will be sent to one of the mailboxes) choose the appropriate rule from the drop down list. Following our example– you will choose: "Siemplify - Senders List

    • Permanently Delete ".

  3. Check "Perform action in all mailboxes" so that action will make sure the rule is in all mailboxes

  4. If you would also want to block the domain phishing.com , you can just check the "Should add senders' domain to the corresponding Domains List rule as well?" checkbox, so that the domain will be added to the corresponding rule as well as the sender.

  5. Please also review the other parameters in the action, to adjust it according to best match your needs.

What will happen behind the scenes

  1. This action will update the Logged in user inbox rule: "Siemplify - Senders List - Permanently Delete" with the new added sender, to that now the rule will contain all blocked senders till now and the new one.

  2. Then will take the "Siemplify - Senders List - Permanently Delete" rule from the admin rules and will apply it in all of the organization's mailboxes.

    1. If a rule already exists in the client side – it will override it with the new content.

    2. If a rule doesn't exist – it will create it

  3. It will update a few rules at a time, according to the "mailboxes to process in one batch" parameter.

  4. Once action will be finished, it will display the names of the mailboxes that weren't updated successfully, due to permission errors, network, etc…

Let's also assume you want to list down the rules for employee1@org.com, which is deleting the rules and opening phishing emails whenever he can. Then you can use the "List Exchange-Siemplify Inbox Rules" on his mailbox at any time, to see the status of his Exchange-Siemplify Inbox rules.

Pros:

  • Can be easily automated.
  • Can work on both senders and domains.
  • Can work on all mailboxes, regardless of whether there's a received mail there.

Cons:

  • The rules can be deleted by the end user.
  • Going over all mailboxes might take long in large organizations.
  • Users private inbox rules that are disabled – will be removed using this operation

The third option is the most preferred one, for large organizations and for best performance and protection – but will require some more configuration and login credentials in order to apply, as it involves Exchange PowerShell login and options. It will be described thoroughly once ready.

Block Sender by Message ID

Description

The action gets a list of message IDs as a parameter and can mark it as junk. Marking an item as junk using this action adds the item sender's mail address to the "Blocked Senders List", and moves it to the "Junk" folder.

This action runs asynchronously. Adjust the script timeout value in the Google Security Operations SOAR IDE for the action as needed.

This action is supported only from Exchange Server version 2013 and newer. If a lower version is used, the action fails with the appropriate message.

A message from the email address must exist in the user's mailbox before you can add the email address to or remove it from the Blocked Senders List.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Move item to Junk folder? Checkbox Checked Yes Should the action move the specified messages to the junk folder
Message IDs String N/A No

Filter condition.

Specify emails with which message IDs to find.

This parameter also accepts a comma-separated list of message IDs to mark as junk.

If a message ID is provided, the subject, sender and recipient filters are ignored.
Mailboxes list to perform on String N/A No

Filter condition.

If you have a specific list of mailboxes you would like to conduct the operation on, for better timing, provide them here.

This parameter also accepts a comma-separated list of mail addresses, to mark the messages as junk in.

If a mailboxes list is provided, the "Perform Action in all Mailboxes" parameter is ignored.
Folder Name String Inbox No

Mailbox folder to search the email in.

This parameter also accepts a comma-separated list of folders to move the item from.
Subject Filter String N/A No

Filter condition.

Specify the subject to search for emails.
Sender Filter String N/A No

Filter condition.

Specify the sender of needed emails.
Recipient Filter String N/A No

Filter condition.

Specify the recipient of needed emails.
Mark All Matching Emails Checkbox Unchecked No

Filter condition.

Specify if the action should Mark all matched by criteria emails from the mailbox or Mark only first match.
Perform action in all mailboxes Checkbox Unchecked No If checked, the action moves to junk and block sender emails in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 25 No In case "Perform action in all mailboxes" is checked, the action works in batches. This parameter controls the number of mailboxes that the action should process in a single batch (single connection to mail server).
Time Frame (minutes) Integer N/A No

Filter condition.

Specify the time frame in minutes in which the action looks for emails.

Run On

The action doesn't run on entities, it has a mandatory input parameter.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success=False
JSON Result
N/A
Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (email is found by the search criteria, Mark operation is successful): "{0} mails were successfully marked as junk". format(emails_count)

If no emails are found: "No mails were found matching the search criteria!"

If the action is running on all mailboxes and status is still running: f"{len(successful_messages_jsons)} email(s) were marked as junk from {len(processed_mailboxes)} mailboxes (out of {len(processed_mailboxes) + len(not_processed_mailboxes)}). Continuing."

Action should fail and stop playbook execution:

If the version is lower than 2013: "Failed to execute action - Action is fully supported only from Exchange Server version 2013 and above, Please make sure you have the appropriate version configured in Google Security Operations SOAR."

If an error is reported: "Error performing "Mark as junk and Block Sender" action : {0}".format(exception.stacktrace)

 General

Unblock Sender by Message ID

Description

The action gets a list of message IDs as a parameter and can unmark it as junk. Unmarking an item as junk using this action removes the item sender's mail address from the "Blocked Senders List''. To move it back to the inbox, tick the appropriate checkbox in the action parameters.

This action runs asynchronously. Adjust the script timeout value in the Google Security Operations SOAR IDE for the action as needed.

This action is supported only from Exchange Server version 2013 and newer. If a lower version is used, the action fails with the appropriate message.

A message from the email address must exist in the user's mailbox before you can add the email address to or remove it from the Blocked Senders List.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Move items back to Inbox? Checkbox Checked Yes If checked, the action moves the specified messages back to the inbox folder.
Message IDs String N/A No

Filter condition.

Specify email IDs with which email ids to mark.

This parameter accepts a comma-separated list of message IDs to unmark as junk.

If a message ID is provided, the subject, sender and recipient filters are ignored.
Mailboxes list to perform on String N/A No

Filter condition.

If you have a specific list of mailboxes you would like to conduct the operation on, for better timing, provide them here.

This parameter also accepts a comma-separated list of email addresses to unmark the messages as junk in.

If a mailboxes list is provided, the "Perform Action in all Mailboxes" parameter is ignored.
Folder Name String Junk Email No

Mailbox folder to search email in.

This parameter also accepts a comma-separated list of folders to move the item from.
Subject Filter String N/A No

Filter condition.

Specify the subject to search for emails.
Sender Filter String N/A No

Filter condition.

Specify the sender of needed emails.
Recipient Filter String N/A No

Filter condition.

Specify the recipient of needed emails.
Unmark All Matching Emails Checkbox Unchecked No

Filter condition.

Specify if the action should Unmark all matched by criteria emails from the mailbox or Unmark only first match.
Perform action in all mailboxes Checkbox Unchecked No If checked, the action runs in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 25 No

In case "Perform action in all mailboxes" is checked, the action works in batches.

This parameter controls the number of mailboxes that the action should process in a single batch (single connection to mail server).
Time Frame (minutes) Integer N/A No

Filter condition.

Specify the time frame in minutes in which the action looks for emails.

Run On

The action doesn't run on entities, it has a mandatory input parameter.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success=False
JSON Result
N/A
Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (emails are found by the search criteria, Mark operation is successful): "{0} mails were successfully unmarked as junk". format(emails_count)

If no emails are found: "No mails were found matching the search criteria!"

If the action is running on all mailboxes and status is still running: f"{len(successful_messages_jsons)} email(s) were unmarked as junk from {len(processed_mailboxes)} mailboxes (out of {len(processed_mailboxes) + len(not_processed_mailboxes)}). Continuing."

Action should fail and stop playbook execution:

If the version is lower than 2013: "Failed to execute action - Action is fully supported only from Exchange Server version 2013 and above, Please make sure you have the appropriate version configured in Google Security Operations SOAR."

If an error is reported: "Error performing "Mark as junk and Block Sender" action : {0}".format(exception.stacktrace)

 General

Add Senders to Exchange-Siemplify Inbox Rule

Description

The action gets a list of Email Addresses as a parameter or works on the User entities with Email regexes (if parameters are not provided), and can create a new rule, filtering the senders from your mailboxes. Actions can be modified in the parameters using the rule parameter.

This action runs asynchronously. Adjust the script timeout value in the Google Security Operations SOAR IDE for the action as needed.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Senders String N/A No

Specify the email addresses you would like to add to the rule, in a comma separated list.

If no parameter is provided, the action works with the User entities.
Rule to add senders to DDL

Siemplify - Senders List - Move To Junk

Possible Values:

  • Siemplify - Senders List - Move To Junk
  • Siemplify - Senders List - Delete
  • Siemplify - Senders List - Permanently Delete
 Yes

Specify the rule to add the sender to.

If the rule doesn't exist, the action creates it where it's missing.
Should add senders' domain to the corresponding Domains List rule as well? Checkbox Unchecked No Specify whether the action should automatically take the domains of the provided email addresses and add them as well to the corresponding domain rules (same rule action for domains).
Perform action in all mailboxes Checkbox Unchecked No If checked, the action is performed in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 50 No

In case "Perform action in all mailboxes" is checked, the action works in batches.

This parameter controls the number of mailboxes that the action should process in a single batch (single connection to mail server).

Run On

This action runs on the User entity, if the email regex is valid for it, and if parameters are not provided.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success=False
JSON Result
N/A
Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (Rules are updated accordingly, inputs are right): "Added the following inputs to the corresponding rules:
Email Addresses: Successful_email_addresses
Domains: successful_domains

Rules updated:
Rules_updated_names_list

If there's an option to count the amount of successful mailboxes updated out of the total available: "Successfully updated (successful_mailboxes_count) out of (total_available_mailboxes)."

If failed_mailboxes_count is grater than 0: "Failed to perform operation on the following mailboxes: {failed_mailboxes_list)."

If the action is running on all mailboxes and status is still running: f"{len(successful_updated_mailboxes)} mailboxes were updated out of {len(total_processed_mailboxes)} mailboxes. Continuing."

Action should fail and stop playbook execution:

If no email addresses are provided in the "Senders" parameter and no appropriate entities are found: "No email addresses provided in "Senders" parameter and there are no email addresses in user entities, Please check action inputs and try again"

If an error is reported: "Error performing "Add Senders to Siemplify Inbox Rule" action : {0}".format(exception.stacktrace)

 General

Remove Senders from Exchange-Siemplify Inbox Rules

Description

This action gets a list of Senders as a parameter or work on the User entities (if parameters are not provided), and can remove the provided Senders from the existing rules.

This action runs asynchronously. Adjust the script timeout value in the Google Security Operations SOAR IDE for the action as needed.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Senders String N/A No

Specify the Senders you would like to remove from the rule, in a comma separated list.

If no parameter is provided, the action works with entities.
Rule to remove Senders from DDL

Siemplify - Senders List - Move To Junk

Possible Values:

  • Siemplify - Senders List - Move To Junk
  • Siemplify - Senders List - Delete
  • Siemplify - Senders List - Permanently Delete
 Yes

Specify the rule to remove the Senders from.

If the rule doesn't exist, the action does nothing.
Remove Senders from all available Rules Checkbox Unchecked No Specify whether the action should look for the provided Senders in all of Google Security Operations SOAR inbox rules.
Should remove senders' domains from the corresponding Domains List rule as well? Checkbox Unchecked No Specify whether the action should automatically take the domains of the provided email addresses and remove them as well from the corresponding domain rules (same rule action for domains).
Perform action in all mailboxes Checkbox Unchecked No If checked, the action is performed in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 50 No

In case "Perform action in all mailboxes" is checked, the action works in batches.

This parameter controls the number of mailboxes that the action should process in a single batch (single connection to mail server).

Run On

This action runs on the User entity, if parameters are not provided.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success=False
JSON Result
N/A
Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (Rules are updated accordingly, inputs are right): "Removed the following inputs from the corresponding rules:"
Senders : successful_senders

Rules updated: Rules_updated_names_list"

If there's an option to count the number of successfully updated mailboxes out of the total available: "Successfully updated (successful_mailboxes_count) out of (total_available_mailboxes)"

If failed_mailboxes_count is grater than 0: "Failed to perform operation on the following mailboxes: {failed_mailboxes_list)."

If the action is running on all mailboxes and status is still running: f"{len(successful_updated_mailboxes)} mailboxes were updated out of {len(total_processed_mailboxes)} mailboxes. Continuing."

Action should fail and stop playbook execution:

If no email addresses are provided in the "Senders" parameter and no appropriate entities are found: "No email addresses provided in "Senders" parameter and there are no email addresses in user entities, Please check action inputs and try again"

If an error is reported: "Error performing "Remove Senders from Siemplify Inbox Rule" action : {0}".format(exception.stacktrace)

 General

Add Domains to Exchange-Siemplify Inbox Rules

Description

This action gets a list of Domains as a parameter or works on the Domain entities (only in Google Security Operations SOAR version 5.6 and above, and if parameters are not provided), and can create or update a rule, filtering the domains from your mailboxes. This action can be modified in the parameters using rule parameter.

This action runs asynchronously. Adjust the script timeout value in the Google Security Operations SOAR IDE for the action as needed.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Domains String N/A No Specify the Domains you would like to add to the rule, in a comma-separated list.
Rule to add Domains to DDL

Siemplify - Domains List - Move To Junk

Possible Values:

  • Siemplify - Domains List - Move To Junk
  • Siemplify - Domains List - Delete
  • Siemplify - Domains List - Permanently Delete
 Yes

Specify the rule to add the Domains to.

If the rule doesn't exist, the action creates it where it's missing.
Perform action in all mailboxes Checkbox Unchecked No If checked, the action is performed in all mailboxes accessible with current impersonalization settings
How many mailboxes to process in a single batch Integer 50 No

In case "Perform action in all mailboxes" is checked, the action works in batches.

This parameter controls the number of mailboxes that the action should process in a single batch (single connection to mail server).

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success=False
JSON Result
N/A
Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (Rules are updated accordingly, inputs are right): "Added the following Domains to the corresponding rules:
Domains: successful_domains

Rules updated: Rules_updated_names_list"

If there's an option to count the number of successfully updated mailboxes out of the total available: "Successfully updated (successful_mailboxes_count) out of (total_available_mailboxes)

If failed_mailboxes_count is grater than 0: "Failed to perform operation on the following mailboxes: {failed_mailboxes_list)."

If the action is running on all mailboxes and status is still running: f"{len(successful_updated_mailboxes)} mailboxes were updated out of {len(total_processed_mailboxes)} mailboxes. Continuing."

Action should fail and stop playbook execution:

If no domains are provided in the action parameter: "No domains provided in "Domains" parameter, please check action parameters and try again"

If an error is reported: "Error performing "Add Domains to Exchange-Siemplify Inbox Rules" action : {0}".format(exception.stacktrace)"

 General

Remove Domains from Exchange-Siemplify Inbox Rules

Description

This action get a list of Domains as a parameter or works on the Domain entities (only in Google Security Operations SOAR version 5.6 and above, and if parameters are not provided), and can remove the provided domains from the existing rules.

This action runs asynchronously. Adjust the script timeout value in the Google Security Operations SOAR IDE for the action as needed.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Domains String N/A No

Specify the Domains you would like to remove from the rule, in a comma-separated list.

If no parameter is provided, the action works with entities.
Rule to remove Domains from DDL

Siemplify - Domains List - Move To Junk

Possible Values:

  • Siemplify - Domains List - Move To Junk
  • Siemplify - Domains List - Delete
  • Siemplify - Domains List - Permanently Delete
 Yes

Specify the rule to remove the Domains from.

If the rule doesn't exist, the action does nothing.
Remove Domains from all available Rules Checkbox Unchecked No Specify whether the action should look for the provided domains in all of Google Security Operations SOAR inbox rules.
Mailboxes list to perform on String N/A No

Filter condition.

If you have a specific list of mailboxes you would like to conduct the operation on, for better timing, provide them here.

The parameter accepts a comma-separated list of mail addresses to unmark the messages as junk.

If a mailboxes list is provided, the "Perform Action in all Mailboxes" parameter is ignored.
Perform action in all mailboxes Checkbox Unchecked No If checked, the action is performed in all mailboxes accessible with current impersonalization settings.
How many mailboxes to process in a single batch Integer 50 No

In case "Perform action in all mailboxes" is checked, the action works in batches.

This parameter controls the number of mailboxes that the action should process in single batch (single connection to mail server).

Run On

This action runs on the Domain entity, if parameters are not provided.

Action Results

Script Result
Script Result Name Value Options Example
is_success True/False is_success=False
JSON Result
N/A
Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (Rules are updated accordingly, inputs are right): "Removed the following inputs from the corresponding rules:"
Domains: successful_domains

Rules updated: Rules_updated_names_list"

If there's an option to count the number of successfully updated mailboxes out of the total available: "Successfully updated (successful_mailboxes_count) out of (total_available_mailboxes)"

If failed_mailboxes_count is grater than 0: "Failed to perform operation on the following mailboxes: {failed_mailboxes_list)."

If the action is running on all mailboxes and status is still running: f"{len(successful_updated_mailboxes)} mailboxes were updated out of {len(total_processed_mailboxes)} mailboxes. Continuing."

Action should fail and stop playbook execution:

If no domains are provided in the action parameter: "No domains provided in "Domains" parameter, please check action parameters and try again"

If an error is reported: "Error performing "Remove Domains from Siemplify Inbox Rule" action : {0}".format(exception.stacktrace)

 General

Delete Exchange-Siemplify Inbox Rules

Description

This action get a rule name as a parameter and deletes it from all the specified mailboxes.

This action runs asynchronously. Adjust the script timeout value in the Google Security Operations SOAR IDE for the action as needed.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Rule Name To Delete DDL

Choose

Possible Values:

  • Siemplify - Senders List - Move To Junk
  • Siemplify - Senders List - Delete
  • Siemplify - Senders List - Permanently Delete
  • Siemplify - Domains List - Move To Junk
  • Siemplify - Domains List - Delete
  • Siemplify - Domains List - Permanently Delete
  • All available Exchange-Siemplify Senders Rules
  • All available Exchange-Siemplify Domains Rules
  • All available Exchange-Siemplify Rules
 Yes Specify the Rule name you would like to completely delete from the relevant mailboxes
Perform action in all mailboxes Checkbox Unchecked No If checked, the action is performed in all mailboxes accessible with current impersonalization settings
How many mailboxes to process in a single batch Integer 50 No

In case "Perform action in all mailboxes" is checked, the action works in batches.

This parameter controls the number of mailboxes that the action should process in a single batch (single connection to mail server).

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
N/A
Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful (Rules are updated accordingly): "Deleted the following rules from the specified:"
Mailboxes:
Rules updated: Rules_updated_names_list"

If there's an option to count the number of successfully updated mailboxes out of the total available: "Successfully updated (successful_mailboxes_count) out of (total_available_mailboxes)"

If failed_mailboxes_count is grater than 0: "Failed to perform operation on the following mailboxes: {failed_mailboxes_list)."

If the action is running on all mailboxes and status is still running: f"{len(successful_updated_mailboxes)} mailboxes were updated out of {len(total_processed_mailboxes)} mailboxes. Continuing."

Action should fail and stop playbook execution:

If an error is reported: "Error performing "Delete Siemplify Inbox Rules" action : {0}".format(exception.stacktrace)

 General

List Exchange-Siemplify Inbox Rules

Description

This action gets a rule name from the Exchange-Siemplify Inbox rules as a parameter and lists it. If there are no mailboxes to list, the rules for the logged in user are listed.

This action runs asynchronously. Adjust the script timeout value in the Google Security Operations SOAR IDE for the action as needed.

Parameters

Parameter Display Name Type Default Value Is Mandatory Description
Rule Name To List DDL

Choose

Possible Values:

  • Siemplify - Senders List - Move To Junk
  • Siemplify - Senders List - Delete
  • Siemplify - Senders List - Permanently Delete
  • Siemplify - Domains List - Move To Junk
  • Siemplify - Domains List - Delete
  • Siemplify - Domains List - Permanently Delete
  • All available Exchange-Siemplify Senders Rules
  • All available Exchange-Siemplify Domains Rules
  • All available Exchange-Siemplify Rules
 Yes Specify the Rule name you would like to list from the relevant mailboxes
Mailboxes list to perform on String N/A No

Filter condition.

If you have a specific list of mailboxes you would like to conduct the operation on, for better timing, provide them here.

This parameter accepts a comma-separated list of mail addresses to list the rules from.

If a mailboxes list is provided, the "Perform Action in all Mailboxes" parameter is ignored.
Perform action in all mailboxes Checkbox Unchecked No If checked, the action is performed in all mailboxes accessible with current impersonalization settings
How many mailboxes to process in a single batch Integer 50 No

In case "Perform action in all mailboxes" is checked, the action works in batches.

This parameter controls the number of mailboxes that the action should process in a single batch (single connection to mail server).

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
{
    "id": "x",
    "name": "Siemplify - Domains List - Delete",
    "priority": 1,
    "is_enabled": True,
    "conditions": {
        "domains": ["xxx.COM", "xxx.CO"],
        "addresses": []
    },
    "actions": "move_to_folder"
    }
}
Case Wall
Result type Value/Description Type
Output message*

Action should not fail and not stop playbook execution:

If successful: "Listed the following rules :" specified_rules_names "for the specified mailboxes"

If there's an option to count the number of successfully updated mailboxes listed out of the total available: "Successfully listed (successful_mailboxes_count) out of (total_available_mailboxes)

If failed_mailboxes_count is grater than 0: "Failed to perform operation on the following mailboxes: {failed_mailboxes_list)."

Action should fail and stop playbook execution:

If an error is reported: "Error performing "List Exchange-Siemplify Inbox Rules" action : {0}".format(exception.stacktrace)

 General

Connectors

Configure Exchange connectors in Google Security Operations SOAR

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

To configure the selected connector use the connector-specific parameters listed in the following tables:

Exchange EML Connector

Description

Exchange EML connector retrieves emails from the Exchange server, and parses them. If there are attached EML files, it attaches them to the case as events. If there are multiple EML attachments in the email, the connector creates multiple cases and ingests every attachment as one event for each case.

Connector parameters

Use the following parameters to configure the connector:

Parameter Type Default Value Description
Product Field Name String device_product Framework parameter, must be set for every connector. Describes the name of the field where the product name is stored.
EventClassId String event_name The field name used to determine the event name (sub-type).
PythonProcessTimeout String 30 The timeout limit (in seconds) for the python process running current script.
Server IP 4 x.x.x.x N/A
Domain String N/A N/A
Email String N/A Email address for the mailbox to be monitored.
Username String N/A Username for the mailbox to pull emails from, for example, user@siemplify.com
Password Password N/A Password for the email mailbox to pull emails from.
Mail Address 8 Inbox N/A
Use Domain for Authentication String N/A Use domain as part of the authentication credentials (i.e: DOMAIN\USER, user@domain.).
Folder Name String N/A Inbox.
Environment Field Name String N/A N/A
Environment Regex Pattern String N/A N/A
Unread Emails Only 0 N/A N/A
Mark Emails as Read 0 N/A N/A
Max Days Backwards Number N/A N/A
Encode Data as UTF-8 Checkbox Checked Indicates whether to encode the email data with UTF-8 or not. Setting to True is recommended.
Exclusion Subject Regex 2 N/A Exclude those emails, whose subject matches this regex. For example '([N|n]ewsletter)|([O|o]ut of office)' finds all emails containing 'Newsletter' or 'Out of office' keywords.
Extract urls from HTML email part? Checkbox Unchecked Specify whether connector should additionally try to extract urls from html part of email. This will allow connector to extract complex urls, but urls from plain text part of email will not be extracted with this method. Extracted urls will be available in urls_from_html_part event field.
Exclusion Body Regex 2 N/A Exclude those emails, whose body matches this regex. For example '([N|n]ewsletter)|([O|o]ut of office)' finds all emails containing 'Newsletter' or 'Out of office' keywords.
Proxy Server Address 0 N/A The address of the proxy server to use.
Proxy Username 0 N/A The proxy username to authenticate with.
Proxy Password 0 N/A The proxy password to authenticate with.

Connector rules

Blocklist and dynamic list

The connector doesn't support blocklist and dynamic list rules.

Proxy support

The connector supports proxy.

Exchange Mail Connector

Description

The email connector enables emails to be retrieved from the configured Exchange server, which scans each server and subsequently creates new cases. At least one initial email occurrence is included in each scenario. The main difference is that Exchange EML connector removes emails itself and produces events which parsen the connected EML or MSG data. Exchange Mail connector generates events which parse the Exchange server's original emails. This document explains how Google Security Operations SOAR interacts and integrates with the Exchange Mail interface and the assisted workflows and activities within the application.

This document refers to communicating with a Microsoft Exchange 2007-2019 Server or Microsoft 365 using Exchange Web Services (EWS).

Exchange Case Forwarding to Google Security Operations SOAR

Google Security Operations SOAR will communicate with an Exchange 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 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 Yes Framework parameter, must be set for every connector. Describes the name of the field where the event name is stored
Environment Field Name String N/A No

Describes the name of the field where the environment name is stored.

If environment field isn't found, environment is ""
Environment Regex Pattern String N/A No

A regex pattern to run on the value found in the "Environment Field Name" field.

Default is .* to catch all and return value unchanged.

Used to allow the user to manipulate the environment field via regex logic

If regex pattern is null or empty, or the environment value is null, the final environment result is ""
Headers to add to events String N/A No Specify what headers from emails should be added to the events. Parameter accepts multiple values as a comma separated string. Provided values can be exact match or set as a regex.
Email exclude pattern String N/A No Regular expression to exclude specific emails from being ingested by the connector. Works with both subject and body part of email. Example is, to exclude mass mailing emails like news from being ingested.
Script Timeout (Seconds) Int 60 Yes Timeout limit for the python process running the current script.
Mail Server Address String N/A Yes Mail server IP address to connect to. If connecting to Microsoft 365, server address should be set to outlook.office365.com
Mail Address String N/A Yes Mail address to use in integration, to use for sending out emails and work with received emails for this email (mailbox)
Use Domain For Authentication Checkbox Checkbox unchecked No Use domain authentication to authenticate on mail server
Domain String N/A Yes Domain to authenticate with on mail server
Username String N/A Yes Username to authenticate with on mail server
Password Password N/A Yes A password to authenticate with on mail server
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
Unread Emails Only Checkbox Checkbox unchecked No If checked, cases will be pulled only from unread emails
Mark Emails as Read Checkbox Checkbox unchecked No If checked, after the emails have been pulled they will be marked as read.
Attach Original EML Checkbox Checkbox unchecked No If checked, the original email will be attached to the case info as an eml file
Full path to a file where email identifiers for which replies should be attached to Cases instead of been ingested are stored String

C:\Siemplify_Server\Scripting\

SiemplifyJob\

MonitoredExchangeCorrespondence\

Alerts.json

 No

Specify a file path to json file that stores identifiers of mails to track and attach replies as comments to Google Security Operations SOAR case.

Such emails can be sent with Send Mail (Advanced Action)

File path should have special symbols escaped. For example, \ should be used for "\" symbols in the file path.

Offset Time In Days Int 5 Yes Fetch emails from X days backwards
Max Emails Per Cycle Int 10 Yes Fetch x emails per connector cycle
Extract urls from HTML email part? Checkbox false No Specify whether connector should additionally try to extract urls from html part of email. This will allow connector to extract complex urls, but urls from plain text part of email will not be extracted with this method. Extracted urls will be available in urls_from_html_part event field.
Proxy Server Address String N/A No Proxy server to use for connection to the mail server
Proxy Server Username String N/A No Proxy server username
Proxy Server Password String N/A No Proxy server password

In the dynamic list area, add the following rule in order to extract specific values from the email using a regular expression in the following format:

  • Desired display name: matching regular expression
  • Example: For extracting URLs from the email insert: urls: http[s]?://(?:[a-zA-Z]|[0-9]|[$-_@.&+]|[!*(),]|(?:%0-9a-fA-F))+

Connector rules

Blocklist and dynamic list
*   The connector doesn't support the blocklist rule.
*   WhiteLogic - Exchange integration should use the dynamic list section
    to define regular expressions to parse email content to add to the email event
    specific fields based on the regular expression matches.
Proxy support

The connector supports Proxy.

Note that in Exchange Mail Connector v2 and Exchange Mail Connector v2 with OAuth Authentication there are parameters that can influence email processing:

  • Original Received Mail File and Attached Mail File Prefixes - those parameter can be used to define prefixes that will be added to either or both the Original Received Mail File and Attached Mail File, so when processing such events User can differentiate between event fields of original received file or attached mail file.
  • Create a Separate Google Security Operations SOAR Alert per Attached Mail File?
    • If enabled, connector will create multiple alerts, 1 alert per attached mail file. This behavior can be useful when processing email with multiple mail files attached and Google Security Operations SOAR event mapping set to create entities from attached mail file.

Note that to map "to", "from" fields of the emails processed with connector, connector produces two sets of fields: regular "to" and "from" fields that have email addresses in a format " email@address", and "to_raw" and "from_raw" that have only email address as a value, format: "email@address"

Exchange Mail Connector v2

Description

Connector periodically connects to the mail server to check for new emails in specific mailbox.

If new email present – connector pulls the email and creates a new alert to ingest in Google Security Operations SOAR with info from that email.

If no new emails found – connector finishes current run and sleeps for a defined period of time before the next run.

After each run connector updates the connector timestamp file with the last run date/time. Connector extracts actionable information for a case from email as a Mail Object technical result discussed earlier (additionally presented in event section below), such as, but not limited to:

  • sender/receiver of email,
  • email subject,
  • email body,
  • urls in email,
  • attachments.

Connector run finishes with creation of zero to many alerts (cases) for ingestion to Google Security Operations SOAR.

Next, based on the case data provided by Connector, Google Security Operations SOAR Server runs ETL procedures to ingest new alerts and create or update cases. If there are related playbooks defined – Siemplify Server executes playbooks to enrich the case, produce Google Security Operations SOAR Insights, perform automatic actions.

How to work with "Alert Name Template" and "Case Name Template"

These 2 parameters allow users to overwrite the way Alert/Case name is created. Let's assume that our Google Security Operations SOAR Event looks like this:

{
    "event": {
        "type": "Phishing"
        "name": "Bad Event",
        "id": "1"
    }
}

We want to create a Google Security Operations SOAR Alert that will have a name "Phishing - Bad Event". In this situation the template, would need to look like this:

[event_type] - [event_name]

Connector Parameters

Use the following parameters to configure the connector:

Parameter Display Name Type Default Value Is Mandatory Description
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 Yes Framework parameter, must be set for every connector. Describes the name of the field where the event name is stored
Environment Field Name String N/A No

Describes the name of the field where the environment name is stored.

If environment field isn't found, environment is ""
Environment Regex Pattern String N/A No

A regex pattern to run on the value found in the "Environment Field Name" field.

Default is .* to catch all and return value unchanged.

Used to allow the user to manipulate the environment field via regex logic

If regex pattern is null or empty, or the environment value is null, the final environment result is ""
Headers to add to events String N/A No Specify what headers from emails should be added to the events. Parameter accepts multiple values as a comma separated string. Provided values can be exact match or set as a regex.
Email exclude pattern String N/A No Regular expression to exclude specific emails from being ingested by the connector. Works with both subject and body part of email. Example is, to exclude mass mailing emails like news from being ingested.
Script Timeout (Seconds) Integer 60 Yes Timeout limit for the python process running the current script.
Mail Server Address String N/A Yes Mail server IP address to connect to. If connecting to Microsoft 365, server address should be set to outlook.office365.com
Mail Address

String

 N/A Yes Mail address to use in integration, to use for sending out emails and work with received emails for this email (mailbox)
Use Domain For Authentication Checkbox Checkbox unchecked No Use domain authentication to authenticate on mail server
Domain String N/A Yes Domain to authenticate with on mail server
Username String N/A Yes Username to authenticate with on mail server
Password Password N/A Yes A password to authenticate with on mail server
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
Unread Emails Only Checkbox Checkbox unchecked No If checked, cases will be pulled only from unread emails
Mark Emails as Read Checkbox Checkbox unchecked No If checked, after the emails have been pulled they will be marked as read.
Attach Original EML Checkbox Checkbox unchecked No If checked, the original email will be attached to the case info as an eml file.
Offset Time In Days Integer 5 Yes Fetch emails from X days backwards
Max Emails Per Cycle Integer 10 Yes Fetch x emails per connector cycle
Disable Overflow Checkbox Unchecked No If enabled, the connector will ignore the overflow mechanism.
Extract urls from HTML email part? Checkbox Unchecked No Specify whether connector should additionally try to extract urls from html part of email. This will allow connector to extract complex urls, but urls from plain text part of email will not be extracted with this method. Extracted urls will be available in urls_from_html_part event field.
Fetch Backwards Time Interval (minutes) Integer 0 No Time interval connector should use to fetch events from max hours backwards or connector last run timestamp. This parameter in minutes can be used to split max hours backwards on smaller segments and process them individually. Its recommended to adjust this value accordingly to the environment, for example 60 minutes or less.
Verify SSL Checkbox Unchecked No If enabled, verify the SSL certificate for the connection to the Exchange server is valid.
PythonProcessTimeout Integer 60 Yes Timeout limit for the python process running the current script.
Original Received Mail Prefix String orig No Prefix to add to the extracted event 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 event keys (to, from,subject,…) from the attached mail file received with the email in the monitored mailbox.
Create a Separate Siemplify Alert per Attached Mail File? Checkbox Unchecked No If enabled, connector will create multiple alerts, 1 alert per attached mail file. This behavior can be useful when processing email with multiple mail files attached and Google Security Operations SOAR event mapping set to create entities from attached mail file.
Alert Name Template String N/A No If provided, connector will use this value for Google Security Operations SOAR Alert Name. You can provide placeholders in the following format: [name of the field]. Example: Phishing - [event_mailbox]. Note: connector will use first Google Security Operations SOAR Event for placeholders. Only keys that have string value will be handled. If nothing is provided or user provides an invalid template, connector will use the default alert name.
Case Name Template String N/A No When provided, connector will add a new key called "custom_case_name" to the Google Security Operations SOAR Event. It can used to have a customer case name. Please refer to the documentation portal for more details. You can provide placeholders in the following format: [name of the field]. Example: Phishing - [event_mailbox]. Note: connector will use first Google Security Operations SOAR Event for placeholders. Only keys that have string value will be handled.
Proxy Server Address String N/A No Proxy server to use for connection to the mail server
Proxy Server Username String N/A No Proxy server username
Proxy Server Password String N/A No Proxy server password
Email Padding Period (minutes) Integer 0 No Specify an optional period in minutes that the connector should fetch emails from before the latest timestamp.

Connector rules

Blocklist and dynamic list
  • The connector doesn't support the blocklist rule.
  • WhiteLogic - Exchange integration should use the dynamic list section to define regex'es to parse email content to add to the email event specific fields based on the regular expression matches.
Proxy support

The connector supports Proxy.

Exchange Mail Connector v2 with OAuth Authentication

Description

Connector can be used to monitor specific mailboxes on Microsoft 365 mail servers that require OAuth authentication. Get Authorization and Generate Token actions can be used to obtain refresh token that should be set in the connector.

How to work with "Alert Name Template" and "Case Name Template"

These 2 parameters allow users to overwrite the way Alert/Case name is created. Let's assume that our Google Security Operations SOAR Event looks like this:

{
    "event": {
        "type": "Phishing"
        "name": "Bad Event",
        "id": "1"
    }
}

We want to create a Google Security Operations SOAR Alert that will have a name "Phishing - Bad Event". In this situation the template, would need to look like this:

[event_type] - [event_name]

Connector parameters

Use the following parameters to configure the connector:

Parameter Display Name Type Default Value Is Mandatory Description
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 Yes Framework parameter, must be set for every connector. Describes the name of the field where the event name is stored
Environment Field Name String N/A No

Describes the name of the field where the environment name is stored.

If environment field isn't found, environment is ""
Environment Regex Pattern String N/A No

A regex pattern to run on the value found in the "Environment Field Name" field.

Default is .* to catch all and return value unchanged.

Used to allow the user to manipulate the environment field via regex logic

If regex pattern is null or empty, or the environment value is null, the final environment result is ""
Headers to add to events String N/A No Specify what headers from emails should be added to the events. Parameter accepts multiple values as a comma separated string. Provided values can be exact match or set as a regex.
Email exclude pattern String N/A No Regular expression to exclude specific emails from being ingested by the connector. Works with both subject and body part of email. Example is, to exclude mass mailing emails like news from being ingested.
Script Timeout (Seconds) Integer 60 Yes Timeout limit for the python process running the current script.
Refresh Token Password N/A Yes For Microsoft 365 OAuth authentication, refresh token that was obtained from running "Get Authorization" and "Generate Token" actions.
Tenant (Directory) ID String N/A Yes For Microsoft 365 OAuth authentication, Azure Tenant (Directory) ID.
Client Secret Password N/A No For Microsoft 365 OAuth authentication, secret can be provided for the auth flow.
Client ID String N/A Yes For Microsoft 365 OAuth authentication, Client (Application) ID of Azure Active Directory App that will be used for the integration.
Mail Address String N/A Yes Mail address to use for connector.
Mail Server Address String N/A Yes Mail server IP address to connect to. If connecting to Microsoft 365, server address should be set to outlook.office365.com
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
Unread Emails Only Checkbox Unchecked No If checked, cases will be pulled only from unread emails
Mark Emails as Read Checkbox Unchecked No If checked, after the emails have been pulled they will be marked as read.
Attach Original EML Checkbox Unchecked No If checked, the original email will be attached to the case info as an eml file
Offset Time In Days Integer 5 Yes Fetch emails from X days backwards
Max Emails Per Cycle Integer 10 Yes Fetch x emails per connector cycle
Disable Overflow Checkbox Unchecked No If enabled, the connector will ignore the overflow mechanism.
Extract urls from HTML email part? Checkbox Unchecked No Specify whether connector should additionally try to extract urls from html part of email. This will allow connector to extract complex urls, but urls from plain text part of email will not be extracted with this method. Extracted urls will be available in urls_from_html_part event field.
Fetch Backwards Time Interval (minutes) Integer 0 No Time interval connector should use to fetch events from max hours backwards or connector last run timestamp. This parameter in minutes can be used to split max hours backwards on smaller segments and process them individually. Its recommended to adjust this value accordingly to the environment, for example 60 minutes or less.
Verify SSL Checkbox Unchecked No If enabled, verify the SSL certificate for the connection to the Exchange server is valid.
PythonProcessTimeout Integer 60 Yes Timeout limit for the python process running the current script.
Original Received Mail Prefix String orig No Prefix to add to the extracted event 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 event keys (to, from,subject,…) from the attached mail file received with the email in the monitored mailbox.
Create a Separate Siemplify Alert per Attached Mail File? Checkbox Unchecked No If enabled, connector will create multiple alerts, 1 alert per attached mail file. This behavior can be useful when processing email with multiple mail files attached and Google Security Operations SOAR event mapping set to create entities from attached mail file.
Alert Name Template String N/A No If provided, connector will use this value for Google Security Operations SOAR Alert Name. You can provide placeholders in the following format: [name of the field]. Example: Phishing - [event_mailbox]. Note: connector will use first Google Security Operations SOAR Event for placeholders. Only keys that have string value will be handled. If nothing is provided or user provides an invalid template, connector will use the default alert name.
Case Name Template String N/A No When provided, connector will add a new key called "custom_case_name" to the Google Security Operations SOAR Event. It can used to have a customer case name. Please refer to the documentation portal for more details. You can provide placeholders in the following format: [name of the field]. Example: Phishing - [event_mailbox]. Note: connector will use first Google Security Operations SOAR Event for placeholders. Only keys that have string value will be handled.
Proxy Server Address String N/A No Proxy server to use for connection to the mail server
Proxy Server Username String N/A No Proxy server username
Proxy Server Password String N/A No Proxy server password
Email Padding Period (minutes) Integer 0 No Specify an optional period in minutes that the connector should fetch emails from before the latest timestamp.

Jobs

Refresh Token Renewal Job

The goal of the Token Renewal Job is to periodically update the refresh token configured for the integration.

By default, the refresh token expires every 90 days, thus making integration unusable upon expiration. It is recommended to run this job every 7 or 14 days to make sure that the refresh token is up to date.

Job inputs

Parameters
Integration Environments Optional

Integration environments for which the job should update the refresh tokens.

This parameter accepts multiple values as a comma-separated string. Individual values should be enclosed in quotation marks (" " )
Connector Names Optional

Connector names for which the job should update the refresh tokens.

This parameter accepts multiple values as a comma-separated string. Individual values should be enclosed in quotation marks (" " )

OAuth Token Expiry Notification Job - Deprecated

OAuth Token Expiry Notification Job is recommended to use if the integration is working with OAuth refresh tokens.

If not used for 90 days, the refresh token expires. Upon expiration, the user should create a new refresh token to use it in the integration.

This job sends reminder emails to the configured list of recipients 10, 5, and 1 day before the token expires. Once a new token is set in this job, the notification timer starts over.

Job inputs

Parameters
Mail Server Address Required

The mail server IP address to connect to.

If connecting to Microsoft 365, the server address should be set to outlook.office365.com.

Default value is outlook.office365.com.
Mail Address for sending notifications Required

Mail address to use for sending out the notifications.
Notifications Recipients List Required

List of notification recipients.

This parameter accepts multiple values as a comma-separated string.
Client ID Required

Client (Application) ID of Azure Active Directory App that is used for the integration.
Tenant (Directory) ID Required

Azure Tenant (Directory) ID.
Refresh Token Required

Refresh token obtained from running the Get Authorization and Generate Token actions.