Onboard Windows devices using a local script

Applies to:

• Microsoft Defender for Endpoint Plan 1 and Plan 2
• Microsoft Defender for Endpoint for servers
• Microsoft Defender for Servers Plan 1 or Plan 2

Want to experience Defender for Endpoint? Sign up for a free trial.

You can also manually onboard individual devices to Defender for Endpoint. You might want to onboard some devices when you're testing the service before you commit to onboarding all devices in your network.

Check out Identify Defender for Endpoint architecture and deployment method to see the various paths in deploying Defender for Endpoint.

1. Open the configuration package .zip file (WindowsDefenderATPOnboardingPackage.zip) that you downloaded from the service onboarding wizard. You can also get the package from the Microsoft Defender portal:

   1. In the navigation pane, select Settings > Endpoints > Device management > Onboarding.

   2. Select Windows 10 or Windows 11 as the operating system.

   3. In the Deployment method field, select Local Script.

   4. Select Download package and save the .zip file.

2. Extract the contents of the configuration package to a location on the device you want to onboard (for example, the Desktop). You should have a file named WindowsDefenderATPLocalOnboardingScript.cmd.

3. Open an elevated command-line prompt on the device and run the script:

   1. Go to Start and type cmd.

   2. Right-click Command prompt and select Run as administrator.

   

4. Type the location of the script file. If you copied the file to the desktop, type: %userprofile%\Desktop\WindowsDefenderATPLocalOnboardingScript.cmd

5. Press the Enter key or select OK.

6. Type "Y" and enter when prompted.

7. After the script completes, it will display "Press any key to continue...". Press any key to complete the steps on the device.

For information on how you can manually validate that the device is compliant and correctly reports sensor data see, Troubleshoot Microsoft Defender for Endpoint onboarding issues.

For each device, you can set a configuration value to state whether samples can be collected from the device when a request is made through Microsoft Defender XDR to submit a file for deep analysis.

You can manually configure the sample sharing setting on the device by using regedit or creating and running a .reg file.

The configuration is set through the following registry key entry:

Path: "HKLM\SOFTWARE\Policies\Microsoft\Windows Advanced Threat Protection"
Name: "AllowSampleCollection"
Value: 0 or 1

Where Name type is a D-WORD. Possible values are:

• 0 - doesn't allow sample sharing from this device
• 1 - allows sharing of all file types from this device

The default value in case the registry key doesn't exist is 1.

After onboarding the device, you can choose to run a detection test to verify that a device is properly onboarded to the service. For more information, see Run a detection test on a newly onboarded Microsoft Defender for Endpoint device.

For security reasons, the package used to offboard devices expires seven days after the date it was downloaded. Expired offboarding packages sent to a device are rejected. When downloading an offboarding package, you're notified of the package's expiry date, and that date is included in the package file name.

1. Get the offboarding package from the Microsoft Defender portal:

   1. In the navigation pane, select Settings > Endpoints > Device management > Offboarding.

   2. Select Windows 10 or Windows 11 as the operating system.

   3. In the Deployment method field, select Local Script.

   4. Select Download package and save the .zip file.

2. Extract the contents of the .zip file to a shared, read-only location that devices can access. You should have a file named WindowsDefenderATPOffboardingScript_valid_until_YYYY-MM-DD.cmd.

3. Open an elevated command-line prompt on the device and run the script:

   1. Go to Start and type cmd.

   2. Right-click Command prompt and select Run as administrator.

      

4. Type the location of the script file. If you copied the file to the desktop, type: %userprofile%\Desktop\WindowsDefenderATPOffboardingScript_valid_until_YYYY-MM-DD.cmd

5. Press the Enter key or select OK.

You can follow the different verification steps in the Troubleshoot onboarding issues to verify that the script completed successfully and the agent is running.

Monitoring can also be done directly on the portal, or by using the different deployment tools.

1. Go to the Microsoft Defender portal.

2. Select Devices inventory.

3. Verify that devices are appearing.

• Onboard Windows devices using Group Policy
• Onboard Windows devices using Microsoft Endpoint Configuration Manager
• Onboard Windows devices using Mobile Device Management tools
• Onboard non-persistent virtual desktop infrastructure (VDI) devices
• Run a detection test on a newly onboarded Microsoft Defender for Endpoint device
• Troubleshoot Microsoft Defender for Endpoint onboarding issues