Enable Defender for Endpoint integration in Microsoft Defender for Cloud

Microsoft Defender for Cloud integrates natively with Microsoft Defender for Endpoint to provide Defender for Endpoint and Defender Vulnerability Management capabilities in Defender for Cloud.

• When you enable the Defender for Servers plan in Defender for Cloud, Defender for Endpoint integration is enabled by default.
• The integration deploys or uses an existing Defender for Endpoint installation on supported machines when prerequisites are met.

This article explains how to manually enable Defender for Endpoint integration if it was previously turned off or if you have a legacy subscription that requires manual opt-in.

Prerequisites

Before you enable Defender for Endpoint integration, review these requirements.

Pre-deployment validation

Complete these checks before you enable Defender for Endpoint integration:

• Confirm that the machine is powered on and runs a supported operating system.
• For Azure Arc-enabled machines, confirm that the Azure Connected Machine agent reports a healthy connection.
• Confirm that the machine can reach the Defender for Endpoint service URLs. Don't use a test against a single URL as proof that all required service endpoints are reachable.
• Confirm that your proxy doesn't require interactive user authentication. The Defender for Endpoint sensor connects in the system context.
• On Linux, confirm that the distribution is supported, Python is installed, and the file system that contains /opt/microsoft/mdatp isn't mounted with noexec.
• Review Group Policy and third-party antimalware configuration to confirm that Microsoft Defender Antivirus and the Early Launch Antimalware (ELAM) driver aren't disabled.

For a complete connectivity and sensor-readiness assessment, run the Microsoft Defender for Endpoint Client Analyzer. The analyzer tests the service endpoints and collects diagnostics in the same security context used by the sensor.

Collect Windows readiness information

The following read-only PowerShell script collects information that is commonly needed when you investigate a deployment failure. It doesn't modify the server and doesn't replace the supported operating-system check or the Client Analyzer.

$os = Get-CimInstance Win32_OperatingSystem
$disk = Get-CimInstance Win32_LogicalDisk -Filter "DeviceID='$($env:SystemDrive)'"
$himds = Get-Service -Name himds -ErrorAction SilentlyContinue
$senseService = Get-Service -Name Sense -ErrorAction SilentlyContinue
$defenderService = Get-Service -Name WinDefend -ErrorAction SilentlyContinue

[pscustomobject]@{
    ComputerName             = $env:COMPUTERNAME
    OperatingSystem          = $os.Caption
    OSVersion                = $os.Version
    SystemDriveFreeGB        = [math]::Round($disk.FreeSpace / 1GB, 2)
    AzureArcAgent            = if ($himds) { $himds.Status } else { 'Not installed' }
    SenseService             = if ($senseService) { $senseService.Status } else { 'Not present' }
    DefenderAntivirusService = if ($defenderService) { $defenderService.Status } else { 'Not present' }
    PowerShellVersion        = $PSVersionTable.PSVersion.ToString()
}

Interpret the output against the linked platform requirements. A stopped or missing service isn't, by itself, proof of the root cause because the expected service state depends on the operating system and deployment stage.

Collect Linux readiness information

Run these commands to collect Linux prerequisites and health information:

cat /etc/os-release
python3 --version
findmnt -no TARGET,OPTIONS /
findmnt -T /opt -o TARGET,OPTIONS
azcmagent show
mdatp health

If Defender for Endpoint isn't installed yet, the mdatp health command isn't available. Validate the distribution and version against Defender for Endpoint on Linux prerequisites, and use the Client Analyzer after installation to validate connectivity and collect diagnostics.

Deployment and verification by platform

Windows Server 2019 and later

• Enable Defender for Servers Plan 1 or Plan 2.
• Verify endpoint protection is enabled in Environment settings > Endpoint protection.
• Verify the extension state in the Azure portal: VM > Extensions > MDE.Windows > Provisioning succeeded.
• Verify onboarding in the Microsoft Defender portal: Devices > server name.

Windows Server 2016 and Windows Server 2012 R2

• Enable Defender for Servers.
• Keep the operating system and Microsoft Defender Antivirus fully updated.
• After the unified agent is installed, make sure Defender Antivirus Update KB5005292 is approved and applied so that the EDR sensor continues to receive updates.
• Verify the MDE.Windows extension and the device record in the Microsoft Defender portal.

Linux servers

• Validate the supported distribution, Python requirement, file-system mount options, and outbound connectivity before deployment.
• Verify extension state in Azure portal: VM > Extensions > MDE.Linux > Provisioning succeeded.
• Run mdatp health and confirm that healthy and licensed are true.
• If installation fails, follow Troubleshoot installation issues for Defender for Endpoint on Linux and apply a remediation for a similarly worded error only after you confirm the actual failure in the installation or extension logs.

Enable Defender for Endpoint integration on a subscription

When you enable a Defender for Servers plan, Defender for Endpoint integration is enabled by default. If you turn off integration on a subscription, you can manually turn it on again.

To enable Defender for Endpoint integration on a subscription:

1. Sign in to the Azure portal.

2. Go to Microsoft Defender for Cloud > Environment settings.

3. Select the subscription containing the machines on which you want to deploy the Defender for Endpoint integration.

4. Go to Settings and monitoring > Endpoint protection.

5. Toggle Status to On.

   

6. Select Continue.

7. Select Save.

8. The Defender for Endpoint sensor is deployed to supported Windows and Linux machines that meet the prerequisites.

9. Defender for Cloud detects an existing Defender for Endpoint installation and uses it when the device is associated with the same Defender for Endpoint organization (tenant). A device onboarded to another organization isn't automatically reassigned.

Verify installation on Linux machines

To verify Defender for Endpoint sensor installation on a Linux machine:

1. Run the following shell command on each machine: mdatp health. If Microsoft Defender for Endpoint is installed, you see its health status:

   healthy : true

   licensed: true

2. Also, in the Azure portal, you can check that Linux machines have a new Azure extension called MDE.Linux.

Legacy subscriptions (created before spring-2022): Enable Defender for Endpoint unified solution on Windows Server 2016/2012 R2

If you enabled Defender for Servers and turned on Defender for Endpoint integration in a subscription that you created before spring 2022, you might need to manually enable integration of the unified solution for machines running Windows Server 2016 or Windows Server 2012 R2 in the subscription.

1. Sign in to the Azure portal.

2. Go to Microsoft Defender for Cloud > Environment settings.

3. Select the subscription with the Windows machines that you want to receive Defender for Endpoint.

   The status of the Endpoint protection component is Partial, meaning that not all parts of the component are enabled.

4. Select Fix to see the components that aren't enabled.

   

5. Go to Missing components > Unified solution.

6. In Missing components > Unified solution, select Enable to automatically install the Defender for Endpoint agent on Windows Server 2012 R2 and 2016 machines connected to Microsoft Defender for Cloud.

   

7. Select Save.

8. In Settings and monitoring, select Continue.

Defender for Cloud onboards existing and new machines to Defender for Endpoint.

If you're configuring Defender for Endpoint on the first subscription in your tenant, onboarding might take up to 12 hours. For new machines and subscriptions that you create after enabling the integration, onboarding takes up to an hour.

Legacy subscriptions (created before summer-2021): Enable on Linux machines (plan/integration enabled)

If Defender for Servers is already enabled and Defender for Endpoint integration is on in a subscription that existed before summer 2021, you might need to manually enable the integration for Linux machines.

1. Sign in to the Azure portal.

2. Go to Microsoft Defender for Cloud > Environment settings.

3. Select the subscription with the Linux machines that you want to receive Defender for Endpoint.

   The status of the Endpoint protection component is Partial, meaning that not all parts of the component are enabled.

4. Select Fix to see the components that aren't enabled.

   

5. In Missing components > Linux machines, select Enable.

   

6. Select Save to save your settings.

7. In Settings and monitoring, select Continue.

   • Defender for Cloud onboards Linux machines to Defender for Endpoint.
   • Defender for Cloud detects any previous Defender for Endpoint installations on Linux machines and reconfigures them to integrate with Defender for Cloud.
   • If you're configuring Defender for Endpoint on the first subscription in your tenant, onboarding might take up to 12 hours. For new machines created after the integration has been enabled, onboarding takes up to an hour.

8. To verify Defender for Endpoint sensor installation on a Linux machine, run the following shell command on each machine.

   mdatp health

   If Microsoft Defender for Endpoint is installed, you see its health status:

   healthy : true

   licensed: true

9. In the Azure portal, you can check that Linux machines have a new Azure extension called MDE.Linux.

Enable integration with PowerShell in multiple subscriptions

To enable Defender for Servers integration for Linux machines or Windows Server 2012 R2 and 2016 with the Microsoft Defender for Endpoint (MDE) Unified solution on multiple subscriptions, use one of the PowerShell scripts in the Defender for Cloud GitHub repository.

• Use the Enable MDE unified solution script to enable integration with the Defender for Endpoint modern unified solution on Windows Server 2012 R2 or Windows Server 2016.
• Use the Enable MDE integration for Linux script to enable Defender for Endpoint integration on Linux machines.

Manage automatic updates for Linux

In Windows, Defender for Endpoint version updates are provided through continuous knowledge base updates. In Linux, you need to update the Defender for Endpoint package.

• When you use Defender for Servers with the MDE.Linux extension, automatic updates for Microsoft Defender for Endpoint are enabled by default.

• If you want to manage version updates manually, you can disable automatic updates on your machines. To do this, add the following tag for machines onboarded with the MDE.Linux extension.

  • Tag name: ExcludeMdeAutoUpdate
  • Tag value: true

This configuration is supported for Azure VMs and Azure Arc machines, where the MDE.Linux extension initiates autoupdate.

Enable integration at scale

You can enable the Defender for Endpoint integration at scale through the supplied REST API version 2022-05-01. For full details, see the API documentation.

The following example shows the request body for the PUT request that enables Defender for Endpoint integration. This Microsoft.Security/settings resource configuration sets the WDATP setting to enabled, which activates the Defender for Endpoint integration programmatically for the specified subscription.

URI: https://management.azure.com/subscriptions/<subscriptionId>/providers/Microsoft.Security/settings/WDATP?api-version=2022-05-01

{
    "name": "WDATP",
    "type": "Microsoft.Security/settings",
    "kind": "DataExportSettings",
    "properties": {
        "enabled": true
    }
}

Troubleshoot extension deployment

Use the following sequence instead of retrying the deployment without first identifying the failure stage.

Windows diagnostics

• Azure portal: VM > Extensions > MDE.Windows > View detailed status
• Event Viewer: Applications and Services Logs > Microsoft > Windows > Windows Defender
• Extension logs: C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.AzureDefenderForServers.MDE.Windows
• Run the Defender for Endpoint Client Analyzer on Windows.
• For onboarding and sensor errors, use Troubleshoot Defender for Endpoint onboarding issues.

Linux diagnostics

• Azure portal: VM > Extensions > MDE.Linux > View detailed status

• Extension logs: /var/log/azure/Microsoft.Azure.AzureDefenderForServers.MDE.Linux/

• Installation log: /var/log/microsoft/mdatp/install.log

• Installation journal: sudo journalctl --no-pager | grep 'microsoft-mdatp'

• Sensor health: mdatp health

• If the machine is Azure Arc-enabled: azcmagent show

• Diagnostic package: sudo mdatp diagnostic create

• Follow Troubleshoot installation issues for Defender for Endpoint on Linux for dependency, service-account, systemd, SELinux, and noexec issues.

Track Defender for Endpoint deployment status

You can use the Defender for Endpoint deployment status workbook to track the Defender for Endpoint deployment status on your Azure VMs and Azure Arc-enabled VMs. The interactive workbook provides an overview of machines in your environment showing their Defender for Endpoint extension deployment status.

Access the Microsoft Defender portal

To access the Microsoft Defender portal from Defender for Cloud, complete the following steps:

1. Ensure you have the right permissions for portal access.

2. Check whether you have a proxy or firewall that blocks anonymous traffic.

   • The Defender for Endpoint sensor connects from the system context, so you must permit anonymous traffic.
   • To ensure unhindered access to the Microsoft Defender portal, enable access to service URLs in the proxy server.

3. Open the Microsoft Defender portal. Learn about Incidents and alerts in the Microsoft Defender portal.

Run a detection test

To run a detection test, see EDR detection test for verifying device's onboarding and reporting services.

Remove Defender for Endpoint from a machine

To remove the Defender for Endpoint solution from your machines:

1. Sign in to the Azure portal.

2. Go to Microsoft Defender for Cloud > Environment settings, and select the relevant subscription.

3. Go to Settings and monitoring > Endpoint protection.

4. Toggle Endpoint protection to Off.

5. Select Continue.

6. Select Save.

7. Remove the MDE.Windows or MDE.Linux extension from the machine.

8. Offboard the device from the Microsoft Defender for Endpoint service.

Remove Defender for Endpoint integration tags

When you onboard a Windows device through Defender for Cloud, Defender for Endpoint creates registry values related to Defender for Cloud. These registry tags remain on the device after offboarding and don’t affect functionality.

To remove these tags completely, follow these steps. On Linux, the system stores this information internally and doesn't show it in the registry.

1. Select Start, enter regedit, and select Enter to open Registry Editor.

2. In the left pane, go to:

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Advanced Threat Protection\DeviceTags

3. Delete these value names if they exist:

   • AzureResourceId
   • SecurityWorkspaceId
   • SecurityAgentId

Next steps