Notes for MDE Onboarding and Offboarding

siwei • 2025-06-23 16:05 • 好物分享

While working on MDE, onboarding / offboarding becomes a common topic to discuss with team. This post is to collect all related resources and steps for this topic. Hopefully it can clear out lots of questions you might have.

Onboarding Windows Machines

This workflow is an example using onboarding script to onboard Windows machines. If you are using Arc, it will be different in step 4.

1. Verify AV service installed and running on the machines

sc query windefend
sc qc windefend
hostname

2. Check the registries before onboarding

3. Check the event logs in the sense related folders

sc qc sense
sc query sense

the service is not running and no logs are in sense related folders

4. Run onboarding script

5. verify sense service is running

Offboarding in Windows

You can offboard Windows Server 2012 R2, Windows Server 2016, Windows Server (SAC), Windows Server 2019, Windows Server 2019 Core edition, Windows Server 2022, and Windows Server 2025 (beginning in February 2025 and rolling out over the next several weeks) using the same method available for Windows 10 client devices.

After offboarding, you can proceed to uninstall the unified solution package on Windows Server 2016 and Windows Server 2012 R2.

For other Windows server versions, you have two options to offboard Windows servers from the service:

Uninstall the MMA agent
Remove the Defender for Endpoint workspace configuration

Two different ways exist to offboard devices:

Locally, by running an offboarding script on a device (supported for macOS, Linux, and Windows (Server)).
Through the offboarding API (supported for Windows 10 and Windows Server 2019).

It is important to understand that offboarding a device does not remove a device from the inventory. Instead, the device switches to an ‘inactive’ state 7 days after offboarding. This means that offboarding is not an efficient way to manage reimaged/repurposed devices.

The main goal of offboarding is to sever the connection between Microsoft Defender and the device. This is useful in several scenarios, including:

A device encounters compatibility issues because the scanning process impacts performance and the standard operation of the server or legitimate processes are being blocked
You are moving away from Microsoft Defender to a different EDR solution.
The device is no longer in scope.

The last scenario is something I regularly encounter with customers: by accident, the customer onboarded personal devices into Microsoft Defender for Endpoint due to a misconfiguration. By using the offboarding API, I could block the device from sending data to Microsoft 365 Defender by moving it out of scope for the company. So offboarding devices do have a use case, but it is not a solution for managing inactive devices

check the OnboardingState value in the registry (HKLM/SOFTWARE/Microsoft/Windows Advanced Threat Protection/Status). A value of 0 indicates the device is offboarded, while 1 indicates it's still connected.

Steps:

1 Get offboarding code

2 Run offboarding code from local machine

No need to reboot

3 Verify

1. Check the Registry:
Open Registry Editor (regedit).

Navigate to the following key: HKLM:/Software/Microsoft/Windows Advanced Threat Protection/Status.

Find the OnboardingState value. If it's set to 0, the device is offboarded.
Note: Even registry shows 0, the system might still show onboarded in the Defender portal. (Verifying this)

2. Monitor in the Microsoft Defender Portal:
Go to the Microsoft Defender portal (
https://security.microsoft.com

).

Navigate to Assets > Devices.

Locate the device in the device inventory.

Check the device's status in the flyout panel, which may show "Inactive" or "No sensor data".
3. Offboarding Package Execution:
If you used a local script to offboard the device, ensure that the offboarding package was successfully executed on the device.

You can verify that the MDE agent has been removed by checking if the SENSE service is running (if the service is not running, the agent is gone).
4. Retention Period:
Keep in mind that data from an offboarded device, including alerts and vulnerabilities, is retained in the portal for up to 6 months, says Microsoft.

The device profile will also remain in the device inventory for up to 180 days, says Microsoft.

MDE VDI Deployments

https://learn.microsoft.com/en-us/defender-endpoint/configure-endpoints-vdi

Onboard non-persistent virtual desktop infrastructure (VDI) devices in Microsoft Defender XDR

Open the VDI configuration package 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 the operating system.
3. In the Deployment method field, select VDI onboarding scripts for non-persistent endpoints.
4. Select Download package and save the file.
Copy the files from the WindowsDefenderATPOnboardingPackage folder extracted from the zipped folder into the golden/primary image under the path C:/WINDOWS/System32/GroupPolicy/Machine/Scripts/Startup. (The folder will be generated by local group policy from next step, if the folder is not presented in the system)
- If you're implementing multiple entries for each device - one for each session, copy WindowsDefenderATPOnboardingScript.cmd.
- If you're implementing a single entry for each device, copy both Onboard-NonPersistentMachine.ps1 and WindowsDefenderATPOnboardingScript.cmd.
Open a Local Group Policy Editor window and navigate to Computer Configuration > Windows Settings > Scripts > Startup.

Note

Domain Group Policy may also be used for onboarding non-persistent VDI devices.

Depending on the method you'd like to implement, follow the appropriate steps:

Method	Steps
Single entry for each device	1. Select the PowerShell Scripts tab, then select Add (Windows Explorer opens directly in the path where you copied the onboarding script earlier). 2. Navigate to onboarding PowerShell script `Onboard-NonPersistentMachine.ps1`. There's no need to specify the other file, as it's triggered automatically.
Multiple entries for each device	1. Select the Scripts tab, then select Add (Windows Explorer opens directly in the path where you copied the onboarding script earlier). 2. Navigate to the onboarding bash script `WindowsDefenderATPOnboardingScript.cmd`.

Test your solution

For VDI Master image, it will not be onboarded into MDE portal. To avoid it to be onboarded, following scrip will check the hostname of machines before run VDI start up script.

Write-Host "INFO: Checking hostname against a list of known master images... Please wait..." # Get the current hostname $CURRENT_HOSTNAME = (hostname) # Define the target hostnames $TARGET_HOSTNAMES = @("example1", "example2", "example3", "example4", "MDLT2") Write-Host "INFO: Current hostname is $CURRENT_HOSTNAME" Write-Host "INFO: Target hostnames are $($TARGET_HOSTNAMES -join ', ')" # Initialize a flag to indicate if a match is found $MATCH_FOUND = $false # Check if the current hostname matches any of the target hostnames foreach ($TARGET_HOSTNAME in $TARGET_HOSTNAMES) { if ($CURRENT_HOSTNAME -eq $TARGET_HOSTNAME) { $MATCH_FOUND = $true Write-Host "INFO: Hostname matches one of the target hostnames" Write-Host "WARNING: This machine is a master image... Exiting..." exit } } if (-not $MATCH_FOUND) { Write-Host "INFO: Hostname does not match any of the target hostnames" $script = $PSScriptRoot+"/Onboard-NonPersistentMachine.ps1" & $script } 
For

For Windows 2012 R2 and Windows 2016, the onboarding script for VDI master image will be modified with :

@echo off
echo INFO: Checking hostname against a list of known master images... Please wait...
for /f "tokens=*" %%i in ('hostname') do set CURRENT_HOSTNAME=%%i
set TARGET_HOSTNAMES=example1 exampl2 example3 exampel4
echo INFO: Current hostname is %CURRENT_HOSTNAME%
echo INFO: Target hostnames are %TARGET_HOSTNAMES%
set MATCH_FOUND=false
for %%h in (%TARGET_HOSTNAMES%) do (
if "%CURRENT_HOSTNAME%"=="%%h" (
set MATCH_FOUND=true
echo INFO: Hostname matches one of the target hostnames
echo WARNING: This machine is a master image... Exiting...
exit
)
)

echo This script is for onboarding machines to the Microsoft Defender for Endpoint services, including security and compliance products.

echo Once completed, the machine should light up in the portal within 5-30 minutes, depending on this machine's Internet connectivity availability and machine power state (plugged in vs. battery powered).

echo IMPORTANT: This script is optimized for onboarding a single machine and should not be used for large scale deployment.

echo For more information on large scale deployment, please consult the MDE documentation (links available in the MDE portal under the endpoint onboarding section).

echo.

:USER_CONSENT

...

...(omitted)

Onboarding Linux Servers

1. Get Linux Server Deployment Script from Microsoft Defender - Settings - Endpoints - Device Management - Onboarding

2. Download installation script from Github

wget
https://github.com/microsoft/mdatp-xplat/blob/master/linux/installation/mde_installer.sh
chmod +x mde_
installer.sh

Note:

https://learn.microsoft.com/en-us/defender-endpoint/linux-installer-script

sudo ./mde_
installer.sh

--install --onboard ./MicrosoftDefenderATPOnboardingLinuxServer.py --channel prod --min_req

root@netsec-syslog:/tmp# ./mde_installer.sh
 --install --onboard ./MicrosoftDefenderATPOnboardingLinuxServer.py --channel prod --min_req [i] Specify the version to be installed using --mdatp argument. If not provided, latest mde will be installed by default. --- mde_installer.sh
 v0.8.2 --- [v] minimal requirements met [v] detected: x86_64 architecture [v] detected: ubuntu 24.04 noble (debian) [v] scaled: 24.04 [v] set package manager: apt [i] Found MDE already installed and onboarded with org_id e94278fa-7cfa-4e5c-8c23-4c2e60281d06 and app_version 101.25032.0010. Either try to upgrade/downgrade your MDE version using --upgrade/--downgrade option or Please verify that the onboarded linux server appears in Microsoft 365 Defender. [i] MDE already installed (101.25032.0010) [>] onboarding script: ./MicrosoftDefenderATPOnboardingLinuxServer.py [i] MDE already onboarded [v] --- mde_installer.sh
 ended. --- [*] exiting (0) root@netsec-syslog:/tmp#

Check MDE status on Linux Machine

root@netsec-syslog:/tmp# /tmp# mdatp health healthy : true health_issues : [] licensed : true engine_version : "1.1.25040.4000" engine_load_status : "Engine load succeeded" app_version : "101.25032.0010" org_id : "e94278fa-7cfa-4e5c-8c23-4c2e60281d06" log_level : "info" machine_guid : "20510b42-aecd-8449-e6f8-886e6e5d3463" release_ring : "Production" product_expiration : Feb 10, 2026 at 09:16:13 AM cloud_enabled : true [managed] cloud_automatic_sample_submission_consent : "safe" [managed] cloud_diagnostic_enabled : true [managed] cloud_pin_certificate_thumbs : false passive_mode_enabled : false [managed] behavior_monitoring : "enabled" [managed] real_time_protection_enabled : true [managed] real_time_protection_available : true real_time_protection_subsystem : "fanotify" supplementary_events_subsystem : "ebpf" automatic_definition_update_enabled : true [managed] definitions_updated : Jun 23, 2025 at 10:29:11 AM definitions_updated_minutes_ago : 91 definitions_version : "1.431.168.0" definitions_status : "up_to_date" edr_early_preview_enabled : "disabled" edr_device_tags : [{"key":"AzureResourceId","value":"/subscriptions/a5cf0589-e4e7-40f0-b615-94fa4c6d7158/resourceGroups/RG-ARC-PROD-EASTUS-01/providers/Microsoft.HybridCompute/machines/ehq-syslog"},{"key":"SecurityWorkspaceId","value":"a5cf0589-e4e7-40f0-b615-94fa4c6d7158"}] edr_group_ids : "" edr_configuration_version : "30.199999.main.2025.06.21.01-74039ab26fd123826b7084d7fe9a9145bc801d9a
" edr_machine_id : "756b55f088086942a78ad22c356dffb270abd4ca
" managed_by : "MDE" conflicting_applications : [] network_protection_status : "stopped" network_protection_enforcement_level : "disabled"

Videos

References

版权声明：
作者：siwei
链接：https://www.techfm.club/p/218167.html
来源：TechFM
文章版权归作者所有，未经允许请勿转载。

THE END

二维码

说说阅读

< <上一篇

关系线样式-关系线｜图形天下思维导图样式与风格

下一篇>>

搜索内容