Run the client analyzer on Linux

If you have issues with Microsoft Defender for Endpoint on Linux and need support, you might be asked to provide the output from the Client Analyzer tool. It's a diagnostic tool that helps administrators and support teams troubleshoot issues with Microsoft Defender for Endpoint. It collects detailed information about installation, configuration, service health, logs, connectivity status, etc. This tool is primarily used for checking system health, validating configurations, and helping troubleshoot potential issues.

You can collect Client Analyzer diagnostics in any of the following ways:

1. Command line: Run the Client Analyzer locally on the device. See run-the-binary-version-of-the-client-analyzer or run-the-python-based-client-analyzer.

2. Live response: Run the Client Analyzer remotely during a live response session. See use-live-response-to-collect-diagnostics-log

3. Investigation package: Collect an investigation package from the device page in the Microsoft Defender portal. On Linux, the package includes Client Analyzer diagnostics. See collect-investigation-package-from-devices

Run the binary version of the client analyzer

The binary version of client analyzer is made available in two ways:

• Shipped with Microsoft Defender for Linux
• Shipped as a standalone tool

Run the Client Analyzer binary shipped with Microsoft Defender for Linux:

Running this tool generates a diagnostic package as a .zip file in the /tmp directory.

To run the Client Analyzer, follow these steps:

1. Go to the directory /opt/microsoft/mdatp/tools/client_analyzer/binary:

   cd /opt/microsoft/mdatp/tools/client_analyzer/binary
   

2. Run the tool with root privileges to generate a diagnostic package:

   sudo ./MDESupportTool -d
   

Download and run the Client Analyzer standalone binary tool

To use the standalone ClientAnalyzer binary, complete the following steps.

1. Download the XMDE Client Analyzer Binary tool to the Linux machine that 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=2336125"
   

2. Verify the download:

   echo '5F906591D33D675F14D73D5B658A796CEC7480B023B18D45C5D687713A4D4FBB XMDEClientAnalyzerBinary.zip' | sha256sum -c
   

3. Extract the contents of XMDEClientAnalyzerBinary.zip on the machine.

   unzip -q XMDEClientAnalyzerBinary.zip -d XMDEClientAnalyzerBinary
   

4. Change the directory:

   cd XMDEClientAnalyzerBinary
   

5. Two new zip files are produced:

   • SupportToolLinuxamd64Binary.zip: For x86 Linux devices
   • SupportToolLinuxarm64Binary.zip: For ARM Linux devices

6. Unzip the specific zip based on your Linux OS architecture. For example, we use here the SupportToolLinuxamd64Binary.zip file.

   unzip -q SupportToolLinuxamd64Binary.zip
   

7. Run the tool with root privileges to generate a diagnostic package:

   sudo ./MDESupportTool -d
   

Run the Python-based client analyzer

The python version of client analyzer is made available in two ways:

• Shipped with Microsoft Defender for Linux
• Shipped as a standalone tool

Run Client Analyzer python version shipped with Microsoft Defender for Linux

To run this client analyzer, follow these steps:

1. Go to directory /opt/microsoft/mdatp/tools/client_analyzer/python:

   cd /opt/microsoft/mdatp/tools/client_analyzer/python
   

2. Run with root privileges to install required dependencies.

   sudo ./mde_support_tool.sh
   

3. To collect the diagnostic package and generate the result archive file, run again with root privileges.

   sudo ./mde_support_tool.sh -d
   

Download and run the Client Analyzer standalone python version

1. Download the XMDE Client Analyzer tool on the Linux machine you need to investigate. If you're using a terminal, download the tool by entering the following command:

   wget --quiet -O XMDEClientAnalyzerPython.zip "https://go.microsoft.com/fwlink/?linkid=2336046"
   

2. Verify the download:

   echo '0B7C350A1C19E049416B1C8FB7ED857569DDCC32FB90453A3FCCD083487C0B4E XMDEClientAnalyzerPython.zip' | sha256sum -c
   

3. Extract the contents of XMDEClientAnalyzer.zip on the machine:

   unzip -q XMDEClientAnalyzerPython.zip -d XMDEClientAnalyzerPython
   

4. Change the directory:

   cd XMDEClientAnalyzerPython
   

5. Give the tool executable permission:

   chmod a+x mde_support_tool.sh
   

6. Run as a nonroot user to install required dependencies:

   ./mde_support_tool.sh
   

7. To collect the diagnostic package and generate the result archive file, run again with root privileges:

   sudo ./mde_support_tool.sh -d
   

Command line options

The client analyzer provides the following command-line options:

usage: MDESupportTool [-h] [--output OUTPUT] [--outdir OUTDIR] [--no-zip]
                      [--force] [--diagnostic] [--skip-mdatp]
                      [--bypass-disclaimer] [--interactive] [--delay DELAY]
                      [--mdatp-log {trace,info,warning,error,debug,verbose}]
                      [--max-log-size MAX_LOG_SIZE]
                      {certinfocollection,performance,installation,exclude,ratelimit,skipfaultyrules,trace,observespikes,connectivitytest}
                      ...

MDE Diagnostics Tool

positional arguments:
  {certinfocollection,performance,installation,exclude,ratelimit,skipfaultyrules,trace,observespikes,connectivitytest}
    certinfocollection  Collect cert information: Subject name and Hashes
    performance         Collect extensive machine performance tracing for
                        analysis of a performance scenario that can be
                        reproduced on demand
    installation        Collect different installation/onboarding reports
    exclude             Exclude specific processes from audit-d monitoring.
    ratelimit           Set the rate limit for auditd events. Rate limit will
                        update the limits for auditd events for all the
                        applications using auditd, which could impact
                        applications other than MDE.
    skipfaultyrules     Continue loading rules in spite of an error. This
                        summarizes the results of loading the rules. The exit
                        code will not be success if any rule fails to load.
    trace               Use OS tracing facilities to record Defender
                        performance traces.
    observespikes       Collect the process logs in case of spike or mdatp
                        crash
    connectivitytest    Perform connectivity test for MDE

optional arguments:
  -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.
  --skip-mdatp          Skip any mdatp command. Use this when the mdatp
                        command is unresponsive.
  --bypass-disclaimer   Do not display disclaimer banner.
  --interactive, -i     Interactive diagnostic,
  --delay DELAY, -dd DELAY
                        Delay diagnostic by how many minutes (0~2880), use
                        this to wait for more debug logs before it collects.
  --mdatp-log {trace,info,warning,error,debug,verbose}
                        Set MDATP log level. If you use interactive or delay
                        mode, the log level will set to debug automatically,
                        and reset after 48h.
  --max-log-size MAX_LOG_SIZE
                        Maximum log file size in MB before rotating(Will
                        restart mdatp).

Diagnostics mode

Diagnostics mode is used to collect extensive set of machine information, such as memory, disk, and MDATP logs. This set of files gives the primary set of information required to debug any issue related to Defender For Endpoint.

The options supported are as follows:

optional arguments:
  -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.
  --skip-mdatp          Skip any mdatp command. Use this when the mdatp
                        command is unresponsive.
  --bypass-disclaimer   Do not display disclaimer banner.
  --interactive, -i     Interactive diagnostic,
  --delay DELAY, -dd DELAY
                        Delay diagnostic by how many minutes (0~2880), use
                        this to wait for more debug logs before it collects.
  --mdatp-log {trace,info,warning,error,debug,verbose}
                        Set MDATP log level. If you use interactive or delay
                        mode, the log level will set to debug automatically,
                        and reset after 48h.
  --max-log-size MAX_LOG_SIZE
                        Maximum log file size in MB before rotating(Will
                        restart mdatp).

Usage example: sudo ./MDESupportTool -d

The files generated when using this mode are summarized in the following table:

Optional arguments for Client Analyzer

Client Analyzer provides the following optional arguments for extra data collection:

Collect performance info

Collect extensive machine performance tracing of Defender for Endpoint processes 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 500

This mode generates the following file:

The tar contains files in the format <pid of a MDE process>.data. The data file can be read using the command:

perf report -i <pid>.data

Run connectivity test

This mode tests if the cloud resources needed by Defender for Endpoint are reachable or not.

  -h, --help            show this help message and exit
  -o ONBOARDING_SCRIPT, --onboarding-script ONBOARDING_SCRIPT
                        Path to onboarding script
  -g GEO, --geo GEO     Geo string to test <US|UK|EU|AU|CH|IN>

Usage example:

sudo ./MDESupportTool connectivitytest -o ~/MicrosoftDefenderATPOnboardingLinuxServer.py`

The output printed on the screen shows if the URLs are reachable or not.

Collect different installation/onboarding reports

This mode collects installation related information like distro and system requirements.

  -h, --help                show this help message and exit
  -d, --distro              Check for distro support
  -m, --min-requirement     Check for the system info against offical minimum requirements
  -e, --external-dep        Check for externel package dependency
  -c, --connectivity        Check for connectivity for services used by MDE
  -a, --all                 Run all checks
  -o ONBOARDING_SCRIPT, --onboarding-script ONBOARDING_SCRIPT
                            Path to onboarding script
  -g GEO, --geo GEO         Geo string to test <US|UK|EU|AU|CH|IN>

Usage example:

sudo ./MDESupportTool installation --all

A single report installation_report.json is generated. The keys in the file are as follows:

Exclude mode

This mode adds exclusions for audit-d monitoring.

  -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`

Use live response in Defender for Endpoint to collect support logs

The Client Analyzer can be run during a Live Response session either by using the version that is already included with Microsoft Defender for Endpoint on Linux, or by downloading the Client Analyzer as a binary or Python package and extracting it on the device.

• For installation, the unzip package is required.
• For execution, the acl package is required.

Defender for Endpoint on Linux troubleshooting documents

• Client analyzer overview

• Data collection for advanced troubleshooting on Windows

• Understand the analyzer HTML report

• Troubleshoot installation issues for Microsoft Defender for Endpoint on Linux

• Investigate agent health issues

• Troubleshoot cloud connectivity issues for Microsoft Defender for Endpoint on Linux

• Troubleshoot performance issues for Microsoft Defender for Endpoint on Linux

• Troubleshoot missing events or alerts issues for Microsoft Defender for Endpoint on Linux

• Address false positives/negatives in Microsoft Defender for Endpoint