> For the complete documentation index, see [llms.txt](https://docs.expel.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.expel.io/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench.md). # Microsoft Defender for Endpoint Setup for Workbench This guide helps you integrate your Microsoft Defender for Endpoint installation with the Expel Workbench. {% hint style="info" %} We support alert status syncing from Workbench to Microsoft Defender for Endpoint. If enabled, when an ingested Microsoft threat creates an [Expel Alert](/workbench-reference/alerts/how-expel-alerts-work.md), its status (e.g. open, investigating, closed) is reflected back into Microsoft as the SOC conducts its work. Comments are also included for every state change, or for any action taken by the SOC (e.g. a Verify Action is sent). See the [Reference](#reference) for more information about status syncing. {% endhint %} ## Prerequisites * You must be able to log into the Microsoft Entra Admin Console as a user assigned the Global Administrator or User Administrator role. ## Step 1: Enable Console Access {% hint style="warning" %} **If your organization has already created a new Expel account for console access and enabled cross-tenant access for another Microsoft integration, you may skip to** [**Step 2: Create a Custom Microsoft Entra ID Application**](#step-2-create-a-custom-microsoft-entra-id-application)**.** The same "\@soc.expel.io" account provides access across all Microsoft services. {% endhint %} ### Enable Console Access for a New Account Expel requires console access to allow analysts to perform investigation and triage. Without this additional level of information, details cannot be verified by our analysts and an investigation cannot be initiated. For more information, see [Why Expel Asks for Console Access](/connect-your-technology/about-integrations/why-expel-asks-for-console-access.md). 1. [Log in to the Microsoft Entra Admin Center](https://entra.microsoft.com/) as a user assigned the Global Administrator or User Administrator role. 2. Navigate to **Entra ID > Users > All Users**. 3. Select **User > Invite external user**. 4. On the **Basics** tab, include the following: * **Email** - use your [Organization GUID](#user-content-fn-1)[^1] to create the email address in the format "\@soc.expel.io". For example, `a123bc45-aa12-123b@soc.expel.io` . * **Display Name** - enter "Expel SOC". 5. On the Assignments tab, configure the following: * Select **Add role**. * Search for and select **Global Reader**. {% hint style="info" %} This role provides read-only access across most Microsoft 365 and Azure management consoles. {% endhint %} 6. Select **Review + invite** and then **Invite**. The user account will be added to your directory as a guest, and an invitation will be sent to the email provided. ### Set Up Permissions You have two user permission options. * The simplest way to grant Expel access to the Microsoft Defender for Endpoint console is with **basic Entra ID AAD permissions**. * To more granularly control which permissions Expel has in Microsoft Defender for Endpoint, use **Role-Based Access Control (RBAC) permissions**. {% hint style="info" %} If the tenant is using RBAC to manage permissions in Microsoft Defender for Endpoint, basic AAD permissions will not be an option for that tenant. {% endhint %}
Option 1: Basic AAD Permissions Expel prefers full access but can still operate with read-only access (although some of our capabilities will be limited).
Access LevelDescriptionProcedure
Full accessUsers with full access can log in, view all system information, resolve alerts, submit files for deep analysis, and download the onboarding package.

Add the new Expel user to all of these Directory roles:

  • Security administrator
  • Security operator
  • Security reader
Read-only accessUsers with read-only access can log in, view all alerts, and related information. They cannot change alert states, submit files for deep analysis or perform any state-changing operations.
  1. Add the new Expel user to the Security Reader AAD built-in role.
  2. (Optional) Add the new Expel user to the Security Operator role, which is also required to view EDR alerts within your Microsoft Defender for Endpoint console.

If you choose to only grant the Security Reader role, we may not be able to view all of your alerts and may have limited investigative and monitoring capabilities for your device(s).

Option 2: RBAC Permissions {% hint style="danger" %} Enabling RBAC in Microsoft Defender for Endpoint may have an unintended consequence if you were previously using basic permissions. Users who were previously granted read-only access via the `Security Reader` role will be denied access until they are added to a Microsoft Defender for Endpoint role. {% endhint %} 1. From the Microsoft 365 Defender portal, navigate to **Permissions > Microsoft 365 Defender**. 2. Create the **new role** for Expel. 3. Enter a **role name** and **description**. 4. Select the permissions as indicated below (make sure to choose your correct technology).
TechnologyPermissions
Microsoft Defender for Endpoint RBAC

Required Permissions

  • View Data (all)
  • Security operations
  • Threat and vulnerability management
  • Alerts investigation

Recommended Permissions

  • Active remediation actions (all)
  • Security operations
  • Threat and vulnerability management
  • Remediation handling
  • Threat and vulnerability management
  • Exception handling
  • Live response capabilities (advanced)

Permissions Not Required

  • Manage security settings
Microsoft Defender XDR RBAC

Required Permissions

  • Security operations \ Security data \ Security data basics (read)
  • Security operations \ Raw data (Email & collaboration) \ Email & collaboration metadata (read)
  • Security operations \ Security data \ Response (manage)

Recommended Permissions

  • Security operations \ Security data \ Security data basics (read)
  • Security operations \ Security data \ Alerts (manage)
  • Security operations \ Raw data (Email & collaboration) \ Email & collaboration metadata (read)
  • Security operations \ Security data \ Response (manage)
  • Security operations \ Advanced live response (manage)
  • Security operations \ Security data \ File collection (manage)

Permissions Not Required

  • Authorization and settings \ Security settings \ Core security settings (manage)
  • Authorization and settings\Security settings \ Detection tuning (manage)
5. Select **Save**.
## Step 2: Enable Cross-Tenant Access In this step you will add Expel as an external organization and configure inbound trust. 1. Still in the Microsoft Entra Admin Center, navigate to **Entra ID > External Identities > Cross-tenant access settings**. 2. Select the **Organizational settings** tab. 3. Select **Add organization**. 4. On the Add organization pane, enter Expel’s tenant ID: `1cde81fd-b430-4035-b24d-709921922876` 5. Select **Expel** from the search results, and then select **Add**. 6. In the Organizational settings list, locate the **Expel** row and select **Inbound access**. 7. On the "Inbound access settings - Expel" page, select the **Trust settings** tab, and configure the following: * Select **Customize settings**. * Enable **Trust multifactor authentication from Microsoft Entra tenants**. * Enable **Trust compliant devices**. * Enable **Trust Microsoft Entra hybrid joined devices**. * Under Automatic redemption, enable **Automatically redeem invitations with the tenant Expel**. 8. Select **Save**. ## Step 3: Generate API Credentials Choose one of the following methods to enable secure API access. You will need to save the following value(s) as they are generated, for use later in this guide: * Directory (tenant) ID * Application (client) ID\*[^2] * Application (client) secret value\*[^2] {% hint style="info" %} Additional permissions are required if you would like to set up and use the auto remediation actions for which you are licensed. See [About Auto Remediations](/workbench-setup/auto-remediations/about-auto-remediations.md) for more information. {% endhint %}
Option 1: Enable the Expel Defender for Endpoint Integration (RECOMMENDED) 1. As an Administrator, go to the[ Expel Admin Consent Page](https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent\&client_id=30823cb8-7698-431e-a770-a5a656f754e9\&response_type=code\&sso_reload=true). 2. Review and accept the requested permissions. 3. The Expel Defender for Endpoint Integration app now appears under Enterprise Applications. * Review the properties and make sure that all permissions were properly granted. * Copy and save the **Directory (Tenant) ID**, as you will need it in the next step.
Option 2: Create a Custom Entra ID App 1. As an Azure administrator, [log in to Azure.](https://portal.azure.com/) 2. Navigate to App registrations and select **+ New registration**. 3. Fill in the application details as follows: * **Name** - enter "Expel Defender for Endpoint" or another name of your choosing. * **Supported account types** - select **Single tenant only** (first option). 4. Select **Register** to create the new application. 5. You will navigate automatically to the Settings page for the app you just created. 6. Copy and save the **Application (client) ID** and **Directory (tenant) ID** to a safe place, as you will need it in the next step. 7. In the left menu, go to **Manage > API permissions**. 8. Select **Add a permission**. 9. Select the **APIs my organization uses** tab and search for "WindowsDefenderATP". 10. Select **WindowsDefenderATP**. 11. For the permission type, select **Application permissions**. 12. Add the following permissions:
APIPermissions
WindowsDefenderATP

AdvancedQuery.Read.All

Alert.Read.All

File.Read.All

Ip.Read.All

Machine.CollectForensics

Machine.Read.All

Score.Read.All

SecurityConfiguration.Read.All

SecurityRecommendation.Read.All

Software.Read.All

Url.Read.All

User.Read.All

Vulnerability.Read.All

Microsoft GraphUser.Read
User.Read.All
12. After all permissions are assigned, select **Grant admin consent** and **Yes** at the prompt. 13. Still in the new app, use the left menu to go to **Manage > Certificates & secrets**. 14. Select **New client secret**. 15. For the new secret: * **Description** - enter a description, such as "Expel API". * **Expires** - select **730 days (24 months)**. 16. Select **Add**. 17. Copy and save the **client secret's** [**value**](#user-content-fn-3)[^3] to a safe place, as you will need it in the next step. This value only appears once.
## Step 4: Add Microsoft Defender for Endpoint as a Security Device in Workbench Now that we have the correct access configured and noted the credentials, we can integrate your tech with Workbench. 1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F). 2. In the side menu, navigate to **Organization Settings > Security Devices**. 3. Select the **Add Security Device** button. 4. In the search box, enter “Defender” and then select the Microsoft Defender for Endpoint integration. 5. Complete the fields as follows: * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName Defender”; this name will display in Workbench under the Name column, and is a text string that you can filter on. * **Location** - enter the location of your server. * **Directory (tenant) ID** - enter the directory (tenant) ID value from Step 3. * **Application (client) ID** - enter the application (client) ID value from Step 3. * *Leave this field blank if you chose to enable the Expel Defender for Endpoint Integration (*[*Step 3 Option 1*](#option-1-enable-the-expel-defender-for-endpoint-integration-recommended)*).* * **App (client) secret** - enter the application (client) secret value from Step 3. * *Leave this field blank if you chose to enable the Expel Defender for Endpoint Integration (*[*Step 3 Option 1*](#option-1-enable-the-expel-defender-for-endpoint-integration-recommended)*).* * **Enable status syncing?** - select **Yes** if you wish to enable status syncing. 6. Select **Save**. Your device should be created successfully within a few seconds. A few reminders: * After your connection is healthy, it will take some time for your device to begin polling and receiving data. * To check on the status, select the downward arrow for your device in the first column and choose **View details**. * Polling will happen first; data will be received after that. **You must refresh the page to see updates.** * If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support/how-to-reach-us.md). * To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work.md#device-tuning). ## Reference ### About Status Syncing If you have chosen to grant Manage permissions to Expel during your setup and have also enabled status syncing in the security device, syncing will be enabled upon completion of this guide. Workbench status syncing is available for any Microsoft customer using the Defender for Endpoint platform. The addition of Wayfinder MDR or other Microsoft services do not impact API permissions or Workbench status syncing. {% hint style="info" %} Syncing is currently one-way and Workbench serves as the source of truth. This means statuses in Microsoft are updated by Workbench, but Workbench is not informed or updated by status changes made in Microsoft. {% endhint %} ### **Limitations** **1. Syncing only applies to Microsoft threats that generate an Expel Alert.** If a Microsoft alert is ingested but does not meet our detections threshold (i.e. remains a vendor alert), then nothing “happens” in Microsoft. We acknowledge this creates a possible blind spot into knowing what our SOC is or is not triaging, and are committed to supporting this use case in the future. **2. Status syncing behaviors are limited to alert status and commenting.** Expel Alert assignment metadata (i.e. assigned to Expel, assigned to your organization) does not map back to Microsoft threats. ### Object Mappings | Workbench Object | Syncing Key | Microsoft Object | | ------------------- | ------------------ | ---------------- | | Expel Alert | Microsoft alert ID | Threat | | Investigation\*[^4] | N/A | N/A | | Incident\*[^4] | N/A | N/A | ### State Mappings | Expel Alert State or Action | Microsoft Status | | --------------------------- | -------------------------------- | | New / Reopened | Unresolved | | Investigating | In Progress | | Closed | Resolved | | (Closed Reason) | N/A (to be captured via comment) | | Expel Alert (Close Reason) | Microsoft Analyst Verdict | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | N/A | Undefined\*[^5] | |

Closed (Activity Blocked)

Closed (Attack Failed)
Closed (Incident)

Closed (True Positive)

| True Positive | |

Closed (Benign)

Closed (False Positive)

Closed (Testing)

Closed (Suppressed)

Closed (Suppressed - New Device)

Closed (Suppressed - Threshold Exceeded)

| False Positive | |

Closed (IT Misconfiguration)

Closed (Possible Policy Violation)

Closed (PUP/PUA)

Closed (Other)

| Suspicious | ### Comments In addition to state syncing, the close reason and associated analysis is added as a comment to the Microsoft Defender for Endpoint alert or incident upon closure. ### Supported Events | Event | Triggers Status Sync? | Triggers Comment? | | -------------------------------------- | --------------------- | ----------------- | | Expel Alert Created | ✅ | ✅ | | Expel Alert Closed | ✅ | ✅ | | Expel Alert Reopened | ✅ | ✅ | | Investigation Created | ✅ | ✅ | | Investigation Closed | ✅ | ✅ | | Investigation Promoted |


| ✅ | | Investigation Reopened |


| ✅ | | Incident Created | ✅ | ✅ | | Incident Closed | ✅ | ✅ | | Incident Promoted |


| ✅ | | Incident Reopened |


| ✅ | | Comment Created |


| ✅ | | Expel Alert Assigned |


| ✅ | | Investigation Assigned |


| ✅ | | Investigation Alert Added |


| ✅ | | Incident Assigned |


| ✅ | | Incident Downgraded |


| ✅ | | Investigative Action Analysis Assigned |


| ✅ | | Investigative Action Manual Action |


| ✅ | | Investigative Action Assigned |


| ✅ | | Notify Action Assigned |


| ✅ | | Verify Action Assigned |


| ✅ | | Verify Action Approved |


| ✅ | | Verify Action Denied |


| ✅ | | Incident Finding Created |


| ✅ | | Incident Finding Updated |


| ✅ | | Incident Finding Completed |


| ✅ | | Remediation Action Automated |


| ✅ | | Remediation Action Assigned |


| ✅ | | Remediation Action Completed |


| ✅ | | Remediation Action Automated Failed |


| ✅ | ## Troubleshooting **If you are encountering a 403 permissions error and are on Government Community Cloud (GCC):** Please [contact our support team](/support/how-to-reach-us.md) for assistance. [^1]: * [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F). * Go to **Organization Settings > My Organization**. * On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID. [^2]: *Custom Entra ID apps only.* [^3]: Make sure you copy the value, not the secret ID. [^4]: There is no apples-to-apples object def mapping between Workbench and Microsoft. Workbench Investigation/Incident states instead map to all S1 Threats associated with the Incident/Investigation. [^5]: Undefined is the typical, default status for a threat that has not been triaged and thus does not map to an Expel “Closed” state. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.expel.io/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.