Windows - Security - Windows Defender for Endpoint Onboarding

What the Microsoft Defender for Endpoint onboarding Worklet does

This Automox Worklet™ enrolls Windows endpoints into Microsoft Defender for Endpoint (MDE) machine onboarding from the local-script package Microsoft issues in the Microsoft 365 Defender portal. The Worklet extracts WindowsDefenderATPOnboardingPackage.zip, reads the embedded WindowsDefenderATPOnboardingScript.cmd, and pulls the OnboardingInfo blob the script would otherwise write through a manual run.

The OnboardingInfo value is written to HKLM:\SOFTWARE\Microsoft\Windows Advanced Threat Protection. The Worklet installs the WdBoot.sys Early Launch Anti-Malware (ELAM) certificate so the Defender boot driver is trusted on the next start. It then removes any stale offboarding artifacts from a previous tenant and clears the enterprise authentication proxy keys that block the EDR sensor from reaching securitycenter.windows.com.

Once the registry state is in place, the Worklet calls Get-Service Sense and starts the service if it is stopped. It then polls the OnboardingState property for up to 50 seconds, waiting for the value 1 that confirms the cloud handshake completed. On success, it reloads the Defender engine so policy and exclusions apply immediately, then cleans the extracted payload to keep the disk footprint minimal.

Why onboard Windows endpoints to MDE through Automox

Microsoft Defender for Endpoint is the EDR sensor that powers attack-surface reduction, automated investigation, and the device timeline in the Microsoft 365 Defender portal. An endpoint that is not onboarded is invisible to all of it. The legacy Microsoft Monitoring Agent (MMA) path is now deprecated, and the modern unified solution requires the local-script, MDM, or Intune onboarding packages to land OnboardingInfo on the endpoint and start the Sense service. Re-imaged laptops, newly acquired endpoints, and hosts migrating off MMA all need the same one-time write.

Microsoft Defender for Endpoint enrollment normally relies on a one-off WindowsDefenderATPOnboardingScript.cmd executed by a technician on each host, which is the standard reason MDE coverage stalls in the high 80s. This Worklet carries the onboarding package as a script payload and executes WindowsDefenderATPOnboardingScript.cmd from the Automox agent in SYSTEM context. The MDE deployment turns into an unattended evaluation across every Windows host under management, with the OnboardingState registry value reporting back to confirm enrollment.

How MDE machine onboarding works

1. Evaluation phase: The Worklet reads HKLM:\SOFTWARE\Microsoft\Windows Advanced Threat Protection\Status using Get-ItemPropertyValue and inspects the OnboardingState DWORD. A value of 1 means the endpoint is already onboarded and reporting; the script exits 0 and skips remediation. Any other value, a missing property, or a missing key flags the endpoint as non-compliant. The evaluation re-launches under 64-bit PowerShell when invoked from a 32-bit host. Registry virtualization cannot hide the real status from the 64-bit view.

2. Remediation phase: The Worklet expands WindowsDefenderATPOnboardingPackage.zip to a temp directory and parses WindowsDefenderATPOnboardingScript.cmd to extract the OnboardingInfo value. It writes that blob into HKLM:\SOFTWARE\Microsoft\Windows Advanced Threat Protection, then writes the ELAM root certificate from WdBoot.sys into the system certificate store. It removes the OffboardingInfo property if present, sets DisableEnterpriseAuthProxy to 0, runs Start-Service Sense, and polls OnboardingState every two seconds for up to 50 seconds. On confirmation, it reloads the Defender engine via Update-MpSignature and deletes the extracted payload.

MDE onboarding requirements

• Supported Windows versions: Windows 10 1709 or later, Windows 11, and Windows Server 2016, 2019, 2022, or 2025 with the unified MDE solution enabled (not legacy MMA)

• Microsoft Defender for Endpoint Plan 1 or Plan 2 license, or a Microsoft 365 E5 / E5 Security tenant that grants MDE

• WindowsDefenderATPOnboardingPackage.zip downloaded from the Microsoft 365 Defender portal (Settings → Endpoints → Onboarding → Local Script) and attached to the Worklet as a payload file

• Outbound HTTPS reachability to the Defender for Endpoint service URLs (winatp-gw-*.microsoft.com, *.events.data.microsoft.com, x.cp.wd.microsoft.com) from each endpoint

• Automox agent running in SYSTEM context, which is the default; the script requires administrative privileges to write under HKLM and start Sense

• If endpoints are migrating off MMA, run a Defender for Cloud (Azure Arc) offboarding pass first so the MMA workspace key is removed before this Worklet writes the new OnboardingInfo blob

Expected state after MDE enrollment

On success, HKLM:\SOFTWARE\Microsoft\Windows Advanced Threat Protection\Status\OnboardingState equals 1 and HKLM:\SOFTWARE\Microsoft\Windows Advanced Threat Protection\Status\OrgId carries your tenant identifier. Get-Service Sense returns Status Running and StartType Automatic. The endpoint appears in security.microsoft.com under Assets → Devices within 5 to 30 minutes. Health state reads Active and Sensor data reads Reporting.

Verify from the endpoint by running Get-MpComputerStatus and confirming AMRunningMode is Normal (not Passive or EDR Block). Run the Microsoft detection test (Invoke-WebRequest -Uri 'https://winatp-gw-cus.microsoft.com/test') from an elevated PowerShell prompt to generate a benign device-event, then watch the timeline populate in the portal. Subsequent Worklet runs find OnboardingState already set to 1, log the endpoint as compliant, and exit without changes.