Microsoft Defender for Endpoint Integration Guide
integrations endpoints microsoft edr
The following guide steps you through integrating Microsoft Defender for Endpoint with Secureworks® Taegis™ XDR.
Important
DeviceAlertEvents
table will be removed from Microsoft 365 Defender soon. It has been replaced by AlertInfo*
and AlertEvidence
tables. Please ensure that AlertInfo
and AlertEvidence
tables are selected and DeviceAlertEvents
table is unselected in Streaming API settings in Microsoft 365 Defender.
Use the provided XDR Terraform templates in your Azure account to configure your Defender for Microsoft Endpoint and Azure tenant. The default resource values provided in the template safely work for environments with up to 1,000 endpoints. For environments with greater than 1,000 endpoints or if you want to customize your own environment, you’ll need to do additional template modifications as detailed below.
Notes
- 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 | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Microsoft Defender for Endpoint | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓* |
Note
ScriptBlock events are collected only on Linux and macOS devices.
Configure Microsoft Defender for Endpoint Integration ⫘
- Download the Terraform templates.
- Unzip the archive and open the terraform.tfvars file in a text editor such as Notepad or vim.
- Change the following values to reflect your current environment. For more information, see Get subscription and tenant IDs in the Azure portal in the Microsoft Azure documentation.
- client_name
- azure_tenant_id
- azure_subscription_id
- azure_region
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.
Note
It is recommended to leave the resource group name as is.
- The Azure administrator can provide you the Azure Region code. If you do not know the region code associated with your Azure Region run the following command in Azure cloud shell (bash):
az account list-locations --query "sort_by([].{RegionalDisplayName:regionalDisplayName, Name:name}, &RegionalDisplayName)" -o table
- Modify the Terraform vars file terraform.tfvars with the corresponding region code and save the file.
Terraform Region
- If you need to configure for more than 1,000 endpoints, follow Steps 7-10. Otherwise, skip to Step 11.
-
To use the provided Terraform templates for more than 1,000 endpoints, you must calculate the Number of Required Throughput Units (TUs) and Partitions you need, then modify several entries in the Terraform template.
-
Determine your event throughput. Go to Advanced Hunting in Microsoft Defender portal and calculate the event throughput using the query below. Advanced Hunting queries have a timeout period of ten minutes. If your query times out, paste the query into a text editor and find and replace
7d
with6d
to shorten the search window. Shorten again, if necessary.
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)
Note
If you are using the former Microsoft Defender for Endpoint Portal, go to Advanced Hunting and use the following query instead:
DeviceAlertEvents | where Timestamp > ago(7d) | 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 Security Center:
TU Calculation
This query outputs the number of Events per Minute that the endpoints generate.
- Determine the number of Throughput Units and Partitions your Event Hub needs.
Throughput Units Calculator ⫘
If you have events per minute, you need 0 Throughput Units and 0 Partitions.
Calculate
Alternatively, use the following formula to calculate the required Throughput Units for the namespace:
(Events per minute
/60*3/1024)+1
= Number of throughput units
= Number of partitions
Note
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.
- 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 from Step 9 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 in Step 9 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 from Step 9 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 Step 9 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 in Step 9 above |
data_retention_length | 1 | XDR only requires 1 day - add more (up to 90 days) for your own purposes |
- Save the changes to your modified terraform.tfvars file.
- Upload all the provided Terraform files, including the edited terraform.tfvars file to Azure using the manage file share and Upload/Download files toolbar action buttons.
Terraform Upload
- From the Azure Cloud Bash shell, run the following command:
cd clouddrive && terraform init && terraform plan -out ScwxAppTest.tfplan && terraform apply ScwxAppTest.tfplan && terraform output
This process takes a few minutes to complete.
Note
The terraform apply
command requires that Global Administrator or Application Administrator Azure AD role be assigned to the user executing the command.
- Securely record the output of the commands—you need them for the rest of the configuration.
- Go to the URL presented in
azure_consent_url
, authenticate, and accept the permissions presented. - Configure the Security Center Data Export by navigating to Settings → Microsoft 365 Defender → Streaming API.
Note
If you are using the former Microsoft Defender for Endpoint Portal, navigate to Partners & APIs → Data export settings.
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 subscription.
- Select + Add and configure the export settings as follows:
- Name:
SCWX-XDR-Integration-Export
- 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
- Select Event Hub Name: Copy and paste the
event_hub_name
value found in the Terraform output. For example,SCWX-TDR-EventHub
. - Under Event Types, check Alerts and Devices categories.
Note
If you are using Microsoft 365 Defender Portal, please uncheck DeviceAlertEvents in the Devices category, if such option is present. The DeviceAlertEvents table has been replaced by the AlertInfo and AlertEvidence tables and should not be used.
Note
If you are using the former Microsoft Defender for Endpoint Portal, check all event types.
- Select Submit (or Save).
Set Up ATP Defender in XDR ⫘
With the terraform output from the above steps, complete the integration in XDR.
- Select Integrations → Cloud APIs from the left-hand side navigation in XDR. The Cloud API Integrations page displays.
- Select Add API Integration from the top right of the Cloud API Integrations table. The Cloud API Integrations dialog displays.
- Select Set up Defender Integrations under Microsoft Defender for Endpoint. The Set up Microsoft Defender for Endpoint dialog displays.
Microsoft Defender for Endpoint
- Enter the appropriate values you captured in the Terraform output from the Configure Microsoft Defender for Endpoint Integration process you completed above.
- Choose Done when you have the form filled out.
- You can confirm that the integration is now working by checking it on the XDR Cloud APIs page. A healthy integration shows a green Listening status.
Cloud API Integration Status
Recreate Azure Active Directory Application and Secret ⫘
If for any reason you need to regenerate the Azure Active Directory application and secret to be used in the integration in XDR, proceed with the following steps:
Clean Up Existing Lingering Azure Active Directory Application ⫘
- In Azure portal, go to Azure Active Directory. Select App registrations from the left side pane under the Manage group.
- Select All applications from the right side pane and type
SCWX-TDR-MDATP-APP
in the search box that displays Start typing a name or Application ID to filter these results. If you see one or more applications/clients listed in the results, select one of these applications. Otherwise, skip to the next section. - In the application, select Delete. A Delete app registration pane displays. Check the checkbox labelled I understand the implications of deleting this app registration, and then select Delete to delete the Azure AD application.
- If you see more than one application in step 2 of this section, delete each by repeating step 3 for all.
Use Terraform Template to Repopulate Azure Active Directory Application ⫘
- Download the second set of Terraform templates.
- Unzip the archive and open the terraform.tfvars file in a text editor such as Notepad or Vim.
- Change the azure_tenant_id value to reflect your current environment and save the file.
- Before selecting Upload, choose Add directory to create a new folder named repopulate_application in order to upload these new terraform template files to a different folder than before.
- Select the repopulate_application folder just created and choose Upload to upload all of application.tf, configuration.tf, output.tf, and terraform.tfvars to the repopulate_application folder.
- From the Azure Cloud Bash shell, run the following command:
cd clouddrive/repopulate_application && terraform init && terraform plan -out ScwxAppTest.tfplan && terraform apply ScwxAppTest.tfplan && terraform output
This process takes less time than before to complete.
- Securely record the output of the commands—you need them for the rest of the configuration.
- Go to the URL presented in
azure_consent_url
, authenticate, and accept the permissions presented. -
Securely Record information about the Event Hub—you will need to re-enter it in XDR.
- In Azure portal, go to Event Hubs and make note of the namespace being used for the Defender integration (it should begin with
SCWX-TDR-Namespace-
). Select the namespace. - Select Event Hubs in the left pane.
- Make note of the name of the active Event Hub. Select the Event Hub.
- Select Consumer groups in the left pane.
- Make note of the name of the non-default Consumer Group.
- Select Shared access policies in the left pane.
- Make note of the Shared Access Policy name. Select the policy.
- Copy the Primary key in the right pane. This is the Shared Access Policy key.
- In Azure portal, go to Event Hubs and make note of the namespace being used for the Defender integration (it should begin with
-
Go back to the Defender Integration in XDR, delete and re-create it using the information you just collected.
Scaling Event Hub ⫘
You can monitor the performance of your Event Hub by alerting on the Incoming Bytes and Outgoing Bytes metrics.
If the Incoming Bytes metric reaches (Number_of_TUs * 1 MB/s)
and/or the 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 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 (this 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 is to update the number of Throughput Units, which can be managed from 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.
Replacing an Event Hub ⫘
If XDR still cannot read data from your Event Hub as quickly as the messages are produced, then the Event Hub itself must be replaced.
To replace the Event Hub:
-
Create a new Event Hub but do not delete the old Event Hub yet.
- Refer to Step 6 above to calculate the required throughput, partition count, and Event Hub tier (Standard, Premium and Dedicated).
- Unzip the Terraform archive into a new directory. Continue to follow the directions for updating the Terraform parameters.
- Open the terraform.tfvars file in a text editor such as Notepad or vim. In order to generate a new Event Hub namespace, you must enter a slightly different client_name in terraform.tfvars. Set the replacement_eventhub to true in terraform.tfvars.
- Plan and apply the Terraform to create the Event Hub.
-
In the Microsoft Defender portal, modify the Streaming API settings.
- Add new settings and specify the Event Hub Namespace Resource ID and the name of the new Event Hub.
- Delete old settings.
-
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.
- In XDR, enter parameters of the new Event Hub in the Microsoft Defender for Endpoint integration.
- Delete the old Event Hub and Event Hub Namespace in the Azure Portal.
Remove Microsoft Defender for Endpoint Integration ⫘
To remove a Microsoft Defender for Endpoint integration:
- Delete the integration in XDR.
- Remove the Streaming API setting in Microsoft Defender (Settings → Microsoft 365 Defender → Streaming API).
- Delete the following Azure resources (which were created with Terraform):
- App Registration called
SCWX-TDR-MDATP-APP
. - Event Hub Namespace beginning with
SCWX-TDR-Namespace
.
Further Reading ⫘
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