Fortinet Document Library

Version:

Version:

Version:

Version:


Table of Contents

About the connector

The Exchange connector provides a robust, platform-independent, and simple interface for communicating with Microsoft Exchange 2007-2016 Server or Office 365 using Exchange Web Services (EWS).

This document provides information about the Exchange connector, which facilitates automated interactions, with an Exchange server using FortiSOAR™ playbooks. Add the Exchange connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving unread emails, moving or deleting emails from the Exchange server, sending an email from the Exchange server, or running a query on the Exchange server based on the parameter (s) that you have specified.

Version information

Connector Version: 3.4.1

FortiSOAR™ Version Tested on: 6.0.0-790

Exchange Version Tested on: Microsoft Exchange 2007-2016 Server or Office 365

Authored By: Fortinet

Certified: Yes

Data Ingestion support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling email content from Exchange. Currently, "email content" in Exchange are mapped to "alerts" in FortiSOAR™.

For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation. The following playbooks have been added to support data ingestion:

  • >> Exchange > Extract and Link File Indicator
  • > Exchange > Create Record
  • > Exchange > Fetch

Important: If you have folders with duplicate names in your Exchange mailbox, then the listener and data ingestion will not work for such folders.

Release Notes for version 3.4.1

Following enhancements have been made to the Exchange Connector in version 3.4.1:

  • Added a new parameter "Folder Path to Monitor" to the "Enable Email Notification Service" configuration parameter. You can use the Folder Path to Monitor parameter to specify the path of the mailbox that you want the listener to monitor. This enables support for notification services on custom folders, i.e., now you can configure notification services to work on custom folders that you have defined.
    Note: If you have configured the listener for a custom folder and not the 'Inbox', then you must update the source and source_folder variables in the Set Variable step of the "> Exchange > Fetch" playbook from 'Inbox' to the custom folder. You require to enter the "Custom Folder" string in the source field and the name of the folder in the source_folder field. For example, if you want to monitor the "Inbox/Phishing" mailbox, then you need to enter Inbox/Phishing in the source_folder field. This is required for retrieving unread emails from the custom folder.
    An example screenshot follows:

Important: Exchange 3.4.0 and later will NOT work with version 4.12.x and earlier. This is because exchangelib==3.1.0 requires Python '>=3.5' but version 4.12.x has an earlier Python version.

Installing the connector

From version 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™repository and run the yum command as a root user to install connectors:

yum install cyops-connector-exchange

Prerequisites to configuring the connector

  • You must have the hostname of the Exchange server to which you will connect and perform the automated operations and the credentials to access that server.
  • You must install the exchangelib==3.1.0 python module.
  • You must open port 993 (IMAP) on the firewall to allow communication between FortiSOAR™ and the Exchange server.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Exchange connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
Exchange There are two types of MS Exchange solutions: hosted and cloud. Choose Office365 if you have the cloud services of Exchange or choose On-Premises if you have the hosted services of Exchange.
Note: Notification services will work on both cloud and on-premise solutions. 
Protocol Protocol that will be used to communicate with the Exchange server/Office 365 server. Choose either http and https.
By default, this is set to https.
Host Hostname of the Exchange server to which you will connect and perform the automated operations.  
Note: For Office365, add the host as outlook.office365.com.
Username Username to access the Exchange server/Office 365 server.
For Exchange, add the username in the format: Domain\Username.
Password Password to access the Exchange server.
Email Address Email address of the Exchange server that you are using.
Access Type (Optional) Access type for the user. You can choose between Delegate or Impersonation.
By default, this is set as Delegate.
If you select Impersonation, then ensure that in the Email Address field, you specify the email address that has been granted Impersonation rights. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Use Autodiscover An alias account will work for the given account details.
Defaults to False.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
Defaults to True.
Enable Email Notification Service Select this option, i.e., set it to True (default) to set up a listener that would instantly notify FortiSOAR™ whenever a new email arrives in the mailbox.
Once you select this option, the following parameters get populated:
  • Folder Path to Monitor: Path of the mailbox that you want the listener to monitor. By default, this is set to the user's 'Inbox'; however it can be changed to any folder by entering the path of that folder in this field. For example, to monitor a 'Phishing' mailbox that is present within 'Inbox', you can enter Inbox/Phishing in this field.
    Important: The name that you provide for the mailbox that you want to monitor must be unique. The listener will work only when the folder name is unique.
    Note: If you have configured the listener for a custom folder and not the 'Inbox', then you must update the source and source_folder variables in the Set Variable step of the "> Exchange > Fetch" playbook from 'Inbox' to the custom folder. You require to enter the "Custom Folder" string in the source field and the name of the folder in the source_folder field. For example, if you want to monitor the "Inbox/Phishing" mailbox, then you need to enter Inbox/Phishing in the source_folder field. This is required for retrieving unread emails from the custom folder.
    An example screenshot follows:
  • Listener Port: Port on which you want to start the listener.
    Note: This port is used for communication between FortiSOAR™ and the Exchange notification service process. 10011 is the default port number. You can specify any unused port number if the default port is unavailable. You can also use a similar port number for multiple Exchange connector configurations as the Exchange notification service process is capable of communicating with multiple Exchange servers.
  • Playbook Trigger: The API endpoint used to trigger the playbook
    Note: The playbook authentication method should be set as HMAC.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from version 4.10.0 onwards:  

Function Description Annotation and Category
Get Unread Emails Gets all unread emails from your Exchange account. You can also mark the retrieved Unread emails as Read. get_email_new
Investigation
Create Calendar Event Creates an event in a calendar on the Exchange Server, based on input parameters, such as subject, from date and to date, you have specified. create_event
Investigation
Get Calendar Events Gets events from the calendar on the Exchange server, based on the filter criteria, such as subject, from time, and to time, you have specified. get_events
Investigation
Get Contacts Retrieves the list of contacts from the mailbox associated with your Exchange account. get_contacts
Investigation
Delete Email Deletes an email from a specified folder in your Exchange account, based on the input parameters, such as message ID and delete type, you have specified. delete_email
Investigation
Mark Email as Read Marks an unread email as read in your Exchange account, based on the message ID you have specified. mark_as_read
Investigation
Move Email Moves an email from a specified folder to a specified folder, based on the message ID and the source and destination folder you have specified. move_email
Miscellaneous
Copy Email Copy an email from a specified folder to a specified folder, based on the message ID and the source and destination folder you have specified. copy_email
Miscellaneous
Search Email Runs a query in your Exchange account and searches emails, based on input parameters, such as folder name, email address, body, and subject, that you have specified. search_query
Investigation
Send Email Sends an email from your Exchange account. send_email
Investigation
Get Folder Metadata Retrieves the count of all the emails, including unread emails and subfolder details, from your Exchange account for the folder you have specified. get_folder_metadata
Investigation
Get Unread Emails (Deprecated) Gets all unread emails from your Exchange account. You can also mark the retrieved Unread emails as Read.
Important: This operation has been retained since the new Get Unread Emails has an updated output schema. If you have used this operation earlier in an existing playbook, then the playbook would fail if this operation is removed.
get_email
Investigation
Add Category Assigns categories to an email in your Exchange account based on the message ID and categories that you have specified. add_category
Containment
Get Category Retrieves categories associated with the specified email in your Exchange account based on the message ID that you have specified. get_category
Investigation
Remove Category Removes categories from an email in your Exchange account based on the message ID and categories that you have specified. remove_category
Investigation

operation: Get Unread Emails

Input parameters

Parameter Description
Source Select the source folder from which you want to retrieve unread emails from your Exchange account. You can choose from All, Inbox, Sent, Drafts, Trash, Custom Folder. By default, this is set as Inbox.
If you select All, then this operation will search for emails across all folders associated with your Exchange account.
If you select Custom Folder, then you must specify the folder in your Exchange account from which you want to retrieve unread emails.
Mark as Read Select this option, i.e., set it to True (default), to retrieve the unread emails from the Exchange account and also marks these emails as Read.
By default, this is set to True.
Pull Oldest First Select this option, i.e., set it to True to retrieve the oldest unread email first from the Exchange account, i.e., if this operation is checked, then the unread emails get sorted by datetime from oldest to newest. By default, this is unchecked, i.e., it is set as False.
Limit (Optional) Maximum number of emails, based on your filter criterion, you want to include in the output of this operation. If you do not specify anything in this field then all emails based on your filter criterion will be included in the output of this operation.
Parse Inline Images Select this option, i.e., set it to True, to retrieve the body of the unread emails including inline images, from the Exchange account. By default, this is set to False (option is unchecked).
Save Email Select this option, i.e., set it to True (default) to save the email as a file in the Attachments module.
Extract Attachment Data Select this option, i.e., set it to True (default) to also extract the attachment data for the unread emails, if the type of the attachment is eml or msg.
 

Output

The JSON contains details of all the unread emails retrieved from the Exchange server.

The output contains the following populated JSON schema:
{
     "attachments": [
         {
             "json": "",
             "file": "",
             "metadata": {
                 "content_type": "",
                 "content_length": "",
                 "sha1": "",
                 "md5": "",
                 "filename": "",
                 "sha256": ""
             },
             "text": ""
         }
     ],
     "parsed_attachment_data": [],
     "attachment_files": [],
     "item_id": "",
     "folder_path": "",
     "email_as_attachment": "",
     "body": {
         "json": "",
         "html": "",
         "text": ""
     },
     "headers": {
         "x-ms-exchange-processed-by-bccfoldering": "",
         "from": "",
         "x-ms-exchange-organization-authsource": "",
         "x-eoptenantattributedmessage": "",
         "dkim-signature": [],
         "x-ms-exchange-crosstenant-id": "",
         "x-ms-exchange-organization-network-message-id": "",
         "auto-submitted": "",
         "x-received": "",
         "x-gm-message-state": "",
         "authentication-results": "",
         "x-google-smtp-source": "",
         "x-ms-exchange-organization-authas": "",
         "x-microsoft-antispam-message-info": [],
         "x-ms-exchange-organization-messagedirectionality": "",
         "return-path": "",
         "x-ms-exchange-crosstenant-originalarrivaltime": "",
         "sender": "",
         "x-microsoft-exchange-diagnostics": [],
         "subject": "",
         "x-exchange-antispam-report-test": "",
         "x-ms-exchange-crosstenant-fromentityheader": "",
         "spamdiagnosticmetadata": "",
         "x-ms-exchange-crosstenant-network-message-id": "",
         "x-ms-publictraffictype": "",
         "message-id": "",
         "x-microsoft-antispam": "",
         "mime-version": "",
         "x-eopattributedmessage": "",
         "x-ms-exchange-transport-endtoendlatency": "",
         "reply-to": "",
         "received-spf": "",
         "x-ms-exchange-transport-crosstenantheadersstamped": "",
         "x-ms-exchange-organization-scl": "",
         "x-ms-office365-filtering-correlation-id": "",
         "x-exchange-antispam-report-cfa-test": "",
         "x-forefront-antispam-report": "",
         "content-type": "",
         "x-ms-traffictypediagnostic": "",
         "to": "",
         "x-google-dkim-signature": "",
         "spamdiagnosticoutput": "",
         "received": []
     },
     "epilogue": "",
     "preamble": ""
}

operation: Create Calendar Event

Input parameters

Parameter Description
Subject Subject line of the event that you want to create on the Exchange server.
Start Date Start date and time of the event that you want to create on the Exchange server.
End Date End date and time of the event that you want to create on the Exchange server.
Required Attendees Email IDs of the members who are required to attend the event. You must add the email IDs in the CSV or list format.
For example, @xyz.com, def@lmn.com
Optional Attendees (Optional) Email IDs of the optional members who can attend the event. You must add the email IDs in the CSV or list format.
Body (Optional) Details of the event that you want to create on the Exchange server.
Location (Optional) Location of the event that you want to create on the Exchange server.
Categories (Optional) Category of the event that you want to create on the Exchange server. You must add the categories in the CSV or list format.
For example, Blue category, Green Category, etc.
Show As (Optional) Status of the attendees when they are attending this event. You can choose one of the following options: Free, Working elsewhere, Tentative, Busy, or OOF.
Reminder (Optional) Time before the event starts when you want to set a reminder for the attendees. You can choose one of the following options: 0 minutes, 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hour, 3 hour, 4 hour, 8 hour, 12 hour, 1 day, 2 day, 3 day, 1 week, or 2 week.
Is All Day If you select this option, i.e., set it to True, then this sets the event as a full-day event.
By default, this is set to False.
Is Private If you select this option, i.e., set it to True, then this sets the event as a private event, and it can be viewed only by its attendees.
By default, this is set to True.

Output

The JSON output contains the status of the create calendar event operation. The JSON output returns a Success message if the calendar event is successfully added on the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Get Calendar Events

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Subject Subject text based on which you want to filter events on the Exchange server.
From Time Start date and time from when you want to retrieve events from the Exchange server.
To Time End date and time till when you want to retrieve events from the Exchange server.

Output

The JSON output contains the retrieved events from the calendar on the Exchange server, based on the input parameters you have specified.

The output contains the following populated JSON schema:
{
     "Organizer": "",
     "Importance": "",
     "Required attendees": [],
     "End": "",
     "Attachments": [
         {
             "size": "",
             "Name": "",
             "content_type": ""
         }
     ],
     "Legacy status": "",
     "Location": "",
     "Reminder minutes before start": "",
     "Subject": "",
     "Reminder is set": "",
     "sensitivity": "",
     "Is all day": "",
     "Start": "",
     "Categories": [],
     "Body": "",
     "Optional attendees": []
}

operation: Get Contacts

Input parameters

None.

Output

The JSON output contains the retrieved contact list from the mailbox on the Exchange server.

The output contains the following populated JSON schema:
{
     "N": "",
     "ADR": "",
     "TEL": "",
     "REV": "",
     "VERSION": "",
     "PRODID": "",
     "ORG": "",
     "CLASS": "",
     "EMAIL": "",
     "FN": "",
     "LABEL": "",
     "MAILER": ""
}

operation: Delete Email

Input parameters

Parameter Description
Message ID ID of the email that you want to delete from an Exchange account.
Delete Type Type of Delete that you want to use to delete the email. You can choose from the following options: Soft Delete, Hard Delete, or Move To Trash.
Folder Name (Optional) Folder in the Exchange account from which you want to delete the email.
By default, this is set as Inbox.
Target Email Address (Optional) Email address from which you want to delete the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.

Output

The JSON output contains the status of the delete operation. The JSON output returns a Success message if the email is successfully deleted from the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Mark Email as Read

Input parameters

Parameter Description
Message ID ID of the email that you want to mark as read.
Folder Name (Optional) Name of the folder name that contains the email message that you want to mark as read.

Output

The JSON output contains the status of the "mark email as read" operation. The JSON output returns a Success message if the specified email is successfully marked as read on the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Move Email

Input parameters

Parameter Description
Source Email Address (Optional) Email address from which you want to move the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Source Source folder on the Exchange server from where you want to move the email. To specify the source, you can choose to specify either the Folder Name or Folder Path.
If you choose Folder Name, then in the Source Folder Name parameter, specify the name of the source folder on the Exchange server from where you want to move the email.
If you choose Folder Path, then in the Source Folder Path parameter, specify the path of the source folder on the Exchange server from where you want to move the email. 
Message ID ID of the email that you want to move.
Destination Email Address (Optional) Email address to which you want to move the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Destination Folder Destination folder on the Exchange server to which you want to move the email. To specify the destination, you can choose to specify either the Folder Name or Folder Path.
If you choose Folder Name, then in the Destination Folder Name parameter, specify the name of the destination folder on the Exchange server to which you want to move the email.
If you choose Folder Path, then in the Destination Folder Path parameter, specify the path of the destination folder on the Exchange server to which you want to move the email. 

Output

The JSON output contains the status of the move operation. The JSON output returns a Success message if the email is successfully moved as per your specifications on the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Copy Email

Input parameters

Parameter Description
Source Email Address (Optional) Email address from which you want to copy the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Source Source folder on the Exchange server from where you want to copy the email. To specify the source, you can choose to specify either the Folder Name or Folder Path.
If you choose Folder Name, then in the Source Folder Name parameter, specify the name of the source folder on the Exchange server from where you want to copy the email.
If you choose Folder Path, then in the Source Folder Path parameter, specify the path of the source folder on the Exchange server from where you want to copy the email. 
Message ID ID of the email that you want to copy.
Destination Email Address (Optional) Email address to which you want to copy the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Destination Destination folder on the Exchange server to which you want to copy the email. To specify the destination, you can choose to specify either the Folder Name or Folder Path.
If you choose Folder Name, then in the Destination Folder Name parameter, specify the name of the destination folder on the Exchange server to which you want to copy the email.
If you choose Folder Path, then in the Destination Folder Path parameter, specify the path of the destination folder on the Exchange server to which you want to copy the email. 

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Search Email

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned.

Parameter Description
Target Email Address (Optional) Email address in which you want to search for emails.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Folder Name Folder in the Exchange account based on which you want to search for emails.
Note: If you enter All in this field, then this operation will search for emails across all folders associated with your Exchange account.
Subject Subject of the email message based on which you want to search emails on your Exchange account.
Body Content within the body of the email based on which you want to search emails on the Exchange account.
Sender Email address of the sender based on which you want to search emails on the Exchange account.
Limit Maximum number of emails, based on your filter criterion, you want to include in the output of this operation. If you do not specify anything in this field then all emails based on your filter criterion will be included in the output of this operation.
Email Range Maximum number of emails that you want to display in the output based on your search criteria.
If you do not specify the range, then all the emails based on your search criteria are displayed.
Pull Oldest First Select this option, i.e., set it to True to pull the oldest email first from the Exchange account, i.e., if this operation is checked, then the emails get sorted by datetime from oldest to newest. By default, this is unchecked, i.e., it is set as False.
Parse Inline Images Select this option, i.e., set it to True, to retrieve the body of the emails including inline images, from the Exchange server. By default, this is set to False (option is unchecked).
Extract Attachment Data Select this option, i.e., set it to True (default) to also extract the attachment data for the searched emails, if the type of the attachment is eml or msg.
Query Search parameters based on which you want to search emails on the Exchange server in the form of a query.
Accepts input in the dictionary format.
For example, {'subject__icontains' : '365', 'datetime_received__gt' : '2018-01-20T18:30:00.000Z'}
You can also provide options such as:
subject__exact='foo' // Returns items where subject is 'foo'. Same as filter(subject='foo'),
subject__iexact='foo' // Returns items where subject is 'foo', 'FOO' or 'Foo',
subject_contains='foo' //Returns items where subject contains 'foo',
subject_icontains, subject_startswith, and subject_istartswith.

Output

The JSON output contains the details of all emails that match the search criteria that you have specified.

The output contains the following populated JSON schema:
{
     "search_fields": "",
     "emails": [
         {
             "preamble": "",
             "headers": {
                 "X-Exchange-Antispam-Report-Test": "",
                 "X-EOPTenantAttributedMessage": "",
                 "Message-ID": "",
                 "Sender": "",
                 "Reply-To": "",
                 "X-MS-Exchange-Transport-CrossTenantHeadersStamped": "",
                 "SpamDiagnosticOutput": "",
                 "DKIM-Signature": [],
                 "X-Microsoft-Antispam-Message-Info": [],
                 "X-MS-Exchange-Processed-By-BccFoldering": "",
                 "X-MS-Exchange-CrossTenant-Network-Message-Id": "",
                 "X-MS-Exchange-Organization-AuthAs": "",
                 "X-MS-Office365-Filtering-Correlation-Id": "",
                 "X-Received": "",
                 "X-MS-Exchange-Organization-AuthSource": "",
                 "X-Microsoft-Exchange-Diagnostics": [],
                 "X-Forefront-Antispam-Report": "",
                 "Received-SPF": "",
                 "X-Microsoft-Antispam": "",
                 "X-Google-DKIM-Signature": "",
                 "Subject": "",
                 "X-MS-Exchange-CrossTenant-FromEntityHeader": "",
                 "X-MS-TrafficTypeDiagnostic": "",
                 "Received": [],
                 "X-MS-Exchange-Organization-SCL": "",
                 "X-MS-Exchange-Organization-Network-Message-Id": "",
                 "X-MS-PublicTrafficType": "",
                 "X-EOPAttributedMessage": "",
                 "X-Google-Smtp-Source": "",
                 "X-MS-Exchange-Transport-EndToEndLatency": "",
                 "X-Exchange-Antispam-Report-CFA-Test": "",
                 "X-MS-Exchange-CrossTenant-Id": "",
                 "To": "",
                 "From": "",
                 "X-MS-Exchange-Organization-MessageDirectionality": "",
                 "SpamDiagnosticMetadata": "",
                 "Content-Type": "",
                 "Auto-Submitted": "",
                 "X-Gm-Message-State": "",
                 "X-MS-Exchange-CrossTenant-OriginalArrivalTime": "",
                 "Return-Path": "",
                 "MIME-Version": "",
                 "Authentication-Results": ""
             },
             "epilogue": "",
             "file": "",
             "item_id": "",
             "attachments": [
                 {
                     "text": "",
                     "file": "",
                     "json": "",
                     "metadata": {
                         "filename": "",
                         "md5": "",
                         "sha256": "",
                         "content_type": "",
                         "sha1": "",
                         "content_length": ""
                     }
                 }
             ],
             "parsed_attachment_data": [],
             "folder_path": "",
             "body": {
                 "text": "",
                 "html": "",
                 "json": ""
             },
             "attachment_files": []
         }
     ]
}

operation: Send Email

Important: For this operation to work, you must have the FortiSOAR™ Built-in connector: "Utilities" (minimum version required is 2.0.1) installed on your system. For more information on FortiSOAR™ Built-in connectors, see FortiSOAR™ product documentation.

Input parameters

Parameter Description
Subject (Optional) Subject of the email message that you want to send from the Exchange account.
TO Recipients Email IDs of the members to whom you want to send the email message from the Exchange account. You must add the email IDs in the CSV or list format.
For example, abc@xyz.com, def@lmn.com
Important: You must specify email ID(s) in at least one of the following fields: TO Recipients, CC Recipients, or BCC Recipients.
CC Recipients Email IDs of the members to be added to the CC list of the email message that you want to send from the Exchange account. You must add the email IDs in the CSV or list format.
BCC Recipients Email IDs of the members to be added to the BCC list of the email message that you want to send from the Exchange account. You must add the email IDs in the CSV or list format.
Body (Optional) Message or content of the email that you want to send from the Exchange account.
Attachment IRIs (Optional) List of IRI ID(s) of the file (s) that you want to attach to the email that you want to send from the Exchange server. IRI IDs are used to access files from the Attachments module. You must add the Attachment IRIs in the CSV or list format.
Inline Attachment IRIs (Optional) List of IRI ID(s) of the file (s) that you want to add inline to the email that you want to send from the Exchange server. You can add the image content inline in the email body using its UUIDs. For example, <img src="cid%3Adfe26867-01a1-4969-8168-8c8882586538">

Output

The JSON output contains the status of the send email operation. The JSON output returns a Success message if the email is successfully sent from the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Get Folder Metadata

Input parameters

Parameter Description
Source Select the source folder whose total email count, including unread emails and subfolders details you want to retrieve from your Exchange account. You can choose from  Inbox, Sent, Drafts, Trash, Custom Folder. By default, this is set as Inbox.
If you select Custom Folder, then you must specify the folder in your Exchange account from which you want to retrieve unread emails.

Output

The output contains the following populated JSON schema:
{
     "total_email_count": "",
     "folder": "",
     "child_folder_count": "",
     "child_folder_metadata": [],
     "unread_email_count": ""
}

operation: Get Unread Emails (Deprecated)

Input parameters

Parameter Description
Source Select the source folder from which you want to retrieve unread emails from your Exchange account. You can choose from All, Inbox, Sent, Drafts, Trash, Custom Folder. By default, this is set as Inbox.
If you select All, then this operation will search for emails across all folders associated with your Exchange account.
If you select Custom Folder, then you must specify the folder in your Exchange account from which you want to retrieve unread emails.
Mark as Read Select this option, i.e., set it to True (default) to retrieve the unread emails from the Exchange account and also marks these emails as Read.
By default, this is set to True.
Pull Oldest First Select this option, i.e., set it to True to retrieve the oldest unread email first from the Exchange account, i.e., if this operation is checked, then the unread emails get sorted by datetime from oldest to newest. By default, this is unchecked, i.e., it is set as False.
Limit (Optional) Maximum number of emails, based on your filter criterion, you want to include in the output of this operation. If you do not specify anything in this field then all emails based on your filter criterion will be included in the output of this operation.
Parse Inline Images Select this option, i.e., set it to True, to retrieve the body of the unread emails including inline images, from the Exchange account. By default, this is set to False (option is unchecked).
Save Email Select this option, i.e., set it to True (default) to save the email as a file in the Attachments module.
Extract Attachment Data Select this option, i.e., set it to True (default) to also extract the attachment data for the unread emails, if the type of the attachment is eml or msg.
 

Output

The JSON contains details of all the unread emails retrieved from the Exchange server.

The output contains the following populated JSON schema:
{
     "attachments": [
         {
             "json": "",
             "file": "",
             "metadata": {
                 "content_type": "",
                 "content_length": "",
                 "sha1": "",
                 "md5": "",
                 "filename": "",
                 "sha256": ""
             },
             "text": ""
         }
     ],
     "parsed_attachment_data": [],
     "attachment_files": [],
     "item_id": "",
     "folder_path": "",
     "email_as_attachment": "",
     "body": {
         "json": "",
         "html": "",
         "text": ""
     },
     "headers": {
         "X-Microsoft-Exchange-Diagnostics": [],
         "X-Exchange-Antispam-Report-CFA-Test": "",
         "X-MS-Exchange-CrossTenant-OriginalArrivalTime": "",
         "X-MS-Exchange-Transport-EndToEndLatency": "",
         "MIME-Version": "",
         "X-Microsoft-Antispam": "",
         "X-Google-DKIM-Signature": "",
         "X-Received": "",
         "X-Forefront-Antispam-Report": "",
         "X-MS-PublicTrafficType": "",
         "DKIM-Signature": [],
         "X-Gm-Message-State": "",
         "From": "",
         "X-EOPTenantAttributedMessage": "",
         "X-MS-Exchange-CrossTenant-Id": "",
         "Authentication-Results": "",
         "X-MS-Exchange-Organization-AuthSource": "",
         "X-MS-Office365-Filtering-Correlation-Id": "",
         "Content-Type": "",
         "SpamDiagnosticMetadata": "",
         "SpamDiagnosticOutput": "",
         "Auto-Submitted": "",
         "Received-SPF": "",
         "X-EOPAttributedMessage": "",
         "Subject": "",
         "X-MS-Exchange-Organization-SCL": "",
         "Reply-To": "",
         "X-MS-Exchange-CrossTenant-Network-Message-Id": "",
         "X-MS-Exchange-Processed-By-BccFoldering": "",
         "X-MS-Exchange-Transport-CrossTenantHeadersStamped": "",
         "X-Google-Smtp-Source": "",
         "X-MS-Exchange-Organization-AuthAs": "",
         "Received": [],
         "To": "",
         "X-MS-Exchange-Organization-MessageDirectionality": "",
         "X-MS-Exchange-Organization-Network-Message-Id": "",
         "X-Exchange-Antispam-Report-Test": "",
         "X-MS-Exchange-CrossTenant-FromEntityHeader": "",
         "Message-ID": "",
         "X-Microsoft-Antispam-Message-Info": [],
         "X-MS-TrafficTypeDiagnostic": "",
         "Return-Path": "",
         "Sender": ""
     },
     "epilogue": "",
     "preamble": ""
}

operation: Add Category

Input parameters

Parameter Description
Source (Optional) Name of the source folder from which you want to retrieve the email to which you want to add categories. You can choose from the following options: All, Inbox, Sent, Drafts, Trash or Custom Folder. If you choose Custom Folder, then you must specify the following parameter:  
  • Folder Name: Name of the folder from which you want to retrieve the email.
Message ID Message ID of the email to which you want to assign the specified categories.
Categories CSV list of categories that you want to assign to the specified email.

Output

The output contains the following populated JSON schema:
{
     "subject": "",
     "status": "",
     "message_id": "",
     "message": "",
     "categories": []
}

operation: Get Category

Input parameters

Parameter Description
Source (Optional) Name of the source folder from which you want to retrieve the email whose categories you want to retrieve. You can choose from the following options: All, Inbox, Sent, Drafts, Trash or Custom Folder. If you choose Custom Folder, then you must specify the following parameter:  
  • Folder Name: Name of the folder from which you want to retrieve the email.
Message ID Message ID of the email whose categories you want to retrieve.

Output

The output contains the following populated JSON schema:
{
     "subject": "",
     "status": "",
     "message_id": "",
     "message": "",
     "categories": []
}

operation: Remove Category

Input parameters

Parameter Description
Source (Optional) Name of the source folder from which you want to retrieve the email whose categories you want to remove. You can choose from the following options: All, Inbox, Sent, Drafts, Trash or Custom Folder. If you choose Custom Folder, then you must specify the following parameter:  
  • Folder Name: Name of the folder from which you want to retrieve the email.
Message ID Message ID of the email from which you want to remove the specified categories.
Categories CSV list of categories that you want to remove from the specified email.

Output

The output contains the following populated JSON schema:
{
     "subject": "",
     "status": "",
     "message_id": "",
     "message": "",
     "removed": [],
     "not_found": [] 
}

Included playbooks

The Sample - Exchange - 3.4.1 playbook collection comes bundled with the Exchange connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Exchange connector.

  • Calendar : Create Calendar Event
  • Calendar : Get Calendar Events
  • Categorize : Add Category
  • Categorize : Get Category
  • Categorize : Remove Category
  • Contacts : Get Contacts
  • Email : Copy Email
  • Email : Delete Email
  • Email : Mark Email as Read
  • Email : Move Email
  • Email : Search Email
  • Email : Send Email
  • > Exchange > Extract and Link File Indicator
  • > Exchange > Fetch
  • Exchange > Ingest
  • >Exchange > Process Email
  • Folder : Get Folder Metadata
  • Get Unread Emails

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Troubleshooting

Issue when trying to save the connector configuration when you have upgraded the Exchange connector to version 3.4.0 or later

When you upgrade your exchange connector from an earlier version to version 3.4.0 or later, then you might get a "cannot import name FaultTolerance" error when you try to save the connector configuration.

Resolution:
This issue occurs because in version 3.4.0 , we have upgraded to exchangelib==3.1.0 and our connector framework does not refer to the latest exchangelib dependency package and instead refers to the old exchangelib==1.10.7 package. In order to update the reference, users require to remove the "__pycach__" folder and restart the 'uwsgi' service as described in the following steps:

  1. ssh to your FortiSOAR™ machine.
  2. Use the 'cd' command and navigate to the /opt/cyops-integrations/integrations/connectors/ directory.
  3. Use the rm -rf __pycache__ to remove the "__pycach__" folder from the "connectors" directory
  4. Use the 'cd' command and navigate to the exchange_3_4_0 directory.
  5. Use the rm -rf __pycache__ to remove the "__pycach__" folder from the "exchange_3_4_0" directory.
  6. Use the systemctl restart uwsgi command. to restart the 'uwsgi' service.

Listener stops monitoring (listening) the mailboxes, i.e., the notification service process stops

The listener can stop monitoring the mailboxes due to various reasons.

Resolution

To start the listener, you need to restart the "uwsgi" service using the following command:

# systemctl restart uwsgi

If you face this problem regularly, then you can schedule the attached script "restart_exchange.sh" that restarts the "uwsgi" service at regular intervals. To run the "restart_exchange.sh" script with a schedular do the following steps:

  • Copy the "restart_exchange.sh" script to the /home/csadmin folder.
  • Change the file permissions (assign "execute" permission for nginx) using the following command:
    chmod +x restart_exchange.sh
  • Schedule the script using crontab using the following command:
    crontab -e
  • Add a cron expression to the script so that the "uwsgi" service is restarted at a specified time
    For example, if you want to run the script in every day at 12 AM, then add the following cron expression:
    0 0 * * * /home/csadmin/restart_exchange.sh

About the connector

The Exchange connector provides a robust, platform-independent, and simple interface for communicating with Microsoft Exchange 2007-2016 Server or Office 365 using Exchange Web Services (EWS).

This document provides information about the Exchange connector, which facilitates automated interactions, with an Exchange server using FortiSOAR™ playbooks. Add the Exchange connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving unread emails, moving or deleting emails from the Exchange server, sending an email from the Exchange server, or running a query on the Exchange server based on the parameter (s) that you have specified.

Version information

Connector Version: 3.4.1

FortiSOAR™ Version Tested on: 6.0.0-790

Exchange Version Tested on: Microsoft Exchange 2007-2016 Server or Office 365

Authored By: Fortinet

Certified: Yes

Data Ingestion support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling email content from Exchange. Currently, "email content" in Exchange are mapped to "alerts" in FortiSOAR™.

For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation. The following playbooks have been added to support data ingestion:

Important: If you have folders with duplicate names in your Exchange mailbox, then the listener and data ingestion will not work for such folders.

Release Notes for version 3.4.1

Following enhancements have been made to the Exchange Connector in version 3.4.1:

Important: Exchange 3.4.0 and later will NOT work with version 4.12.x and earlier. This is because exchangelib==3.1.0 requires Python '>=3.5' but version 4.12.x has an earlier Python version.

Installing the connector

From version 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™repository and run the yum command as a root user to install connectors:

yum install cyops-connector-exchange

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Exchange connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Parameter Description
Exchange There are two types of MS Exchange solutions: hosted and cloud. Choose Office365 if you have the cloud services of Exchange or choose On-Premises if you have the hosted services of Exchange.
Note: Notification services will work on both cloud and on-premise solutions. 
Protocol Protocol that will be used to communicate with the Exchange server/Office 365 server. Choose either http and https.
By default, this is set to https.
Host Hostname of the Exchange server to which you will connect and perform the automated operations.  
Note: For Office365, add the host as outlook.office365.com.
Username Username to access the Exchange server/Office 365 server.
For Exchange, add the username in the format: Domain\Username.
Password Password to access the Exchange server.
Email Address Email address of the Exchange server that you are using.
Access Type (Optional) Access type for the user. You can choose between Delegate or Impersonation.
By default, this is set as Delegate.
If you select Impersonation, then ensure that in the Email Address field, you specify the email address that has been granted Impersonation rights. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Use Autodiscover An alias account will work for the given account details.
Defaults to False.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
Defaults to True.
Enable Email Notification Service Select this option, i.e., set it to True (default) to set up a listener that would instantly notify FortiSOAR™ whenever a new email arrives in the mailbox.
Once you select this option, the following parameters get populated:
  • Folder Path to Monitor: Path of the mailbox that you want the listener to monitor. By default, this is set to the user's 'Inbox'; however it can be changed to any folder by entering the path of that folder in this field. For example, to monitor a 'Phishing' mailbox that is present within 'Inbox', you can enter Inbox/Phishing in this field.
    Important: The name that you provide for the mailbox that you want to monitor must be unique. The listener will work only when the folder name is unique.
    Note: If you have configured the listener for a custom folder and not the 'Inbox', then you must update the source and source_folder variables in the Set Variable step of the "> Exchange > Fetch" playbook from 'Inbox' to the custom folder. You require to enter the "Custom Folder" string in the source field and the name of the folder in the source_folder field. For example, if you want to monitor the "Inbox/Phishing" mailbox, then you need to enter Inbox/Phishing in the source_folder field. This is required for retrieving unread emails from the custom folder.
    An example screenshot follows:
  • Listener Port: Port on which you want to start the listener.
    Note: This port is used for communication between FortiSOAR™ and the Exchange notification service process. 10011 is the default port number. You can specify any unused port number if the default port is unavailable. You can also use a similar port number for multiple Exchange connector configurations as the Exchange notification service process is capable of communicating with multiple Exchange servers.
  • Playbook Trigger: The API endpoint used to trigger the playbook
    Note: The playbook authentication method should be set as HMAC.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from version 4.10.0 onwards:  

Function Description Annotation and Category
Get Unread Emails Gets all unread emails from your Exchange account. You can also mark the retrieved Unread emails as Read. get_email_new
Investigation
Create Calendar Event Creates an event in a calendar on the Exchange Server, based on input parameters, such as subject, from date and to date, you have specified. create_event
Investigation
Get Calendar Events Gets events from the calendar on the Exchange server, based on the filter criteria, such as subject, from time, and to time, you have specified. get_events
Investigation
Get Contacts Retrieves the list of contacts from the mailbox associated with your Exchange account. get_contacts
Investigation
Delete Email Deletes an email from a specified folder in your Exchange account, based on the input parameters, such as message ID and delete type, you have specified. delete_email
Investigation
Mark Email as Read Marks an unread email as read in your Exchange account, based on the message ID you have specified. mark_as_read
Investigation
Move Email Moves an email from a specified folder to a specified folder, based on the message ID and the source and destination folder you have specified. move_email
Miscellaneous
Copy Email Copy an email from a specified folder to a specified folder, based on the message ID and the source and destination folder you have specified. copy_email
Miscellaneous
Search Email Runs a query in your Exchange account and searches emails, based on input parameters, such as folder name, email address, body, and subject, that you have specified. search_query
Investigation
Send Email Sends an email from your Exchange account. send_email
Investigation
Get Folder Metadata Retrieves the count of all the emails, including unread emails and subfolder details, from your Exchange account for the folder you have specified. get_folder_metadata
Investigation
Get Unread Emails (Deprecated) Gets all unread emails from your Exchange account. You can also mark the retrieved Unread emails as Read.
Important: This operation has been retained since the new Get Unread Emails has an updated output schema. If you have used this operation earlier in an existing playbook, then the playbook would fail if this operation is removed.
get_email
Investigation
Add Category Assigns categories to an email in your Exchange account based on the message ID and categories that you have specified. add_category
Containment
Get Category Retrieves categories associated with the specified email in your Exchange account based on the message ID that you have specified. get_category
Investigation
Remove Category Removes categories from an email in your Exchange account based on the message ID and categories that you have specified. remove_category
Investigation

operation: Get Unread Emails

Input parameters

Parameter Description
Source Select the source folder from which you want to retrieve unread emails from your Exchange account. You can choose from All, Inbox, Sent, Drafts, Trash, Custom Folder. By default, this is set as Inbox.
If you select All, then this operation will search for emails across all folders associated with your Exchange account.
If you select Custom Folder, then you must specify the folder in your Exchange account from which you want to retrieve unread emails.
Mark as Read Select this option, i.e., set it to True (default), to retrieve the unread emails from the Exchange account and also marks these emails as Read.
By default, this is set to True.
Pull Oldest First Select this option, i.e., set it to True to retrieve the oldest unread email first from the Exchange account, i.e., if this operation is checked, then the unread emails get sorted by datetime from oldest to newest. By default, this is unchecked, i.e., it is set as False.
Limit (Optional) Maximum number of emails, based on your filter criterion, you want to include in the output of this operation. If you do not specify anything in this field then all emails based on your filter criterion will be included in the output of this operation.
Parse Inline Images Select this option, i.e., set it to True, to retrieve the body of the unread emails including inline images, from the Exchange account. By default, this is set to False (option is unchecked).
Save Email Select this option, i.e., set it to True (default) to save the email as a file in the Attachments module.
Extract Attachment Data Select this option, i.e., set it to True (default) to also extract the attachment data for the unread emails, if the type of the attachment is eml or msg.
 

Output

The JSON contains details of all the unread emails retrieved from the Exchange server.

The output contains the following populated JSON schema:
{
     "attachments": [
         {
             "json": "",
             "file": "",
             "metadata": {
                 "content_type": "",
                 "content_length": "",
                 "sha1": "",
                 "md5": "",
                 "filename": "",
                 "sha256": ""
             },
             "text": ""
         }
     ],
     "parsed_attachment_data": [],
     "attachment_files": [],
     "item_id": "",
     "folder_path": "",
     "email_as_attachment": "",
     "body": {
         "json": "",
         "html": "",
         "text": ""
     },
     "headers": {
         "x-ms-exchange-processed-by-bccfoldering": "",
         "from": "",
         "x-ms-exchange-organization-authsource": "",
         "x-eoptenantattributedmessage": "",
         "dkim-signature": [],
         "x-ms-exchange-crosstenant-id": "",
         "x-ms-exchange-organization-network-message-id": "",
         "auto-submitted": "",
         "x-received": "",
         "x-gm-message-state": "",
         "authentication-results": "",
         "x-google-smtp-source": "",
         "x-ms-exchange-organization-authas": "",
         "x-microsoft-antispam-message-info": [],
         "x-ms-exchange-organization-messagedirectionality": "",
         "return-path": "",
         "x-ms-exchange-crosstenant-originalarrivaltime": "",
         "sender": "",
         "x-microsoft-exchange-diagnostics": [],
         "subject": "",
         "x-exchange-antispam-report-test": "",
         "x-ms-exchange-crosstenant-fromentityheader": "",
         "spamdiagnosticmetadata": "",
         "x-ms-exchange-crosstenant-network-message-id": "",
         "x-ms-publictraffictype": "",
         "message-id": "",
         "x-microsoft-antispam": "",
         "mime-version": "",
         "x-eopattributedmessage": "",
         "x-ms-exchange-transport-endtoendlatency": "",
         "reply-to": "",
         "received-spf": "",
         "x-ms-exchange-transport-crosstenantheadersstamped": "",
         "x-ms-exchange-organization-scl": "",
         "x-ms-office365-filtering-correlation-id": "",
         "x-exchange-antispam-report-cfa-test": "",
         "x-forefront-antispam-report": "",
         "content-type": "",
         "x-ms-traffictypediagnostic": "",
         "to": "",
         "x-google-dkim-signature": "",
         "spamdiagnosticoutput": "",
         "received": []
     },
     "epilogue": "",
     "preamble": ""
}

operation: Create Calendar Event

Input parameters

Parameter Description
Subject Subject line of the event that you want to create on the Exchange server.
Start Date Start date and time of the event that you want to create on the Exchange server.
End Date End date and time of the event that you want to create on the Exchange server.
Required Attendees Email IDs of the members who are required to attend the event. You must add the email IDs in the CSV or list format.
For example, @xyz.com, def@lmn.com
Optional Attendees (Optional) Email IDs of the optional members who can attend the event. You must add the email IDs in the CSV or list format.
Body (Optional) Details of the event that you want to create on the Exchange server.
Location (Optional) Location of the event that you want to create on the Exchange server.
Categories (Optional) Category of the event that you want to create on the Exchange server. You must add the categories in the CSV or list format.
For example, Blue category, Green Category, etc.
Show As (Optional) Status of the attendees when they are attending this event. You can choose one of the following options: Free, Working elsewhere, Tentative, Busy, or OOF.
Reminder (Optional) Time before the event starts when you want to set a reminder for the attendees. You can choose one of the following options: 0 minutes, 5 minutes, 10 minutes, 15 minutes, 30 minutes, 1 hour, 2 hour, 3 hour, 4 hour, 8 hour, 12 hour, 1 day, 2 day, 3 day, 1 week, or 2 week.
Is All Day If you select this option, i.e., set it to True, then this sets the event as a full-day event.
By default, this is set to False.
Is Private If you select this option, i.e., set it to True, then this sets the event as a private event, and it can be viewed only by its attendees.
By default, this is set to True.

Output

The JSON output contains the status of the create calendar event operation. The JSON output returns a Success message if the calendar event is successfully added on the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Get Calendar Events

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter Description
Subject Subject text based on which you want to filter events on the Exchange server.
From Time Start date and time from when you want to retrieve events from the Exchange server.
To Time End date and time till when you want to retrieve events from the Exchange server.

Output

The JSON output contains the retrieved events from the calendar on the Exchange server, based on the input parameters you have specified.

The output contains the following populated JSON schema:
{
     "Organizer": "",
     "Importance": "",
     "Required attendees": [],
     "End": "",
     "Attachments": [
         {
             "size": "",
             "Name": "",
             "content_type": ""
         }
     ],
     "Legacy status": "",
     "Location": "",
     "Reminder minutes before start": "",
     "Subject": "",
     "Reminder is set": "",
     "sensitivity": "",
     "Is all day": "",
     "Start": "",
     "Categories": [],
     "Body": "",
     "Optional attendees": []
}

operation: Get Contacts

Input parameters

None.

Output

The JSON output contains the retrieved contact list from the mailbox on the Exchange server.

The output contains the following populated JSON schema:
{
     "N": "",
     "ADR": "",
     "TEL": "",
     "REV": "",
     "VERSION": "",
     "PRODID": "",
     "ORG": "",
     "CLASS": "",
     "EMAIL": "",
     "FN": "",
     "LABEL": "",
     "MAILER": ""
}

operation: Delete Email

Input parameters

Parameter Description
Message ID ID of the email that you want to delete from an Exchange account.
Delete Type Type of Delete that you want to use to delete the email. You can choose from the following options: Soft Delete, Hard Delete, or Move To Trash.
Folder Name (Optional) Folder in the Exchange account from which you want to delete the email.
By default, this is set as Inbox.
Target Email Address (Optional) Email address from which you want to delete the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.

Output

The JSON output contains the status of the delete operation. The JSON output returns a Success message if the email is successfully deleted from the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Mark Email as Read

Input parameters

Parameter Description
Message ID ID of the email that you want to mark as read.
Folder Name (Optional) Name of the folder name that contains the email message that you want to mark as read.

Output

The JSON output contains the status of the "mark email as read" operation. The JSON output returns a Success message if the specified email is successfully marked as read on the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Move Email

Input parameters

Parameter Description
Source Email Address (Optional) Email address from which you want to move the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Source Source folder on the Exchange server from where you want to move the email. To specify the source, you can choose to specify either the Folder Name or Folder Path.
If you choose Folder Name, then in the Source Folder Name parameter, specify the name of the source folder on the Exchange server from where you want to move the email.
If you choose Folder Path, then in the Source Folder Path parameter, specify the path of the source folder on the Exchange server from where you want to move the email. 
Message ID ID of the email that you want to move.
Destination Email Address (Optional) Email address to which you want to move the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Destination Folder Destination folder on the Exchange server to which you want to move the email. To specify the destination, you can choose to specify either the Folder Name or Folder Path.
If you choose Folder Name, then in the Destination Folder Name parameter, specify the name of the destination folder on the Exchange server to which you want to move the email.
If you choose Folder Path, then in the Destination Folder Path parameter, specify the path of the destination folder on the Exchange server to which you want to move the email. 

Output

The JSON output contains the status of the move operation. The JSON output returns a Success message if the email is successfully moved as per your specifications on the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Copy Email

Input parameters

Parameter Description
Source Email Address (Optional) Email address from which you want to copy the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Source Source folder on the Exchange server from where you want to copy the email. To specify the source, you can choose to specify either the Folder Name or Folder Path.
If you choose Folder Name, then in the Source Folder Name parameter, specify the name of the source folder on the Exchange server from where you want to copy the email.
If you choose Folder Path, then in the Source Folder Path parameter, specify the path of the source folder on the Exchange server from where you want to copy the email. 
Message ID ID of the email that you want to copy.
Destination Email Address (Optional) Email address to which you want to copy the specified email.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Destination Destination folder on the Exchange server to which you want to copy the email. To specify the destination, you can choose to specify either the Folder Name or Folder Path.
If you choose Folder Name, then in the Destination Folder Name parameter, specify the name of the destination folder on the Exchange server to which you want to copy the email.
If you choose Folder Path, then in the Destination Folder Path parameter, specify the path of the destination folder on the Exchange server to which you want to copy the email. 

Output

The output contains the following populated JSON schema:
{
     "message": ""
}

operation: Search Email

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criteria is applied, and an unfiltered list is returned.

Parameter Description
Target Email Address (Optional) Email address in which you want to search for emails.
Important: The Exchange account that you have specified in the configuration parameters and using which the connector has logged into Exchange must have Impersonation rights on this email address. For information on how to grant Impersonation rights in Office 365, see the How to Grant Application Impersonation Rights in Office 365? article.
Folder Name Folder in the Exchange account based on which you want to search for emails.
Note: If you enter All in this field, then this operation will search for emails across all folders associated with your Exchange account.
Subject Subject of the email message based on which you want to search emails on your Exchange account.
Body Content within the body of the email based on which you want to search emails on the Exchange account.
Sender Email address of the sender based on which you want to search emails on the Exchange account.
Limit Maximum number of emails, based on your filter criterion, you want to include in the output of this operation. If you do not specify anything in this field then all emails based on your filter criterion will be included in the output of this operation.
Email Range Maximum number of emails that you want to display in the output based on your search criteria.
If you do not specify the range, then all the emails based on your search criteria are displayed.
Pull Oldest First Select this option, i.e., set it to True to pull the oldest email first from the Exchange account, i.e., if this operation is checked, then the emails get sorted by datetime from oldest to newest. By default, this is unchecked, i.e., it is set as False.
Parse Inline Images Select this option, i.e., set it to True, to retrieve the body of the emails including inline images, from the Exchange server. By default, this is set to False (option is unchecked).
Extract Attachment Data Select this option, i.e., set it to True (default) to also extract the attachment data for the searched emails, if the type of the attachment is eml or msg.
Query Search parameters based on which you want to search emails on the Exchange server in the form of a query.
Accepts input in the dictionary format.
For example, {'subject__icontains' : '365', 'datetime_received__gt' : '2018-01-20T18:30:00.000Z'}
You can also provide options such as:
subject__exact='foo' // Returns items where subject is 'foo'. Same as filter(subject='foo'),
subject__iexact='foo' // Returns items where subject is 'foo', 'FOO' or 'Foo',
subject_contains='foo' //Returns items where subject contains 'foo',
subject_icontains, subject_startswith, and subject_istartswith.

Output

The JSON output contains the details of all emails that match the search criteria that you have specified.

The output contains the following populated JSON schema:
{
     "search_fields": "",
     "emails": [
         {
             "preamble": "",
             "headers": {
                 "X-Exchange-Antispam-Report-Test": "",
                 "X-EOPTenantAttributedMessage": "",
                 "Message-ID": "",
                 "Sender": "",
                 "Reply-To": "",
                 "X-MS-Exchange-Transport-CrossTenantHeadersStamped": "",
                 "SpamDiagnosticOutput": "",
                 "DKIM-Signature": [],
                 "X-Microsoft-Antispam-Message-Info": [],
                 "X-MS-Exchange-Processed-By-BccFoldering": "",
                 "X-MS-Exchange-CrossTenant-Network-Message-Id": "",
                 "X-MS-Exchange-Organization-AuthAs": "",
                 "X-MS-Office365-Filtering-Correlation-Id": "",
                 "X-Received": "",
                 "X-MS-Exchange-Organization-AuthSource": "",
                 "X-Microsoft-Exchange-Diagnostics": [],
                 "X-Forefront-Antispam-Report": "",
                 "Received-SPF": "",
                 "X-Microsoft-Antispam": "",
                 "X-Google-DKIM-Signature": "",
                 "Subject": "",
                 "X-MS-Exchange-CrossTenant-FromEntityHeader": "",
                 "X-MS-TrafficTypeDiagnostic": "",
                 "Received": [],
                 "X-MS-Exchange-Organization-SCL": "",
                 "X-MS-Exchange-Organization-Network-Message-Id": "",
                 "X-MS-PublicTrafficType": "",
                 "X-EOPAttributedMessage": "",
                 "X-Google-Smtp-Source": "",
                 "X-MS-Exchange-Transport-EndToEndLatency": "",
                 "X-Exchange-Antispam-Report-CFA-Test": "",
                 "X-MS-Exchange-CrossTenant-Id": "",
                 "To": "",
                 "From": "",
                 "X-MS-Exchange-Organization-MessageDirectionality": "",
                 "SpamDiagnosticMetadata": "",
                 "Content-Type": "",
                 "Auto-Submitted": "",
                 "X-Gm-Message-State": "",
                 "X-MS-Exchange-CrossTenant-OriginalArrivalTime": "",
                 "Return-Path": "",
                 "MIME-Version": "",
                 "Authentication-Results": ""
             },
             "epilogue": "",
             "file": "",
             "item_id": "",
             "attachments": [
                 {
                     "text": "",
                     "file": "",
                     "json": "",
                     "metadata": {
                         "filename": "",
                         "md5": "",
                         "sha256": "",
                         "content_type": "",
                         "sha1": "",
                         "content_length": ""
                     }
                 }
             ],
             "parsed_attachment_data": [],
             "folder_path": "",
             "body": {
                 "text": "",
                 "html": "",
                 "json": ""
             },
             "attachment_files": []
         }
     ]
}

operation: Send Email

Important: For this operation to work, you must have the FortiSOAR™ Built-in connector: "Utilities" (minimum version required is 2.0.1) installed on your system. For more information on FortiSOAR™ Built-in connectors, see FortiSOAR™ product documentation.

Input parameters

Parameter Description
Subject (Optional) Subject of the email message that you want to send from the Exchange account.
TO Recipients Email IDs of the members to whom you want to send the email message from the Exchange account. You must add the email IDs in the CSV or list format.
For example, abc@xyz.com, def@lmn.com
Important: You must specify email ID(s) in at least one of the following fields: TO Recipients, CC Recipients, or BCC Recipients.
CC Recipients Email IDs of the members to be added to the CC list of the email message that you want to send from the Exchange account. You must add the email IDs in the CSV or list format.
BCC Recipients Email IDs of the members to be added to the BCC list of the email message that you want to send from the Exchange account. You must add the email IDs in the CSV or list format.
Body (Optional) Message or content of the email that you want to send from the Exchange account.
Attachment IRIs (Optional) List of IRI ID(s) of the file (s) that you want to attach to the email that you want to send from the Exchange server. IRI IDs are used to access files from the Attachments module. You must add the Attachment IRIs in the CSV or list format.
Inline Attachment IRIs (Optional) List of IRI ID(s) of the file (s) that you want to add inline to the email that you want to send from the Exchange server. You can add the image content inline in the email body using its UUIDs. For example, <img src="cid%3Adfe26867-01a1-4969-8168-8c8882586538">

Output

The JSON output contains the status of the send email operation. The JSON output returns a Success message if the email is successfully sent from the Exchange server or an Error message containing the reason for failure.

The output contains the following populated JSON schema:
{
    "message": ""
}

operation: Get Folder Metadata

Input parameters

Parameter Description
Source Select the source folder whose total email count, including unread emails and subfolders details you want to retrieve from your Exchange account. You can choose from  Inbox, Sent, Drafts, Trash, Custom Folder. By default, this is set as Inbox.
If you select Custom Folder, then you must specify the folder in your Exchange account from which you want to retrieve unread emails.

Output

The output contains the following populated JSON schema:
{
     "total_email_count": "",
     "folder": "",
     "child_folder_count": "",
     "child_folder_metadata": [],
     "unread_email_count": ""
}

operation: Get Unread Emails (Deprecated)

Input parameters

Parameter Description
Source Select the source folder from which you want to retrieve unread emails from your Exchange account. You can choose from All, Inbox, Sent, Drafts, Trash, Custom Folder. By default, this is set as Inbox.
If you select All, then this operation will search for emails across all folders associated with your Exchange account.
If you select Custom Folder, then you must specify the folder in your Exchange account from which you want to retrieve unread emails.
Mark as Read Select this option, i.e., set it to True (default) to retrieve the unread emails from the Exchange account and also marks these emails as Read.
By default, this is set to True.
Pull Oldest First Select this option, i.e., set it to True to retrieve the oldest unread email first from the Exchange account, i.e., if this operation is checked, then the unread emails get sorted by datetime from oldest to newest. By default, this is unchecked, i.e., it is set as False.
Limit (Optional) Maximum number of emails, based on your filter criterion, you want to include in the output of this operation. If you do not specify anything in this field then all emails based on your filter criterion will be included in the output of this operation.
Parse Inline Images Select this option, i.e., set it to True, to retrieve the body of the unread emails including inline images, from the Exchange account. By default, this is set to False (option is unchecked).
Save Email Select this option, i.e., set it to True (default) to save the email as a file in the Attachments module.
Extract Attachment Data Select this option, i.e., set it to True (default) to also extract the attachment data for the unread emails, if the type of the attachment is eml or msg.
 

Output

The JSON contains details of all the unread emails retrieved from the Exchange server.

The output contains the following populated JSON schema:
{
     "attachments": [
         {
             "json": "",
             "file": "",
             "metadata": {
                 "content_type": "",
                 "content_length": "",
                 "sha1": "",
                 "md5": "",
                 "filename": "",
                 "sha256": ""
             },
             "text": ""
         }
     ],
     "parsed_attachment_data": [],
     "attachment_files": [],
     "item_id": "",
     "folder_path": "",
     "email_as_attachment": "",
     "body": {
         "json": "",
         "html": "",
         "text": ""
     },
     "headers": {
         "X-Microsoft-Exchange-Diagnostics": [],
         "X-Exchange-Antispam-Report-CFA-Test": "",
         "X-MS-Exchange-CrossTenant-OriginalArrivalTime": "",
         "X-MS-Exchange-Transport-EndToEndLatency": "",
         "MIME-Version": "",
         "X-Microsoft-Antispam": "",
         "X-Google-DKIM-Signature": "",
         "X-Received": "",
         "X-Forefront-Antispam-Report": "",
         "X-MS-PublicTrafficType": "",
         "DKIM-Signature": [],
         "X-Gm-Message-State": "",
         "From": "",
         "X-EOPTenantAttributedMessage": "",
         "X-MS-Exchange-CrossTenant-Id": "",
         "Authentication-Results": "",
         "X-MS-Exchange-Organization-AuthSource": "",
         "X-MS-Office365-Filtering-Correlation-Id": "",
         "Content-Type": "",
         "SpamDiagnosticMetadata": "",
         "SpamDiagnosticOutput": "",
         "Auto-Submitted": "",
         "Received-SPF": "",
         "X-EOPAttributedMessage": "",
         "Subject": "",
         "X-MS-Exchange-Organization-SCL": "",
         "Reply-To": "",
         "X-MS-Exchange-CrossTenant-Network-Message-Id": "",
         "X-MS-Exchange-Processed-By-BccFoldering": "",
         "X-MS-Exchange-Transport-CrossTenantHeadersStamped": "",
         "X-Google-Smtp-Source": "",
         "X-MS-Exchange-Organization-AuthAs": "",
         "Received": [],
         "To": "",
         "X-MS-Exchange-Organization-MessageDirectionality": "",
         "X-MS-Exchange-Organization-Network-Message-Id": "",
         "X-Exchange-Antispam-Report-Test": "",
         "X-MS-Exchange-CrossTenant-FromEntityHeader": "",
         "Message-ID": "",
         "X-Microsoft-Antispam-Message-Info": [],
         "X-MS-TrafficTypeDiagnostic": "",
         "Return-Path": "",
         "Sender": ""
     },
     "epilogue": "",
     "preamble": ""
}

operation: Add Category

Input parameters

Parameter Description
Source (Optional) Name of the source folder from which you want to retrieve the email to which you want to add categories. You can choose from the following options: All, Inbox, Sent, Drafts, Trash or Custom Folder. If you choose Custom Folder, then you must specify the following parameter:  
  • Folder Name: Name of the folder from which you want to retrieve the email.
Message ID Message ID of the email to which you want to assign the specified categories.
Categories CSV list of categories that you want to assign to the specified email.

Output

The output contains the following populated JSON schema:
{
     "subject": "",
     "status": "",
     "message_id": "",
     "message": "",
     "categories": []
}

operation: Get Category

Input parameters

Parameter Description
Source (Optional) Name of the source folder from which you want to retrieve the email whose categories you want to retrieve. You can choose from the following options: All, Inbox, Sent, Drafts, Trash or Custom Folder. If you choose Custom Folder, then you must specify the following parameter:  
  • Folder Name: Name of the folder from which you want to retrieve the email.
Message ID Message ID of the email whose categories you want to retrieve.

Output

The output contains the following populated JSON schema:
{
     "subject": "",
     "status": "",
     "message_id": "",
     "message": "",
     "categories": []
}

operation: Remove Category

Input parameters

Parameter Description
Source (Optional) Name of the source folder from which you want to retrieve the email whose categories you want to remove. You can choose from the following options: All, Inbox, Sent, Drafts, Trash or Custom Folder. If you choose Custom Folder, then you must specify the following parameter:  
  • Folder Name: Name of the folder from which you want to retrieve the email.
Message ID Message ID of the email from which you want to remove the specified categories.
Categories CSV list of categories that you want to remove from the specified email.

Output

The output contains the following populated JSON schema:
{
     "subject": "",
     "status": "",
     "message_id": "",
     "message": "",
     "removed": [],
     "not_found": [] 
}

Included playbooks

The Sample - Exchange - 3.4.1 playbook collection comes bundled with the Exchange connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Exchange connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Troubleshooting

Issue when trying to save the connector configuration when you have upgraded the Exchange connector to version 3.4.0 or later

When you upgrade your exchange connector from an earlier version to version 3.4.0 or later, then you might get a "cannot import name FaultTolerance" error when you try to save the connector configuration.

Resolution:
This issue occurs because in version 3.4.0 , we have upgraded to exchangelib==3.1.0 and our connector framework does not refer to the latest exchangelib dependency package and instead refers to the old exchangelib==1.10.7 package. In order to update the reference, users require to remove the "__pycach__" folder and restart the 'uwsgi' service as described in the following steps:

  1. ssh to your FortiSOAR™ machine.
  2. Use the 'cd' command and navigate to the /opt/cyops-integrations/integrations/connectors/ directory.
  3. Use the rm -rf __pycache__ to remove the "__pycach__" folder from the "connectors" directory
  4. Use the 'cd' command and navigate to the exchange_3_4_0 directory.
  5. Use the rm -rf __pycache__ to remove the "__pycach__" folder from the "exchange_3_4_0" directory.
  6. Use the systemctl restart uwsgi command. to restart the 'uwsgi' service.

Listener stops monitoring (listening) the mailboxes, i.e., the notification service process stops

The listener can stop monitoring the mailboxes due to various reasons.

Resolution

To start the listener, you need to restart the "uwsgi" service using the following command:

# systemctl restart uwsgi

If you face this problem regularly, then you can schedule the attached script "restart_exchange.sh" that restarts the "uwsgi" service at regular intervals. To run the "restart_exchange.sh" script with a schedular do the following steps: