Hello readers!
This is an update from Todd Linke and Curtis Ricard, both Cloud Solution Architects, based in the United States.
We’re excited to write this post because we (well…mostly Todd) wrote a script that was helpful in debugging Windows Defender onboarding issues for a customer we work with. The script was written because the customer was having difficulty understanding why specific devices failed to onboard, and it was helpful in gathering data from multiple devices so that the customer could identify trends, common failures, etc. and address them at greater scale.
The script may be used to capture output results of the Microsoft Defender for Endpoint (MDE) Client Analyzer, as well as some other settings, and upload the results to a Log Analytics workspace in Azure Monitor. This allows for analysis from a central point via the Kusto Query Language (KQL). The script can be found on GitHub – see MDE_Automation.
The script may be executed manually on a single device or deployed with an automation tool such as Microsoft Endpoint Configuration Manager (MECM).
Possible use cases for the script:
- Pre-rollout, to assess readiness
- During rollout, to troubleshoot onboarding
- Post-rollout, to verify the configuration (intended vs actual)
Implementation recommendations for Gather-MDEConfiguration.ps1:
- Follow the MDE_Automation implementation documentation on GitHub to do the initial setup. After setup, be sure to review the sample KQL queries here, too!
- Create a dedicated Log Analytics workspace in Azure Monitor – it’s cleaner than sharing an existing one and will make it easier to find your data.
- Client devices need Internet access to write data to Log Analytics; if clients don’t have Internet access, the data may also be written to a local .xml file.
- To make it easy to execute the Gather-MDEConfiguration.ps1 script manually, or from MECM, modify the MDEClientAnalyzer.cmd file that comes with the Microsoft Defender for Endpoint (MDE) Client Analyzer. Just add the following highlighted lines to the .CMD file in the :MAIN section. Be sure the file name referenced in the script matches the actual file name of the .PS1 script:
The MDEClientAnalyizer.cmd file changes are below in text format as well, so that you may easily copy and paste this to the modified .CMD file:
echo Running Gather-MDEAnalyzerResults.ps1
%precommand% powershell.exe -ExecutionPolicy Bypass "& '%~dp0Gather-MDEAnalyzerResults.ps1' %*"
Running the script Manually on a Single Device:
- After modifying the .CMD file, execute it with administrator rights.
- When not running as the SYSTEM account, the first time the MDE Client Analyzer is run on a device, a EULA prompt will appear and will need to be accepted.
Running the script via MECM:
- Download Client Analyzer
- Copy the modified MDEClientAnalyzer.cmd file and the Gather-MDEAnalyzerResults.ps1 file to the package source location.
- Reminder: you’ll need to input a workspace ID and secret in the .ps1 file to allow access to your log analytics workspace.
- Deployment options:
- Deploy as a package/program:
- Example Package source in MECM, followed by a view of the package source folder and program/command line:
- Deploy as a package/program:
And now a DISCLAIMER from our legal team:
The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages.
Thank you for reading this posting. We hope it will help admins who are deploying MDE to more easily identify root cause of client onboarding challenges!
Other Resources:
