During the past 5 years I have onboarded a couple of thousand devices into Microsoft Defender for Endpoint and can say that, provided that you done your homework with regards to network connectivity, onboarding devices into Defender for Endpoint usually just works. But as always in IT, there are exceptions.
Should you ever run into an issue with onboarding devices, I recommend checking the guidance provided here: Troubleshoot Microsoft Defender for Endpoint onboarding issues. Now if you have just a couple of devices to manage you will most likely spot any missing device within the Defender for Endpoint management portal, but what If you have several hundred or even thousands of devices, how would you find out that that particular device Computer0073 in Building D1 on the 6th floor isn’t correctly onboarded?
If we take security seriously and apply good IT infrastructure hygiene, we must ensure that every managed device on the network is properly onboarded in Defender for Endpoint.
In this blogpost I will share a solution that we have put together recently to remediate onboarding devices that are managed by Microsoft Endpoint Configuration manager.
When managing devices with Microsoft Endpoint Configuration you are most likely using a Microsoft Defender for Endpoint policy to onboard devices into Microsoft Defender for Endpoint.
Microsoft Endpoint Configuration Manager the pushes down the onboarding policy just like any other configuration baseline and when executed the device is onboarded into Defender for Endpoint. You can verify the state on a client as shown in the example below.
Another way to check the onboarding state is to use CMPivot, run the following query to retrieve the MDE onboarding state.
You also want to check the sate of the services
Now when it comes to onboarding issues, I have seen a couple of situations:
- The Sense service is not running because it is not set to start automatically
- The Sense service is not running, although the service is set to start automatically
On the troubleshooting page mentioned previously, Microsoft describes that this can happen when:
- Onboarding package is deployed to newly built devices
- Sensor does not start because the Out-of-box experience (OOBE) or first user logon has not been completed
- Device is turned off or restarted before the end user performs a first logon
- In this scenario, the SENSE service will not start automatically even though onboarding package was deployed
Sometimes just restarting the service works, another option is to just rerun the ConfigMgr compliance evaluation on the client either locally or by invoking the compliance evaluation remotely. But I have also seen devices where the onboarding policy on the device was broken.
When all of the above does not work, the final action that in most cases will always solve these issues is to re-run the onboarding script manually. But again, with hundreds or thousands of clients to manage you do not want to rely on a manual task, what we need is automation.
With Microsoft Endpoint Configuration manager, you have several options to identify systems that are not onboarded in Defender for Endpoint. When using manually created collections you will need to create two collections, one that has all the devices where the onboarding state value is set to 1 and another collection that excludes the collection with onboarding devices. This is because when the device is not onboarded there is no onboarding state attribute in the device’s inventory.
Below is the collection query for devices that are onboarded
Great we now have visibility on devices that are not onboarded into defender for endpoint, so let us move on. To re-run the onboarding script on devices that have onboarding issues, we leverage the capability of the Microsoft Endpoint Configuration Manager compliance baselines.
My first idea was to simply embed the onboarding file , which is a batch script into a configuration item, but that turned out to be a cumbersome approach , so my colleague Athi (@AKugaseelan) came up with the idea to convert the onboarding script into a base64 string that we then embed into the remediation script.
To convert the onboarding file into the base64 string, download the onboarding file form the Defender for Endpoint portal. Here make sure to select the Group Policy version , because that script does not have a prompt to confirm the script execution. Once downloaded extract the script from the ZIP file.
Next adjust the helper script $onbaordingScript variable and then run it.
Open the generated mdeonboardbase64.txt and copy the content into the clipboard
Next, open the script CI_DefenderOnboarding_Remediation.ps1
And then copy the previously generated base64 string into the script.
Now that we have the remediation script ready for our configuration item, we need to get it into Microsoft Endpoint Configuration Manager. You can create the CI manually and import the script or use the New-CMCIDefenderOnboarding_Remediation.ps1 script that I include in the source code that will create the CI for you.
The CI has two scripts embedded.
- CI_DefenderOnboarding_Discovery.ps1
- CI_DefenderOnboarding_Remediation.ps1
The CI_DefenderOnboarding_Discovery.ps1 script simply checks the onboarding status by querying the appropriate registry key.
The CI_DefenderOnboarding_Remediation.ps1 script does the following:
- Write the base64 encoded string that contains the content of the DefenderATPOnboardingscript.cmd to a temporary location
- Executes the script
- Removes the temporary script
- Checks the onboarding state by querying the appropriate registry key
The CI is now in the Console so we can continue creating the configuration baseline.
When created, we deploy the configuration baseline to our collection that contains devices ‘not onboarded’ into defender for endpoint.
On the client we see that the device is not onboarded and the configuration baseline hasn’t run yet.
And as soon as the CI is triggered the device is successfully onboarded.
And after a while we have our client back under control.
That is it for today, hope you found this useful and will help you with getting devices successfully onboarded into Defender for Endpoint. You find all the scripts referenced I this blog post in my GitHub repository here: https://github.com/alexverboon/PowerShellCode/tree/main/DefenderforEndpoint/Onboarding
Hi, I have tried to follow the instructions in this guide but have not managed to get very far.
Where you state ‘Next adjust the helper script $onbaordingScript variable and then run it.’ is that meant to be a miss-spelling of the word ‘onboarding’??
when you state ‘helper script’, what is this?!
I did find the variable listed in the ‘Convert-MDEOnboardingBase64.ps1’ file, but the format of the file does not look like your image above. Anyway, I tried modifying the path as noted and then ran the file but it seems to be full of syntax errors and so fails.
Please explain where I am going wrong!!
Many thanks.
Hello Gareth,
Let’s do this step by step, you have downloaded the Windows 10 onboarding script from the MDE portal right? Then you save the onboarding script in a local folder , let’s say C:\Data\mde\onboarding\WindowsDefenderATPOnboardingScript.cmd
Note! Please make sure to download the GPO version of the onboarding script , since this one doesn’t prompt you to proceed, whereas the local script does prompt you.
Then run the following in PowerShell:
$onboardingscript = “C:\Data\mde\onboarding\WindowsDefenderATPOnboardingScript.cmd”
$rawContent = Get-Content $onboardingscript -Raw -Encoding UTF8
$utf8ByteArray = [System.Text.Encoding]::UTF8.GetBytes($rawContent)
$base64OnBoardingString = [System.Convert]:: ToBase64String($utf8ByteArray)
$base64OnBoardingString | out-file -FilePath “C:\Data\mde\mdeonboardbase64.txt” -encoding utf8
Source here: https://github.com/alexverboon/PowerShellCode/blob/main/DefenderforEndpoint/Onboarding/Convert-MDEOnboardingBase64.ps1
let me know if that worked please and then we take it from there.
Hi Alex,
All sorted now, it was the way I was downloading the scripts that was the issue.
All added to sccm and working as expected.
Thanks for your prompt response.