Deploy Microsoft Defender endpoint security to Windows devices using the Defender deployment tool (preview)

The Defender deployment tool is a lightweight, self-updating application designed to streamline onboarding for all Windows versions supported by the Defender endpoint security solution. The tool takes care of prerequisites, automates migrations from older solutions, and removes the need for complex onboarding scripts, separate downloads, and manual installations.

Using the tool's user interface, administrators can double-click the tool and follow an interactive installation and onboarding sequence. For larger deployments, the tool provides automation options with advanced command-line parameters so that you can integrate with orchestration platforms or custom deployment tools, such as Group Policy, while leaving in place the experiences that are provided through other Microsoft solution integrations such as Intune and Defender for Cloud.

The features the tool supports include:

• Prerequisite handling: The tool checks for required updates and remediates blocking issues, ensuring devices are ready for Defender onboarding.

• Logging: All operations are logged locally in a detailed log.

• Redundant installation avoidance: If Defender is already present, the tool skips redundant installations.

• UI feedback: The tool provides UI feedback with error descriptions instead of exit codes.

• Passive mode support: On server operating systems and Windows 7, Defender Antivirus can be set to passive mode. This can be helpful when migrating from non-Microsoft antimalware solutions.

• Automation: The tool supports a wide range of command-line options.

• Device handling: Virtual Desktop Infrastructure (VDI) device support ensures that devices deleted and recreated under the same hostname can appear as a single device in the Defender portal.

• Help: A built-in help function displays all available command-line options.

• Configuration files: You can generate reusable configuration files that make bulk deployments more efficient and less error-prone.

• Working without connectivity: When connectivity is temporarily unavailable, offline onboarding and offboarding is possible.

When the interactive, double-click experience is used, the tool automatically leverages the WindowsDefenderATP.onboarding file in the same directory. It will handle the installation of most prerequisite updates and the latest Defender components, and connect the device to the Defender services. If needed, the tool will ask you to reboot the device to finish installation after you sign in again.

For more advanced and large-scale deployments, the tool offers functionality to perform additional and orchestrated steps through command-line parameters or a configuration file.

To view the complete command reference after downloading the tool, run: DefenderDT.exe -?.

Supported operating systems

The Defender deployment tool supports the following operating systems: Windows 7 SP1, Windows Server 2008 R2 SP1, Windows Server 2012 R2, 2016, 2019, 2022, 2025, Windows 10 (version 1809 and newer), and all versions of Windows 11.

Prerequisites

There are prerequisites that pertain to all supported Windows and Windows Server devices, as well as prerequisites that are specific to Windows 7 SP1 and Windows Server 2008 R2 SP1 devices.

General prerequisites

• Administrative privileges are required for most operations.

• Preview features must be enabled on the tenant.

• Access to the domain definitionupdates.microsoft.com. The tool is downloaded and updated from this domain. Since the files it downloads are hosted on a content distribution platform, there will be no static or predictable IP ranges associated with it – unlike for other Defender cloud services.

• While the tool will check for connectivity against your specific tenant before proceeding, other connectivity requirements, such as access to the consolidated *.endpoint.security.microsoft.com/*, apply to (additional) functionality you might want to use with the product. See Configure your network environment to ensure connectivity with the Defender for Endpoint service.

Additional prerequisites for Windows 7 SP1 and Windows Server 2008 R2 SP1

• Devices must be running an x64 version of Windows 7 SP1 or Windows Server 2008 R2 SP1. We recommend having the latest updates installed to avoid reboots and to significantly reduce required installation time.

• For the Defender deployment tool to run on Windows 7 SP1 or Windows Server 2008 R2 SP1, at a minimum, the update KB4474419 for SHA2 code signing must be installed.

  • Servicing stack update (SSU) (KB4490628). If you use Windows Update, the required SSU will be offered to you automatically.

  • SHA-2 update (KB4474419) released September 10, 2019. If you use Windows Update, the required SHA-2 update will be offered to you automatically.

• On Server 2008 R2 SP1 devices, .NET 3.5 or a higher version of the .NET framework must also be installed.

R2 SP1, at a minimum, the updates for SHA2 code signing must be installed:

Servicing stack update (SSU) (KB4490628). If you use Windows Update, the required SSU will be offered to you automatically.

SHA-2 update (KB4474419) released September 10, 2019. If you use Windows Update, the required SHA-2 update will be offered to you automatically.

Download the tool

1. In the Microsoft Defender portal (security.microsoft.com), go System > Settings > Endpoints > Onboarding.

2. In the Step 1 dropdown menu, choose Windows (preview).

3. Under Deploy by downloading and applying packages or files, select the Download package button. This downloads the Defender executable and the onboarding file package.

   

   Note

   For offboarding, select Offboarding in the Device management section, choose Windows 10 and 11 in the Step 1 dropdown menu, and then select the Download package button. This downloads the offboarding file package only - it doesn't download the Defender deployment tool executable, as that is the same for both onboarding and offboarding.

Deploy Defender endpoint security on devices

The Defender deployment tool can be used interactively or non-interactively.

Interactive use

The tool supports two interactive experiences that are suitable for deployment to one or a limited number of devices - a "double-click" quick single-machine onboarding experience without any changes to default behavior, and a manual command-line experience that provides more flexibility.

To use the quick "double-click" default installation:

1. Double-click the executable to launch it.

2. In the dialog that appears, select Continue.

   

   The tool will look for the WindowsDefenderATP.onboarding file in the directory the tool is being run from and perform default installation and onboarding operations.

Non-interactive use

You can also perform all the installation and onboarding operations manually through the command-line interface. In addition, the command-line interface supports a variety of other operations, such as running prerequisite checks:

To view the complete command reference, run: DefenderDT.exe -?.

Advanced and large-scale deployments

The Defender deployment tool can be used non-interactively as part of an orchestrated sequence run by a management tool, such as Group Policy, Microsoft Configuration Manager, or other tool that your organization uses for software deployments.

For this purpose, the tool provides optional command-line parameters that allow you to customize onboarding operations to support a large variety of scenarios.

For repetitive deployment scenarios in your environment, you can use a configuration file instead of the command line to pass parameters. To generate the configuration file, run the tool with the -makeconfig parameter. After the file is created, open it in a text editor to configure the options to suit your deployment scenario. See the usage example.

Usage examples

The following examples illustrate how to use the tool.

• Run the Defender deployment tool without changing settings and without interacting with it:

  DefenderDT.exe -Quiet
  

• Use a WindowsDefenderATP.onboarding file in the same directory as the tool to run the default onboarding sequence, connect via a proxy, and, if a reboot is required, initiate it without asking. Don't show the console window.

  DefenderDT.exe -Proxy:192.168.0.255:8080 -AllowReboot -Quiet
  

• Use a .onboarding file stored in a network location to perform the onboarding sequence. Don't show the console window.

  DefenderDT.exe -File:\\server\share\Defender.onboarding -Quiet
  

• Perform an offboarding operation. Don't ask for approval. Don't show console window.

  DefenderDT.exe -Offboard -File:c:"\Defender deployment tooltest\WindowsDefenderATPOffboardingScript_valid_until_2025-04-02.offboarding" -YES -Quiet
  

• Perform a prerequisite check and display verbose output without displaying a dialog box.

  DefenderDT.exe -PreCheck -Verbose -Quiet
  

• Download updates and installation files to be used for staging, to the current directory.

  DefenderDT.exe -Stage
  

• Create a configuration file, edit it and then use it to pass multiple parameters to the tool to perform an installation using staged installation files.

  • Step 1: Generate a configuration file

    DefenderDT.exe -makeconfig
    

  • Step 2: Use a text editor such as Notepad to open the MdeConfig.txt file that was created in the directory and specify parameters you wish to use. Sample:

    # Only absolute paths can be used for the parameters accepting paths
    
    # Configures the tool to perform offboarding.
    
    # Add the parameter "YES" to proceed with offboarding without user approval. 
    # Offboard: False 
    
    # Used with "Offboard" and "Uninstall" parameters. 
    # Yes: False 
    
    # Downloads the installation files for all Windows versions supported by the tool to a specific location for staging purposes. 
    # Stage: 
    
    # Specifies the path to the folder containing the installation files. To stage installation files, use the "Stage" parameter. 
    # Source: 
    
    # Specifies the full path to the .onboarding or .offboarding file if it is not placed in the current folder. 
    # File: 
    
    # Proxy to use during and after installation. Empty string by default. 
    Proxy: 
    
    # Prevents any dialogs from displaying. False by default. 
    Quiet: False 
    
    # Allows device reboots if needed. False by default 
    AllowReboot: False 
    
    # Prevents the tool from resuming activities after a reboot. False by default. 
    NoResumeAfterReboot: False 
    
    # Windows Server only. Sets Defender antivirus to run in passive mode. 
    Passive: False 
    
    # Installs updates but does not perform onboarding, even if an onboarding file is present. False by default. 
    UpdateOnly: False 
    
    # Displays detailed information. False by default. 
    Verbose: False 
    
    # Checks for prerequisites and logs results but does not proceed with installation or onboarding. False by default. 
    Precheck: False 
    
    # Offboards the device and uninstalls any components that were added during onboarding. 
    # Will use the .offboarding file in the current folder if no path was specified. 
    # Add the parameter "YES" to proceed without user approval. 
    Uninstall: False 
    
    # Optionally removes the specified workspace connection used by Microsoft Monitoring Agent (MMA). Empty string by default. 
    RemoveMMA: 
    
    # Allows offboarding to proceed even if there is no connectivity. False by default. 
    Offline: False 
    

  • Step 3: Run the tool with the configuration file.

    DefenderDT.exe -File:\\server\DDT\Defenderconfig.txt
    

    If the MdeConfig.txt file is stored in the same directory as the tool, there's no need to specify a path.

Using Group Policy for deployment

The following steps show how to create a scheduled task to run the tool using Group Policy:

1. Place the files DefenderDT.exe and WindowsDefenderATP.onboarding on a shared location that can be accessed by the device. If you've previously created an MDEConfig.txt configuration file, place it in the same location.

2. To create a new Group Policy Object (GPO), open the Group Policy Management Console (GPMC), right-click Group Policy Objects you want to configure and select New. Enter the name of the new GPO in the dialogue box that is displayed and select OK.

3. Open the Group Policy Management Console, right-click the Group Policy Object (GPO) you want to configure and select Edit.

4. In the Group Policy Management Editor, go to Computer configuration > Preferences > Control panel settings.

5. Right-click Scheduled tasks, point to New, and then select Immediate Task (At least Windows 7).

6. In the Task window that opens, go to the General tab.

7. Under Security options select Change User or Group, type SYSTEM, and then select Check Names and select OK. NT AUTHORITY\SYSTEM appears as the user account the task will run as.

8. Select Run whether user is logged on or not and check the Run with highest privileges check box.

9. In the Name field, type an appropriate name for the scheduled task.

10. Go to the Actions tab and select New. Ensure that Start a program is selected in the Action field. Enter the full UNC path, using the file server's fully qualified domain name (FQDN), of the shared DefenderDDT.exe application.

11. In the Add arguments (optional) field, enter the parameters you wish to use. For example, to use an onboarding file that isn't in the working directory of the tool, specify the -file: parameter with the full UNC path to the onboarding file, for example -file: \\server\share\WindowsDefenderATP.onboarding.

12. Select OK and close any open GPMC windows.

13. To link the GPO to an Organization Unit (OU), right-click and select Link an existing GPO. In the dialogue box that is displayed, select the Group Policy Object that you wish to link and select OK.

Considerations and limitations

General considerations and limitations, and additional considerations and limitations specific to Windows 7 SP1 and Windows Server 2008 R2 SP1 devices, are outlined below.

General considerations and limitations

• When you're using the interactive experience, and a reboot is required to complete the sequence, you must sign in again after the reboot to resume. Otherwise the device won't be fully onboarded.

• When the -proxy parameter is used, it only applies to Defender deployment tool operations. Despite the parameter description in the command-line help reference, it doesn't set proxy configuration in registry for Defender endpoint security to use after installation. Note that both the tool and Defender will use whatever proxy has been configured on a system-wide (Windows) level regardless. If you wish to specifically configure a proxy to use for the Defender endpoint security services on the machine (static proxy), and not system-wide, see Configure your devices to connect to the Defender for Endpoint service using a proxy.

• On Windows Server 2016 and later, when the Defender Antivirus feature has been uninstalled or removed, you may encounter an error during the Enabling Feature 'Windows-Defender' step. This can be observed in the user interface, in the local log, under Sequence completion with exit code 710 and the error description EnableFeatureFailed. In the local log you'll also be able to find error 14081 with the description 0x3701 The referenced assembly could not be found. This error is not indicative of an issue with the Defender Antivirus feature or source files, as those would typically be resolved by the onboarding tool. Open a support case for Windows Servers if you encounter this issue.

Known issues and limitations for Windows 7 SP1 and Windows Server 2008 R2 SP1

• You may get alerts about mpclient.dll, mpcommu.dll, mpsvc.dll, msmplics.dll, and sense1ds.dll loaded by either mpcmdrun.exe or mssense.exe. These should resolve over time.

• On Windows 7 SP1 and on Windows Server 2008 R2 SP1 with the Desktop Experience pack installed, you might see a notification from Action Center Windows did not find antivirus software on this computer. This is not indicative of a problem.

• The preview ("beta") version of the client analyzer tool can be used to collect logs and perform connectivity troubleshooting on Windows 7 SP1 and Windows Server 2008 R2 SP1. It requires PowerShell 5.1 or later to be installed.

• There's no local user interface for Antivirus. If you wish to manage Antivirus settings locally using PowerShell, version 5.1 or later is required.

• Configuration via Group Policy is supported using a central store with updated group policy templates on a domain controller. For local group policy configuration, templates (WindowsDefender.admx/WindowsDefender.adml) will need to be manually updated to a newer version (Windows 11) if you wish to use the local group policy editor to apply settings.

• The Defender endpoint security solution will be installed to C:\Program Files\Microsoft Defender for Endpoint

• Windows 7 devices may show up as Server in the portal until you update to the latest Sense version by applying KB5005292.

• You can put Defender Antivirus into passive mode on Windows 7 by passing the -passive parameter to the Defender deployment tool. However, it's currently not possible to switch to active mode afterwards by using the ForceDefenderPassiveMode registry key like on Windows server. To switch to active mode, it's necessary to offboard and uninstall, and then to run the Defender deployment tool again without the passive mode parameter.

Troubleshooting

You can reference the Defender deployment tool log to understand if there were any issues during installation and onboarding. The deployment tool log is located at:

C:\ProgramData\Microsoft\DefenderDeploymentTool\DefenderDeploymentTool-<COMPUTERNAME>.log

Events will also be written to the following Windows event logs:

• Onboarding: Windows Logs > Application > Source: WDATPOnboarding

• Offboarding: Windows Logs > Application > Source: WDATPOffboarding

To test if the installation succeeded successfully, perform the following checks:

1. Check if services are running

   Sc.exe query sense
Sc.exe query windefend

   You should see something similar to the following for both services:

   

2. For detailed log collection for Defender Antivirus, including settings and other information, you can run the following command:

   C:\Program Files\Microsoft Defender for Endpoint\MpCmdRun.exe” -GetFiles -SupportLogLocation <FOLDEROFCHOICE>

   The latest preview version of the client analyzer tool can also be used to collect logs and perform connectivity troubleshooting on Windows 7 SP1 and Windows Server 2008 R2 SP1. It requires PowerShell 5.1 or later to be installed.

Related content

• Deploy the Defender endpoint security solution for Windows 7 SP1 and Windows Server 2008 R2 SP1 devices