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, while providing onboarding visibility, customizability, and guardrails.

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. Currently, the tool is its own onboarding methodology, and doesn't integrate with other onboarding methods.

The following table describes some of the main features the tool supports.

When the interactive, double-click experience is used, the tool automatically begins the onboarding process asks you to input the Defender deployment tool key generated in the portal when you create your Defender deployment tool package in Settings > Endpoints > Onboarding. It handles the installation of most prerequisite updates and the latest Defender components, and connects the device to the Defender services. If needed, the tool asks 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 checks 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 is offered to you automatically.

  • SHA-2 update (KB4474419) released September 10, 2019. If you use Windows Update, the required SHA-2 update is 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 is offered to you automatically.

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

Generate and download a new onboarding package

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 Onboard button.

   

4. The Generate Defender deployment tool with an access key page appears.

   

   • Provide a name for the package. Be sure to create a name that's unique and descriptive.

   • Set an expiration date for the package. You can set the expiration date for any time up to a year. It's recommended to make the validity period of packages as short as possible to reduce the risk of unauthorized deployment package use.

   • When you're done configuring the package, select Generate.

5. When the package is ready, you'll see a page that has the package access key and a download button, similar to the following image.

   

   Copy the key and save it, as it will be needed with the deployment tool.

   After you've copied the key and saved it, select Download deployment tool. This downloads a .zip file of the Defender deployment tool executable.

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. A dialog informs you that onboarding on the device will start. Select Continue.

   

3. Enter the Defender deployment tool key that you copied from the portal, and then select Continue.

   

4. Wait until installation is complete, and then select OK. No device reboot is required.

   

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 various 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 through and configure a proxy to use, 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.

• On Windows Server 2016 and later, when the Defender Antivirus feature has been uninstalled or removed, you might 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 isn't 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 might 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 isn't 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

• 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