From 6ef4a4838b88e59e938b160c215b4cf239035dcc Mon Sep 17 00:00:00 2001 From: Mahendra Kamble Date: Wed, 14 May 2025 14:28:52 +0530 Subject: [PATCH 1/6] CSOAR-3249 - initail commit --- .../integrations/microsoft-ews-daemon.md | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md index c61a856466..d8fcf11253 100644 --- a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md +++ b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md @@ -16,6 +16,40 @@ This integration is only for Cloud SOAR. Process emails with EWS Daemon. +## Overview + +### Purpose + +The Microsoft EWS Incoming Mail Daemon automatically retrieves emails. It enables seamless integration with security automation platforms by pulling in messages for further analysis and action. +### Use cases + +* Automatically ingest emails from monitored mailboxes for phishing analysis or ticketing systems. +* Feed email content into security orchestration workflows. +* Process and analyze attachments (e.g., .eml, .msg, documents) in near real-time. +* Extract and enrich sender/recipient metadata for further investigation. + +### Supported versions + +* Microsoft Exchange Online (Office 365) + +### Prerequisites +* Active Azure subscription +* Application registration with: + * Client ID + * Client Secret + * Tenant ID +* EWS API permissions +* Basic authentication (legacy) or OAuth 2.0 with modern authentication +* Correctly configured EWS endpoint +* Valid credentials or token + +### Limitations +* Certain Outlook-specific attachments may appear as ItemAttachment instead of FileAttachment +* Attachments of type ItemAttachment may lack file extensions or MIME types (e.g., content_type=None) +* Mailbox rate limits may apply depending on Microsoft tenant configuration + + + ## Actions * **Microsoft EWS Incoming Mail Daemon** *(Daemon)* - Automatically retrieve emails from EWS. From dbd92b353733e9d20a3f1391d4c03ba37e222788 Mon Sep 17 00:00:00 2001 From: Mahendra Kamble Date: Thu, 15 May 2025 15:22:53 +0530 Subject: [PATCH 2/6] CSOAR-3249 : updated the doc --- .../integrations/microsoft-ews-daemon.md | 57 ++++++++++++++++++- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md index d8fcf11253..345349e50e 100644 --- a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md +++ b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md @@ -43,12 +43,24 @@ The Microsoft EWS Incoming Mail Daemon automatically retrieves emails. It enable * Correctly configured EWS endpoint * Valid credentials or token -### Limitations -* Certain Outlook-specific attachments may appear as ItemAttachment instead of FileAttachment -* Attachments of type ItemAttachment may lack file extensions or MIME types (e.g., content_type=None) +### Limitations +* Certain attachments may be represented differently, which can result in missing or inconsistent file metadata (e.g., name or type). * Mailbox rate limits may apply depending on Microsoft tenant configuration +## Usage +### Basic usage +* Configure credentials (Tenant ID, Client ID, Client Secret). +* Set retrieval parameters like polling frequency, folders to include/exclude. +* Enable the Daemon action in a rule or playbook. +* Emails are pulled automatically. + +### Advanced usage +* Use filtering parameters to narrow email scope: + * Subject keywords + * Sender domain + * Date ranges +* Enable the Daemon action in a rule or playbook. ## Actions @@ -172,6 +184,45 @@ import IntegrationsAuth from '../../../../reuse/integrations-authentication.md'; For information about Microsoft EWS, see [Microsoft Exchange Web Services documentation](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth). +## API reference + +### Configuration +Environment variables or parameters: +* tenant +* client id +* client secret +* email: The service account email address +* password or OAuth token: Authentication credentials +* automation bridge +* and other fields info based on the requirement + +### Containment APIs + +### Rate Limits and Quotas +* Microsoft may enforce throttling based on: + * Number of concurrent EWS requests + * Number of items retrieved per call + * Number of mailbox accesses per day/hour + +#### Troubleshooting +| Issue | Resolution | Resolution | +| :-- |:-- |:-- | +| No emails retrieved | Incorrect folder, filters too strict | Check filters, verify folder ID | +| Authentication failed | Invalid credentials or token | Update credentials and reauthorize | + +### FAQ + +#### Can I filter which emails are fetched? +Yes. Filtering can be applied based on folders, received time. Custom filters may be implemented depending on integration configuration. + +#### How frequently does the Daemon poll for new messages? +The polling interval is determined by the configuration within the integration setup or automation rule. + +### Support +* For issues, questions, or improvements: +* Microsoft [Q&A](https://learn.microsoft.com/answers) +* Review logs on the portal using log search. + ## Category Email Gateway From dbe57badb6d191ee40d046a3b38d9bafdf7fa7df Mon Sep 17 00:00:00 2001 From: Mahendra Kamble Date: Fri, 16 May 2025 16:26:06 +0530 Subject: [PATCH 3/6] CSOAR-3249 : updated the doc --- .../integrations/microsoft-ews-daemon.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md index 345349e50e..9d82eaa4d5 100644 --- a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md +++ b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md @@ -180,6 +180,19 @@ import IntegrationsAuth from '../../../../reuse/integrations-authentication.md'; +* Host +* Authentication Method +* Username +* Password +* Primary SMTP Address +* Tenant +* Client ID +* Client Secret +* Cloud SOAR API URL +* Cloud SOAR Access ID +* Cloud SOAR Access Key +* etc. other details for filtering the mails +* Automation Engine Microsoft EWS Daemon configuration For information about Microsoft EWS, see [Microsoft Exchange Web Services documentation](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth). From 9171649750739dae52623e224c2b794141162381 Mon Sep 17 00:00:00 2001 From: Mahendra Kamble Date: Fri, 16 May 2025 16:33:25 +0530 Subject: [PATCH 4/6] CSOAR-3249 : updated the version --- .../app-central/integrations/microsoft-ews-daemon.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md index 9d82eaa4d5..db98ceef76 100644 --- a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md +++ b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md @@ -7,8 +7,8 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; microsoft-defender-atp -***Version: 2.5 -Updated: May 9, 2024*** +***Version: 2.6 +Updated: May 16, 2025*** :::sumo Cloud SOAR This integration is only for Cloud SOAR. @@ -248,3 +248,4 @@ Email Gateway * March 4, 2024 (v2.3) - Updated code for compatibility with Python 3.12 * March 21, 2024 (v2.4) - Resolved an issue related to the Email Body * May 9, 2024 (v2.5) - A new field has been added to the integration resource for specifying the folder or path to search within +* May 16, 2025 (v2.6) - Enhanced attachment handling to ensure accurate detection and processing. From 8199b9b64b7c19b9230e8ff9c605a9a360e9e73a Mon Sep 17 00:00:00 2001 From: John Pipkin Date: Fri, 16 May 2025 09:03:52 -0500 Subject: [PATCH 5/6] Updates from review --- .../integrations/microsoft-ews-daemon.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md index db98ceef76..8125c792c9 100644 --- a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md +++ b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md @@ -25,7 +25,7 @@ The Microsoft EWS Incoming Mail Daemon automatically retrieves emails. It enable * Automatically ingest emails from monitored mailboxes for phishing analysis or ticketing systems. * Feed email content into security orchestration workflows. -* Process and analyze attachments (e.g., .eml, .msg, documents) in near real-time. +* Process and analyze attachments (for example, .eml, .msg, documents) in near real-time. * Extract and enrich sender/recipient metadata for further investigation. ### Supported versions @@ -44,7 +44,7 @@ The Microsoft EWS Incoming Mail Daemon automatically retrieves emails. It enable * Valid credentials or token ### Limitations -* Certain attachments may be represented differently, which can result in missing or inconsistent file metadata (e.g., name or type). +* Certain attachments may be represented differently, which can result in missing or inconsistent file metadata (for example, name or type). * Mailbox rate limits may apply depending on Microsoft tenant configuration ## Usage @@ -201,13 +201,13 @@ For information about Microsoft EWS, see [Microsoft Exchange Web Services docume ### Configuration Environment variables or parameters: -* tenant -* client id -* client secret -* email: The service account email address -* password or OAuth token: Authentication credentials -* automation bridge -* and other fields info based on the requirement +* Tenant +* Client ID +* Client secret +* Email: The service account email address +* Password or OAuth token: Authentication credentials +* Automation bridge +* And other fields info based on the requirement ### Containment APIs From be21e383ddf3682c678ba751fa1fe63d6a9bab76 Mon Sep 17 00:00:00 2001 From: John Pipkin Date: Fri, 16 May 2025 10:31:58 -0500 Subject: [PATCH 6/6] Add directions for fields --- .../integrations/microsoft-ews-daemon.md | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md index 8125c792c9..7dbe319c29 100644 --- a/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md +++ b/docs/platform-services/automation-service/app-central/integrations/microsoft-ews-daemon.md @@ -180,19 +180,23 @@ import IntegrationsAuth from '../../../../reuse/integrations-authentication.md'; -* Host -* Authentication Method -* Username -* Password -* Primary SMTP Address -* Tenant -* Client ID -* Client Secret -* Cloud SOAR API URL -* Cloud SOAR Access ID -* Cloud SOAR Access Key -* etc. other details for filtering the mails -* Automation Engine +Use the information you set up in [Microsoft EWS configuration](#microsoft-ews-configuration) above: +* **Host**. Enter the host name of the EWS instance, for example, `outlook.office365.com`. +* **Authentication Method**. Select the [EWS authentication](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/authentication-and-ews-in-exchange) method: + * **Basic** + * **NTLM** + * **OAuth 2.0** +* **Username**. Enter the Microsoft EWS username. +* **Password**. Enter the Microsoft EWS password. +* **Primary SMTP Address**. Enter the [primary SMTP address](https://learn.microsoft.com/en-us/exchange/client-developer/web-service-reference/primarysmtpaddress) for the user. +* **Tenant ID**. Enter the [tenant ID](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-find-tenant) for authentication. +* **Client ID**. Enter the client ID for authentication. +* **Client Secret**. Enter the client secret for authentication. +* **Cloud SOAR API URL**. Enter the URL for your Cloud SOAR API, for example, `https://api.sumologic.com`. Enter the [API endpoint URL](/docs/api/getting-started/#sumo-logic-endpoints-by-deployment-and-firewall-security) for your region. +* **Access ID**. Enter the access ID from a Sumo Logic [access key](/docs/manage/security/access-keys/). Select **Default** as the scope when generating access keys. +* **Access Key**. Enter the access key associated with the Sumo Logic access ID entered above. +* **Automation Engine**. Select whether to use [Cloud or Bridge execution](/docs/platform-services/automation-service/automation-service-integrations/#cloud-or-bridge-execution). + Microsoft EWS Daemon configuration For information about Microsoft EWS, see [Microsoft Exchange Web Services documentation](https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth).