Daily Defender News
Aboutmerill.net
Microsoft Defender for Endpoint
Endpoint protection

Microsoft Defender for Endpoint plug-in for Windows Subsystem for Linux (WSL)

4 September 2026Public preview+85 / −64 lines

In brief

The article now documents WSL container (WSLc) support, including WSL 2.9.5+, compatible plug-in installation, registration, and HealthCheck validation. It also updates the standard installer details, onboarding path, and prerequisites.

What Defender admins need to know

Administrators evaluating WSLc should follow the new prerequisites and installation process; existing WSL 2 deployments should use the updated onboarding details.

Summaries are generated from the documentation change itself.

Documentation change

View full page diffView on Microsoft Learn

The comparison below shows only the changed extract. Use the full-page view for complete context.

Microsoft Defender for Endpoint plug-in for Windows Subsystem for Linux (WSL)

This article explains how to install, configure, and troubleshoot the Microsoft Defender for Endpoint plug-in for Windows Subsystem for Linux (WSL) 2. The plug-in supports both traditional WSL 2 distributions and WSL containers (WSLc) running on supported Windows devices and are onboarded to Microsoft Defender for Endpoint Plan 2.

Overview

Windows Subsystem for Linux (WSL) 2, which replaces the previous version of WSL (supported by Microsoft Defender for Endpoint without a plug-in), provides a Linux environment that is seamlessly integrated with Windows, yet is isolated using virtualization technology. The Microsoft Defender for Endpoint plug-in supports both the traditional WSL 2 Linux distributions and the new WSL containers (WSLc). The Defender for Endpoint for WSL plug-in enables Defender for Endpoint to provide more visibility into all running WSL containers by plugging into the isolated subsystem.

Prerequisites

Before you install the Defender for Endpoint WSL plug-in, make sure the following prerequisites are met:

  • WSL version 2.0.7.0 or later must be running with at least one active distro. Run wsl --update to make sure you are on the latest version. If wsl -–version shows a version older than 2.0.7.0, run wsl --update --pre-release to get the latest update.

  • For WSL containers (WSLc), WSL version 2.9.5 or later is required. WSLc support is currently in Public Preview and requires a supported preview version of the Microsoft Defender for Endpoint plug-in for WSL.

  • The Windows client device must be onboarded to Defender for Endpoint.

Supported operating systems

Be aware of the following considerations before you start:

  • The plug-in doesn't support automatic updates on versions prior to 1.24.522.2. On version 1.24.522.2 and later. Updates are supported through Windows Update across all rings. Updates through Windows Server Update Services (WSUS), System Center Configuration Manager (SCCM), and Microsoft Update catalog are supported only in the Production ring to ensure package stability.

  • It takes a few minutes for the plug-in to fully instantiate, and up to 30 minutes for a WSL2 instance to onboard itself. Short-lived WSL container instances might result in the WSL2 instance not showing up in the Microsoft Defender portal. When any distribution has been running long enough (at least 30 minutes), the WSL2 instance does show up in the Microsoft Defender portal.

  • Running a custom kernel and custom kernel command line is not supported. Although the plug-in does not block running in that configuration, it does not guarantee visibility within WSL when you're running a custom kernel and custom kernel command line. We recommend blocking such configurations with Microsoft Intune wsl settings.

  • The plug-in is not supported on machines with an ARM64 processor.

  • The plug-in is not supported on multi-session variants of Windows 10 and 11.

  • The plug-in provides visibility into events from WSL, but other features like antimalware, threat and vulnerability management, and response commands are not available for the WSL logical device.

  • Detection and alerting behavior can vary between Linux distributions.

Software components and installer file names

Installer: DefenderPlugin-Defenderplugin-x64-0.24.426.1.26.813.1.msi. You can download itthe installer from the onboarding page in the Microsoft Defender portal. (Go to Settings > Endpoints > Onboarding > Windows Subsystem for Linux 2 (plug-in).)

Installation directories:

  • %ProgramFiles%

  • %ProgramData%

Components installed:

  • DefenderforEndpointPlug-in.dll. This DLL is the library to load Defender for Endpoint to work within WSL. You can find it at %ProgramFiles%\Microsoft Defender for Endpoint plug-in for WSL\plug-in.

  • healthcheck.exe. This program checks the health status of Defender for Endpoint and enables you to see the installed versions of WSL, plug-in, and Defender for Endpoint. You can find it at %ProgramFiles%\Microsoft Defender for Endpoint plug-in for WSL\tools.

If your Windows Subsystem for Linux isn't installed yet, follow these steps:

  1. Open Terminal or Command Prompt. (In Windows, go to Start > Command Prompt. Or, right-click the start button and then select Terminal.)

  2. Run the command wsl -–install.

    1. Using Terminal or Command Prompt, run wsl –-update to make sure you have the latest version.

      For WSL containers (WSLc), run wsl --update --pre-release to install the latest WSL preview release required for WSLc functionality.

    2. Run the wsl command to ensure WSL is running before testing.

  3. Install the plug-in by following these steps:

    1. Install the MSI file downloaded from the onboarding section in the Microsoft Defender portal (Settings > Endpoints > Onboarding > Windows Subsystem for Linux 2 (plug-in)).

      For WSL containers (WSLc), install the WSLc-compatible Public Preview version of the Microsoft Defender for Endpoint plug-in.

    2. Open a command prompt/terminal and run wsl.

    You can deploy the package using Microsoft Intune.

Installation validation checklist

Use the following checklist to verify that the plug-in installed correctly and is running as expected:

  1. After update or installation, wait for at least five minutes for the plug-in to fully initialize and write log output.

  2. Open Terminal or Command Prompt. (In Windows, go to Start > Command Prompt. Or, right-click the start button and then select Terminal.)

  3. Run the command: cd "%ProgramFiles%\Microsoft Defender for Endpoint plug-in for WSL\tools".

  4. Run the command .\healthcheck.exe.

    For WSL containers (WSLc), verify that all active WSLc VMs are listed in the HealthCheck output and that each VM reports a healthy Defender status.

  5. Review the details of Defender and WSL and make sure they match or exceed the following requirements:

    • Plug-in Version: 1.24.522.2

If you want to use the host winhttp proxy configuration for MDE for WSL plug-in, nothing more is required. The host WinHTTP proxy configuration is adopted by the plug-in automatically.

If you want to use the host network and network proxy settingnetwork and network proxy setting for MDE for WSL plug-in, nothing more is required. The host network proxy configuration is adopted by the plug-in automatically.

Verifying functionality and SOC analyst experience

After installing the plug-in, the subsystem and all its running containers are onboarded to the Microsoft Defender portal

After installing the plug-in, the subsystem and all its running containers are onboarded to the Microsoft Defender portal.

  1. Sign into the Microsoft Defender portal, and open the Devices view.

    You can see all WSL instances in your environment with an active Defender for Endpoint plug-in for WSL. These instances represent all distributions running inside WSL on a given host. The hostname of a device matches that of the Windows host. However, it's represented as a Linux device.

  2. Open the device page. In the Overview pane, there's athe hosting link for where the device is hosted. The link enables you to understandshows that the device is running on a Windows host. You can thenselect this link to pivot to the Windows host for further investigation and/or response.

    :::image type="content" source="media/mdeplugin-wsl/wsl-ui-overview.png" alt-text="Screenshot showing device overview." lightbox="media/mdeplugin-wsl/wsl-ui-overview.png":::

The timeline is populated, similar to Defender for Endpoint on Linux, with events from inside the subsystem (file, process, network). You can observe activity and detections in the timeline view. Alerts and incidents are generated as appropriate as well.

Setting up custom tag for your WSL machine

The plug-in onboards the WSL machine with the tag WSL2. ShouldIf you or your organization need a custom tag, please follow thethese steps outlined below:to configure one:

  1. Open Registry Editor as an administrator.

    1. Run the wsl command.

  2. Wait for 5-10 minutes for the portal to reflect the changes.

Test the plug-in

Use advanced hunting to investigate WSL devices

The Advanced Hunting experience is identical for WSL 2 and WSL container workloads. Existing queries continue to work without modification.

In the Advanced Hunting schema, under the DeviceInfo table, there's a new attribute called HostDeviceId that you can use to map a WSL instance to its Windows host device. Here are a few sample hunting queries:

Get all WSL device IDs for the current organization/tenant

Use the following query to list all WSL device IDs in your tenant: 

//Get all WSL device ids for the current organization/tenant
let wsl_endpoints = DeviceInfo
| where OSPlatform == "Linux" and isnotempty(HostDeviceId)
| distinct DeviceId;
wsl_endpoints

Use the following query to map each WSL device ID to its corresponding Windows host device ID: 

//Get WSL device ids and their corresponding host device ids
DeviceInfo
| where OSPlatform == "Linux" and isnotempty(HostDeviceId)
| distinct WSLDeviceId=DeviceId, HostDeviceId

//Get a list of WSL device ids where curl or wget was run
let wsl_endpoints = DeviceInfo
| where OSPlatform == "Linux" and isnotempty(HostDeviceId)
| distinct DeviceId;
DeviceProcessEvents
| where FileName == "curl" or FileName == "wget"
| where DeviceId in (wsl_endpoints)
| sort by Timestamp desc

Troubleshooting

[!NOTE] For troubleshooting related to WSLc, check this section.

Use the following troubleshooting steps to diagnose and resolve common issues with the Defender for Endpoint WSL plug-in.

Installation failure

If you see this message, start a WSL distribution and wait before rerunning the health check:

:::image type="content" source="media/mdeplugin-wsl/wsl-health-check.png" alt-text="Screenshot showing PowerShell output." lightbox="media/mdeplugin-wsl/wsl-health-check.png":::

  1. Open a terminal instance and run the command wsl.

  2. Wait for at least five minutes before rerunning the health check. You might see the following message while telemetry is still initializing:

:::image type="content" source="media/mdeplugin-wsl/wsl-health-check-telemetry.png" alt-text="Screenshot showing health telemetry status." lightbox="media/mdeplugin-wsl/wsl-health-check-telemetry.png":::

If the "Waiting for Telemetry" message occurs, wait for five minutes and rerun healthcheck.exe.

You don't see any devices in the Microsoft Defender portal, or you don't see any events in the timeline

Check the following things:

  • If you aren't seeing a machine object, make sure sufficient time has passed for onboarding to complete (typically up to 10 minutes).

  • Make sure to use the right filters, and that you have the appropriate permissions assigned to view all device objects. (For example, is your account/group is restricted to a specific group?)

  • Use the health check tool to provide an overview of overall plug-in health. Open Terminal, and run the healthcheck.exe tool from %ProgramFiles%\Microsoft Defender for Endpoint plug-in for WSL\tools.

    :::image type="content" source="media/mdeplugin-wsl/wsl-health-check-support.png" alt-text="Screenshot showing status in PowerShell." lightbox="media/mdeplugin-wsl/wsl-health-check-support.png":::

  • Enable the connectivity test and check for Defender for Endpoint connectivity in WSL. If the connectivity test fails, provide the output of the health check tool to our support team.

Connectivity test reports "invalid" in health check

  • If your machine has a proxy setup, run the command healthCheck --extendedProxy. This will provide information on which proxy(s) is set on your machine and whether these configurations are invalid for WSL defender.

    Screenshot of the healthCheck --extendedProxy command output showing proxy configurations detected on the machine for the WSL Defender plug-in.

  • If running healthCheck --extendedProxy does not resolve the issue,connectivity test failure, include the following configuration settings in the .wslconfig file located in your %UserProfile% and restart WSL. Details about settings can be found in WSL Settings.

    In Windows 11

    Add the following settings to your .wslconfig file to enable DNS tunneling and mirrored networking:

    
# Settings apply across all Linux distros running on WSL 2
[wsl2]

dnsTunneling=true

networkingMode=mirrored

    In Windows 10

    Add the following setting to your .wslconfig file to disable the DNS proxy: 

    # Settings apply across all Linux distros running on WSL 2
[wsl2]

dnsProxy=false

Connectivity issues persist

  1. Download and run: .\collect-networking-logs.ps1 

    Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/WSL/master/diagnostics/collect-networking-logs.ps1" -OutFile collect-networking-logs.ps1
Set-ExecutionPolicy Bypass -Scope Process -Force
.\collect-networking-logs.ps1

  2. Open a new command prompt and run the following command: wsl.

  3. Open an elevated(admin) command prompt and run the following command: wsl --debug-shell.

  4. In debug shell, run: mdatp connectivity test.

  5. Allow the connectivity test to be completed.

  6. Stop the .ps1 ran in step #2.

  7. Share the generated .zip file along with a support bundle collected by running healthcheck.exe --supportBundle from %ProgramFiles%\Microsoft Defender for Endpoint plug-in for WSL\tools.

To collect diagnostic information for support, generate a support bundle using the following steps:

  1. If you run into any other challenges or issues, open Terminal,Terminal. First, navigate to the Defender for Endpoint WSL plug-in tools directory, and then run the following commandshealthcheck.exe tool to generate a support bundle: 

    cd "%ProgramFiles%\Microsoft Defender for Endpoint plug-in for WSL\tools"

    Then, run the following command to generate a support bundle that collects diagnostic information for troubleshooting: 

    .\healthcheck.exe --supportBundle

    The support bundle can be found in the path provided by the previous command.

  2. Set the Allow WSL1 setting to Disabled, to ensure that only WSL 2 distributions can be used.

    Alternately, if you want to keep using WSL 1, or not use the Intune Policy, you can selectively associate yourupgrade a specific installed distributionsdistribution from WSL 1 to run on WSL 2,2 by running the following command in PowerShell: 

    wsl --set-version <YourDistroName> 2

    To haveensure that all future distributions are created with WSL 2 as your default WSL version for new distributions to be installed in the system,by default, run the following command in PowerShell:PowerShell to set WSL 2 as the default version: 

    wsl --set-default-version 2

Override Releasethe release ring for the WSL plug-in

You can override the default release ring for the plug-in by configuring a registry setting.

  • The plug-in uses the Windows EDR ring by default. If you wish to switch to an earlier ring, set OverrideReleaseRing to one of the following under registry and restart WSL:

    • Name: OverrideReleaseRing
    • Type: REG_SZ
    • Value: Dogfood or External or InsiderFast or Production
    • Path: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft Defender for Endpoint plug-in for WSL