Run the client analyzer on macOS and Linux
The XMDEClientAnalyzer is used for diagnosing Microsoft Defender for Endpoint health or reliability issues on onboarded devices running either Linux, or macOS.
There are two ways to run the client analyzer tool:
- Using a binary version (no external Python dependency)
- Using a Python-based solution
Running the binary version of the client analyzer
Download the XMDE Client Analyzer Binary tool to the macOS or Linux machine you need to investigate.
If you're using a terminal, download the tool by entering the following command:wget --quiet -O XMDEClientAnalyzerBinary.zip https://go.microsoft.com/fwlink/?linkid=2297517
Verify the download.
- Linux
echo '2A9BF0A6183831BE43C7BCB7917A40D772D226301B4CDA8EE4F258D00B6E4E97 XMDEClientAnalyzerBinary.zip' | sha256sum -c
- macOS
echo '2A9BF0A6183831BE43C7BCB7917A40D772D226301B4CDA8EE4F258D00B6E4E97 XMDEClientAnalyzerBinary.zip' | shasum -a 256 -c
Extract the contents of XMDEClientAnalyzerBinary.zip on the machine.
If you're using a terminal, extract the files by entering the following command:
unzip -q XMDEClientAnalyzerBinary.zip -d XMDEClientAnalyzerBinary
Change to the tool's directory by entering the following command:
cd XMDEClientAnalyzerBinary
Two new zip files are produced:
- SupportToolLinuxBinary.zip : For all Linux devices
- SupportToolMacOSBinary.zip : For Mac devices
Unzip one of the above 2 zip files based on the machine you need to investigate.
When using a terminal, unzip the file by entering one of the following commands based on OS type:
Linux
unzip -q SupportToolLinuxBinary.zip
Mac
unzip -q SupportToolMacOSBinary.zip
Run the tool as root to generate diagnostic package:
sudo ./MDESupportTool -d
Running the Python-based client analyzer
Note
- The analyzer depends on few extra PIP packages (
decorator
,sh
,distro
,lxml
, andpsutil
) which are installed in the operating system when in root to produce the result output. If not installed, the analyzer attempts to fetch it from the official repository for Python packages. - In addition, the tool currently requires Python version 3 or later to be installed on your device.
- If your device is behind a proxy, then you can simply pass the proxy server as an environment variable to the
mde_support_tool.sh
script. For example:https_proxy=https://myproxy.contoso.com:8080 ./mde_support_tool.sh"
.
Warning
Running the Python-based client analyzer requires the installation of PIP packages which may cause some issues in your environment. To avoid issues from occurring, it is recommended that you install the packages into a user PIP environment.
Download the XMDE Client Analyzer tool to the macOS or Linux machine you need to investigate.
If you're using a terminal, download the tool by running the following command:
wget --quiet -O XMDEClientAnalyzer.zip https://aka.ms/XMDEClientAnalyzer
Verify the download
- Linux
echo '84C9718FF3D29DA0EEE650FB2FC0625549A05CD1228AC253DBB92C8B1D9F1D11 XMDEClientAnalyzer.zip' | sha256sum -c
- macOS
echo '84C9718FF3D29DA0EEE650FB2FC0625549A05CD1228AC253DBB92C8B1D9F1D11 XMDEClientAnalyzer.zip' | shasum -a 256 -c
Extract the contents of XMDEClientAnalyzer.zip on the machine. If you're using a terminal, extract the files by using the following command:
unzip -q XMDEClientAnalyzer.zip -d XMDEClientAnalyzer
Change directory to the extracted location.
cd XMDEClientAnalyzer
Give the tool executable permission:
chmod a+x mde_support_tool.sh
Run as a non-root user to install required dependencies:
./mde_support_tool.sh
To collect actual diagnostic package and generate the result archive file, run again as root:
sudo ./mde_support_tool.sh -d
Command line options
Primary command lines
Use the following command to get the machine diagnostic.
-h, --help show this help message and exit
--output OUTPUT, -o OUTPUT
Output path to export report
--outdir OUTDIR Directory where diagnostics file will be generated
--no-zip, -nz If set a directory will be created instead of an archive file
--force, -f Will overwrite if output directory exists
--diagnostic, -d Collect extensive machine diagnostic information
--bypass-disclaimer Do not display disclaimer banner
--interactive, -i Interactive diagnostic
--delay DELAY, -dd DELAY
Set MDATP log level. If you use interactive or delay mode, the log level will set to debug automatically, and reset after 48h.
--mdatp-log {info,debug,verbose,error,trace,warning}
Set MDATP log level
--max-log-size MAX_LOG_SIZE
Maximum log file size in MB before rotating(Will restart mdatp)
Usage example: sudo ./MDESupportTool -d
NOTE: The log level auto-reset feature only available in 2405 or newer client version.
Positional arguments
Collect performance info
Collect extensive machine performance tracing for analysis of a performance scenario that can be reproduced on demand.
-h, --help show this help message and exit
--frequency FREQUENCY
profile at this frequency
--length LENGTH length of time to collect (in seconds)
Usage example: sudo ./MDESupportTool performance --frequency 2
Use OS trace (for macOS only)
Use OS tracing facilities to record Defender for Endpoint performance traces.
Note
This functionality exists in the Python solution only.
-h, --help show this help message and exit
--length LENGTH Length of time to record the trace (in seconds).
--mask MASK Mask to select with event to trace. Defaults to all
On running this command for the first time, it installs a Profile configuration.
Follow this to approve profile installation: Apple Support Guide.
Usage example ./mde_support_tool.sh trace --length 5
Exclude mode
Add exclusions for audit-d monitoring.
Note
This functionality exists for Linux only.
-h, --help show this help message and exit
-e <executable>, --exe <executable>
exclude by executable name, i.e: bash
-p <process id>, --pid <process id>
exclude by process id, i.e: 911
-d <directory>, --dir <directory>
exclude by target path, i.e: /var/foo/bar
-x <executable> <directory>, --exe_dir <executable> <directory>
exclude by executable path and target path, i.e: /bin/bash /var/foo/bar
-q <q_size>, --queue <q_size>
set dispatcher q_depth size
-r, --remove remove exclusion file
-s, --stat get statistics about common executables
-l, --list list auditd rules
-o, --override Override the existing auditd exclusion rules file for mdatp
-c <syscall number>, --syscall <syscall number>
exclude all process of the given syscall
Usage example: sudo ./MDESupportTool exclude -d /var/foo/bar
AuditD Rate Limiter
Syntax that can be used to limit the number of events being reported by the auditD plugin. This option sets the rate limit globally for AuditD causing a drop in all the audit events. When the limiter is enabled the number of auditd events are limited to 2500 events/sec. This option can be used in cases where we see high CPU usage from AuditD side.
Note
This functionality exists for Linux only.
-h, --help show this help message and exit
-e <true/false>, --enable <true/false> enable/disable the rate limit with default values
Usage example: sudo ./mde_support_tool.sh ratelimit -e true
Note
This functionality should be carefully used as limits the number of events being reported by the auditd subsystem as a whole. This could reduces the number of events for other subscribers as well.
AuditD Skip Faulty Rules
This option enables you to skip the faulty rules added in the auditd rules file while loading them. This option allows the auditd subsystem to continue loading rules even if there's a faulty rule. This option summarizes the results of loading the rules. In the background, this option runs the auditctl with the -c option.
Note
This functionality is only available on Linux.
-h, --help show this help message and exit
-e <true/false>, --enable <true/false> enable/disable the option to skip the faulty rules. In case no argumanet is passed, the option will be true by default.
Usage example: sudo ./mde_support_tool.sh skipfaultyrules -e true
Note
This functionality will be skipping the faulty rules. The faulty rule then needs to be further identified and fixed.
Result package contents on macOS and Linux
report.html
Description: The main HTML output file that contains the findings and guidance from running the client analyzer tool on the device. This file is only generated when running the Python-based version of the client analyzer tool.
mde_diagnostic.zip
Description: Same diagnostic output that gets generated when running mdatp diagnostic create on either macOS or Linux.
mde.xml
Description: XML output that is generated while running and is used to build the html report file.
Processes_information.txt
Description: contains the details of the running Microsoft Defender for Endpoint related processes on the system.
Log.txt
Description: contains the same log messages written on screen during the data collection.
Health.txt
Description: The same basic health output that is shown when running mdatp health command.
Events.xml
Description: Additional XML file used by the analyzer when building the HTML report.
Audited_info.txt
Description: details on audited service and related components for Linux OS.
perf_benchmark.tar.gz
Description: The performance test reports. You'll see this only if you're using the performance parameter.
Tip
Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.