Microsoft Defender for Endpoint Integration Guide

The following guide steps you through integrating Microsoft Defender for Endpoint with Secureworks® Taegis™ XDR.

Note

• Microsoft Defender for Endpoint integration with XDR requires appropriate Microsoft licensing and an active Azure subscription. For more information, see the Microsoft 365 Document Minimum requirements for Microsoft Defender for Endpoint.
• To receive device telemetry events, such as process or authentication events, you must have Microsoft Defender for Endpoint Plan 2, or a Microsoft 365 E5 plan, or a Microsoft 365 A5 plan. Note that Microsoft Defender for Business plan only provides alert data. For more information, see the Microsoft 365 Document Compare Microsoft endpoint security plans.
• Each Azure Active Directory tenant ID can be used with only one XDR integration. If you try to configure a new XDR integration using an Azure AD tenant that already has an existing XDR integration, it will fail.
• Azure integrations are supported in US and EU regions, but may not be supported by Microsoft in other regions. Contact Microsoft directly to verify their support of services in other regions.
• Azure Active Directory and Microsoft 365 integrations are available for the global Azure cloud. Other national clouds, such as Azure Government, Azure China 21Vianet, and Azure Germany, are currently not supported.

Data Provided from Integration

	Alerts	Auth	DNS	File Collection	HTTP	NIDS	Netflow	Process	File Modification	API Call	Registry	Scriptblock	Management	Persistence	Thread Injection	Generic
Microsoft Defender for Endpoint	✓	✓	✓				✓	✓	✓	✓*	✓*	✓	✓	✓	✓*	✓

Note

API Call, Registry, and Thread Injection are only collected on Windows devices.

Determine Event Rate

Before proceeding with the integration, determine your event rate. Go to Advanced Hunting in Microsoft Defender portal and calculate the event rate using the query below.

AlertInfo | where Timestamp > ago(7d) | join AlertEvidence on AlertId | summarize count() by bin(Timestamp, 1m)
| union (DeviceInfo | where Timestamp > ago(7d) | summarize count() by bin(Timestamp, 1m)
| union (DeviceNetworkInfo  | where Timestamp > ago(7d) | summarize count() by bin(Timestamp,1m)
| union (DeviceProcessEvents  | where Timestamp > ago(7d) | summarize count() by bin(Timestamp,  1m)
| union (DeviceNetworkEvents  | where Timestamp > ago(7d) | summarize count() by bin(Timestamp, 1m)
| union (DeviceFileEvents   | where Timestamp > ago(7d) | summarize count() by bin(Timestamp, 1m)
| union (DeviceRegistryEvents  | where Timestamp > ago(7d) | summarize count() by bin(Timestamp, 1m)
| union (DeviceLogonEvents  | where Timestamp > ago(7d) | summarize count() by bin(Timestamp, 1m)
| union (DeviceImageLoadEvents  | where Timestamp > ago(7d) | summarize count() by bin(Timestamp,  1m)
| union (DeviceEvents  | where Timestamp > ago(7d) | summarize count() by bin(Timestamp, 1m) )))))))))
| summarize PerMinute= sum(count_) by Timestamp | summarize percentile(PerMinute, 99.9)

 

A query result looks like this in Microsoft Defender:

Event Rate Example

This query outputs the number of Events per Minute that the endpoints generate.

Determine Integration Method

Defender for Endpoint can integrate with XDR via either an Azure Storage Account or an Azure Event Hub.

Azure Storage Account

Important

Do not use Azure Storage Account integration method if the event rate calculated above exceeds 600,000 events per minute.

Storage Accounts are a consumption-based model. Your Azure subscription will be charged based on the actual amount of data that Defender for Endpoint writes to the Storage Account. If your throughput decreases, you will only be charged for the data used. If your throughput increases, your processing will scale automatically.

Azure Event Hub

Event Hubs are a provisioned model. You will configure partitions and throughput units based on the expected number of Microsoft Defender agents and expected event volume and be charged for that provisioned throughput. If your event volume decreases, you will continue to be charged the provisioned rate. If your throughput increases beyond the provisioned amount, transfer of data to XDR will be delayed and scaling the Event Hub can be a more difficult procedure.

Configure Microsoft Defender for Endpoint Integration

1. Select Integrations → Cloud APIs from the Taegis Menu. The Cloud API Integrations page displays.
2. Select Add an Integration from the top right of the Cloud API Integrations table. The Cloud API Integrations dialog displays.

3. From the Optimized tab, select the Microsoft Defender for Endpoint card. The Microsoft Defender dialog displays.

   

   Microsoft Defender for Endpoint Integration Type

4. Choose the appropriate integration method based on your requirements.

   Note

   If you are opted in to Preview mode, you can configure the integration for an Azure Government tenant by choosing the Storage Account method and selecting the Azure Government option.

5. Depending on the selected integration method, click on Download Event Hub Templates, or Download Storage Account Templates to download Terraform templates.

6. Unzip the archive and open the terraform.tfvars file in a text editor such as Notepad or vim.
7. Follow the instructions for Storage Accounts or Event Hubs as appropriate

Configure Microsoft Defender for Endpoint Storage Account Integration

1. Change the following values to reflect your current environment. For more information, see How to find your Azure Active Directory tenant ID in the Microsoft Azure documentation.

   • storage_account_name
   • azure_tenant_id
   • azure_subscription_id

   It is recommended to leave the resource group name as is.

   Note

   If you are configuring the integration for an Azure Government tenant, select the Azure Government checkbox in Step 4 of the preceding section and update these additional parameters:

   • azure_commercial
   • storage_account_name_queue

   Note

   Per Azure’s requirements, storage_account_name and storage_account_name_queue can contain only lowercase letters and numbers and must not exceed 24 characters. The name must be globally unique.

2. Skip ahead to Configure Azure.

Configure Microsoft Defender for Endpoint Event Hub Integration

1. Change the following values to reflect your current environment. For more information, see How to find your Azure Active Directory tenant ID in the Microsoft Azure documentation.

   • client_name
   • azure_tenant_id
   • azure_subscription_id

   Note

   Per Azure’s requirements, client_name can contain only letters, numbers, and hyphens. Combined length of client_name and azure_region must not exceed 30 characters. Whitespace is not allowed.

2. If you need to configure for more than 1,000 endpoints, follow Steps 3-4. Otherwise, save the changes to your modified terraform.tfvars file and skip to Configure Azure.

3. Calculate the Number of Required Throughput Units (TUs) and Partitions using the Throughput Units Calculator below and the event rate (number of Events per Minute) determined above.

Throughput Units Calculation

The formula to calculate the required Throughput Units and Partitions for the namespace is below.

(Events per minute / 60*3/1024)+1 = Number of throughput units = Number of partitions

If desired, use the throughput and partition calculator below.

Calculator

Enter the number of events and press Enter to calculate: 

You need   0   Throughput Units and    0   Partitions.

Important

Larger deployments require more partitions and more TUs per Event Hub. Take this into account if you expect your endpoint count to grow, because the partition count cannot be modified once created. You should enter the maximum number of Throughput Units needed to handle potential spikes in event flow. For example, if you have 2 Throughput Units defined, set this to 4 to provide double the potential on-demand capacity. Partitions do not auto-inflate.

4. After running the calculation, select the Event Hubs tier, and edit your terraform.tfvars file accordingly.

   • If the calculated number of required TUs is between 1 and 32, use Standard Event Hubs tier.

   Field	Default Value	Note
   require_dedicated_cluster	false	Do not use dedicated cluster
   eventhub_tier	Standard	Use Standard Event Hubs tier
   eventhub_throughput_allocated	2	Allow 1-32 based on TU calculation above
   eventhub_throughput_inflate_cap	4	This number should be larger than allocated TUs to allow for growth
   eventhub_partition_count	4	Allow 1-32 based on the number of Partitions you calculated above
   data_retention_length	1	XDR only requires 1 day - add more (up to 7 days) for your own purposes

   • If the calculated number of required TUs exceeds 32, but you have less than 50,000 endpoints, use Premium Event Hubs tier.

   Field	Default Value	Note
   require_dedicated_cluster	false	Do not use dedicated cluster
   eventhub_tier	Premium	Use Premium Event Hubs tier
   eventhub_processing_units	8	Choose between 1, 2, 4, 8 and 16 Processing Units (PUs) based on TU calculation above. 1 PU is approximately equivalent to 5-10 TUs.
   eventhub_partition_count	100	Allow 1-100 based on the number of Partitions you calculated in above
   data_retention_length	1	XDR only requires 1 day - add more (up to 90 days) for your own purposes

   • If your deployment exceeds 50,000 endpoints, you may need to use a dedicated Event Hubs cluster.

   Field	Default Value	Note
   require_dedicated_cluster	true	Very large deployments may require a dedicated cluster (50k+ Endpoints)
   eventhub_partition_count	1024	Allow 1-1024 based on the number of Partitions you calculated above
   data_retention_length	1	XDR only requires 1 day - add more (up to 90 days) for your own purposes

5. Save the changes to your modified terraform.tfvars file.

Configure Azure

1. Open the Azure Cloud Bash Shell and upload all the provided Terraform files, including the edited terraform.tfvars file to Azure using the Manage files and Upload toolbar action buttons.

   

   Terraform Upload

2. From the Azure Cloud Bash shell, run the following command. This process takes a few minutes to complete.

   terraform init && terraform plan -out ScwxAppTest.tfplan && terraform apply ScwxAppTest.tfplan && terraform output
   

   Note

   The terraform apply command requires that Global Administrator Azure AD role be assigned to the user executing the command.

3. Securely record the output of the commands—you need them for the rest of the configuration.

Configure Microsoft Defender

1. Configure the Microsoft Defender Data Export by navigating to Settings → Microsoft 365 Defender → Streaming API.

   Note

   This action requires the Global Administrator or Security Administrator role, and the account creating the Data Export must have access to the Event Hub or Storage Account subscription.

2. Select + Add and configure the export settings as follows:

   • Name: SCWX-XDR-Integration-Export

   If using an Azure Storage Account:

   • Forward events to Azure Storage Account: Checked
   • Storage Account Resource ID: Copy and paste the storage_account_resource_id value found in the Terraform output.

   An example Namespace Resource ID:/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/xx-xxx-x-xx-xxxxxxxx/providers/Microsoft.Storage/storageAccounts/StorageAccountName

   If using an Azure Event Hub:

   • Forward events to Azure Event Hub: Checked
   • Event Hub Resource Id: Copy and paste the event_hub_namespace_resource_id value found in the Terraform output.

   An example Namespace Resource ID:/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/resourceGroups/xx-xxx-x-xx-xxxxxxxx/providers/Microsoft.EventHub/namespaces/SCWX-XDR-Namespace-CustomerName

   • Event Hub Name: Copy and paste the event_hub_name value found in the Terraform output. For example, SCWX-TDR-EventHub.

3. Under Event Types, check Alerts and Devices categories.

4. Select Submit (or Save).

Finish Setting Up Microsoft Defender for Endpoint in XDR

With the terraform output from the preceding steps, complete the integration in XDR.

1. Confirm you are still navigated to the Microsoft Defender dialog and have made the choice of the integration method (Event Hub or Storage Account) and choose Next.

   

   Microsoft Defender for Endpoint Integration Type

2. Enter the appropriate values you captured in the Terraform output from the Configure Microsoft Defender for Endpoint Integration process you completed above.

• If you selected Storage Account, the form will show the following:

  

  Microsoft Defender for Endpoint Storage Account

• If you selected Storage Account and checked the Azure Government option, the form will show the following:

  

  Microsoft Defender for Endpoint Storage Account with Azure Government

• If you selected Event Hub, the form will show the following:

  

  Microsoft Defender for Endpoint Event Hub

3. Choose Done when you have completed the form.

4. You can confirm that the integration is now working by checking the XDR Cloud APIs page. A healthy integration shows a green Listening status.

   

   Cloud API Integration Status

Scaling Event Hub

You can monitor the performance of your Event Hub by alerting on the Incoming Bytes and Outgoing Bytes metrics.

If Incoming Bytes metric reaches (Number_of_TUs * 1 MB/s) and/or Outgoing Bytes metric reaches (Number_of_TUs * 2 MB/s), then the throughput of the Event Hub has reached its capacity, and the number of TUs should be increased.

However, if the throughput of your Event Hub hits a "ceiling" that is below TU-based capacity—and Secureworks® Taegis™ XDR Support advises that your Event Hub is under-provisioned—then the Event Hub should be replaced.

Find additional information on Scaling with Event Hubs.

Scaling a Premium or Dedicated Event Hub

You can dynamically change:

• Processing Units (PU) of Premium Event Hub.
• Capacity Units (CU) of Dedicated Event Hub cluster (requires a support request).
• The number of partitions in the Event Hub.

Scaling a Standard Event Hub

The first step for increasing the throughput of your Event Hub would be to try and update the number of Throughput Units. You can manage Throughput Units on the Scale tab of the Event Hubs Namespace page in the Azure Portal. You can also set an Auto-Inflate value on the same Scale settings to allow the Event Hub to automatically scale up the number of Throughput Units to meet usage needs.

If XDR still cannot read data from your Event Hub as quickly as the messages are produced then the Event Hub itself will need to be replaced.

To replace the Event Hub:

1. Create a new Event Hub (do not delete the old Event Hub yet).

   1. Refer to the documentation above to calculate the required throughput, partition count, and Event Hub tier (Standard, Premium and Dedicated).
   2. Unzip the Terraform archive into a new directory. Continue to follow the directions for updating the Terraform parameters.
   3. Open the terraform.tfvars file in a text editor such as Notepad or vim. In order to generate a new Event Hub namespace, you will have to enter a slightly different client_name in terraform.tfvars. Set the replacement_eventhub to true in terraform.tfvars.
   4. Plan and apply the Terraform to create the Event Hub.

2. In the Microsoft Defender portal, modify the Streaming API settings.

   1. Add new settings and specify the Event Hub Namespace Resource ID and the name of the new Event Hub.
   2. Delete old settings.

3. In the Azure Portal, confirm that the old Event Hub Outgoing Bytes and Outgoing Message metrics have dropped to zero. This may take some time. If it is acceptable to discard remaining data in the old Event Hub, you can skip this step.

4. In Secureworks® Taegis™ XDR, enter parameters of the new Event Hub in the Microsoft Defender for Endpoint integration.
5. Delete the old Event Hub in the Azure Portal.

Remove Microsoft Defender for Endpoint Integration

To remove a Microsoft Defender for Endpoint integration:

1. Delete the integration in XDR.
2. Remove the Streaming API setting in Microsoft Defender (Settings → Microsoft 365 Defender → Streaming API).

3. Delete the following Azure resources (which were created with Terraform):

   • Storage Account with the name given in terraform.tfvars in the 'scwx-datp-integration-rg' Resource Group
   • Event Hub Namespace beginning with SCWX-TDR-Namespace if applicable

Further Reading

• Minimum Requirements

• Deployment Phases

• Install guides for Windows, Mac, and Linux.

Test Events

Windows

Run the following PowerShell script on a newly onboarded device to verify that it is properly reporting to the Defender for Endpoint service. The Command Prompt window closes automatically upon execution. If successful, a new alert will appear in the portal for the onboarded device in approximately 10 minutes.

• Create a folder: 'C:\test-WDATP-test'.

• Open an elevated command-line prompt on the device and run the script:

  powershell.exe -NoExit -ExecutionPolicy Bypass -WindowStyle Hidden $ErrorActionPreference = "SilentlyContinue";(New-Object System.Net.WebClient).DownloadFile('http://127.0.0.1/1.exe', 'C:\\test-WDATP-test\\invoice.exe');Start-Process 'C:\\test-WDATP-test\\invoice.exe'
  

MacOS/Linux

curl -o ~/Downloads/eicar.com.txt https://www.eicar.org/download/eicar.com.txt