Skip to content

Commit 9d2377e

Browse files
denisebmsftdenisebmsft
authored
Merge pull request #1764 from YongRhee-MSFT/docs-editor/run-analyzer-macos-1730332997
Create article run-analyzer-macos
2 parents 375ede2 + c179ea6 commit 9d2377e

File tree

2 files changed

+279
-0
lines changed

2 files changed

+279
-0
lines changed

‎defender-endpoint/TOC.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -481,6 +481,9 @@
481481
href: run-analyzer-windows.md
482482
- name: Run the client analyzer on macOS or Linux
483483
href: run-analyzer-macos-linux.md
484+
- name: Run the client analyzer on macOS
485+
href: run-analyzer-macos.md
486+
displayName: xMDEClientAnalyzer xMDEClientAnalyzerBinary macOS mac
484487
- name: Data collection for advanced troubleshooting on Windows
485488
href: data-collection-analyzer.md
486489
- name: Understand the analyzer HTML report

‎defender-endpoint/run-analyzer-macos.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
---
2+
title: Run the client analyzer on macOS
3+
description: Learn how to use the Defender for Endpoint Client Analyzer on Mac to identify health or performance issue causes.
4+
author: denisebmsft
5+
ms.author: deniseb
6+
manager: deniseb
7+
ms.reviewer: yongrhee
8+
ms.service: defender-endpoint
9+
ms.subservice: macos
10+
ms.localizationpriority: medium
11+
ms.topic: troubleshooting-general
12+
ms.date: 10/31/2024
13+
ms.custom: partner-contribution
14+
ms.collection:
15+
- m365-security
16+
- tier3
17+
- mde-macos
18+
search.appverid: met150
19+
audience: ITPro
20+
f1.keywords: NOCSH
21+
---
22+
23+
# Run the client analyzer on macOS
24+
25+
If you're experiencing reliability or device health issues with Microsoft Defender for Endpoint on macOS, you can use the XMDE Client Analyzer to diagnose these issues. This article describes two ways to use the client analyzer tool:
26+
27+
- [Use the binary version of the client analyzer](#use-the-binary-version-of-the-client-analyzer)
28+
-
29+
30+
1. Using a binary version (no external Python dependency)
31+
2. Using a Python-based solution
32+
33+
## Use the binary version of the client analyzer
34+
35+
1. Download the [XMDE Client Analyzer Binary](https://aka.ms/XMDEClientAnalyzerBinary) tool to the macOS machine you need to investigate.
36+
37+
If you're using a terminal, download the tool by running the following command:
38+
39+
```bash
40+
wget --quiet -O XMDEClientAnalyzerBinary.zip https://aka.ms/XMDEClientAnalyzerBinary
41+
```
42+
43+
2. Verify the download.
44+
45+
```bash
46+
echo '2A9BF0A6183831BE43C7BCB7917A40D772D226301B4CDA8EE4F258D00B6E4E97 XMDEClientAnalyzerBinary.zip' | shasum -a 256 -c
47+
```
48+
49+
2. Extract the contents of `XMDEClientAnalyzerBinary.zip` on the machine.
50+
51+
If you're using a terminal, extract the files by running the following command:
52+
53+
```bash
54+
unzip -q XMDEClientAnalyzerBinary.zip -d XMDEClientAnalyzerBinary
55+
```
56+
57+
3. Change to the tool's directory by running the following command:
58+
59+
```bash
60+
cd XMDEClientAnalyzerBinary
61+
```
62+
63+
4. Notice that the following two zipped files are produced:
64+
65+
- `SupportToolLinuxBinary.zip`: For all Linux devices
66+
- `SupportToolMacOSBinary.zip`: For Mac devices
67+
68+
5. Depending on the machine you're investigating, unzip the appropriate file.
69+
70+
| OS type | Terminal command |
71+
|---|---|
72+
| Linux | `unzip -q SupportToolLinuxBinary.zip` |
73+
| Mac | `unzip -q SupportToolMacOSBinary.zip` |
74+
75+
6. Run the tool as root to generate your diagnostic package:
76+
77+
```bash
78+
sudo ./MDESupportTool -d
79+
```
80+
81+
## Use the Python-based client analyzer
82+
83+
The client analyzer depends on few extra PIP packages (`decorator`, `sh`, `distro`, `lxml`, and `psutil`) that are installed in the operating system when in root mode to produce the result output. If not installed, the analyzer attempts to fetch it from the [official repository for Python packages](https://pypi.org/search/?q=lxml).
84+
85+
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 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"`.
86+
87+
> [!WARNING]
88+
> Running the Python-based client analyzer requires the installation of PIP packages which could cause some issues in your environment. To avoid issues from occurring, it is recommended that you install the packages into a user PIP environment.
89+
90+
1. Download the [XMDE Client Analyzer](https://aka.ms/XMDEClientAnalyzer) tool to the Mac or Linux machine you're investigating.
91+
92+
If you're using a terminal, download the tool by running the following command:
93+
94+
```bash
95+
wget --quiet -O XMDEClientAnalyzer.zip https://aka.ms/XMDEClientAnalyzer
96+
```
97+
98+
2. Verify the download.
99+
100+
| OS | Command |
101+
|--|--|
102+
| Linux | `echo '84C9718FF3D29DA0EEE650FB2FC0625549A05CD1228AC253DBB92C8B1D9F1D11 XMDEClientAnalyzer.zip' | sha256sum -c` |
103+
| macOS | `echo '84C9718FF3D29DA0EEE650FB2FC0625549A05CD1228AC253DBB92C8B1D9F1D11 XMDEClientAnalyzer.zip' | shasum -a 256 -c` |
104+
105+
3. Extract the contents of `XMDEClientAnalyzer.zip` on the machine.
106+
107+
If you're using a terminal, extract the files by using the following command:
108+
109+
```bash
110+
unzip -q XMDEClientAnalyzer.zip -d XMDEClientAnalyzer
111+
```
112+
113+
4. Change directory to the extracted location.
114+
115+
```bash
116+
cd XMDEClientAnalyzer
117+
```
118+
119+
5. Give the tool executable permission:
120+
121+
```bash
122+
chmod a+x mde_support_tool.sh
123+
```
124+
125+
6. Run as a nonroot user to install required dependencies:
126+
127+
```bash
128+
./mde_support_tool.sh
129+
```
130+
131+
7. To collect actual diagnostic package and generate the result archive file, run again as root:
132+
133+
```bash
134+
sudo ./mde_support_tool.sh -d
135+
```
136+
137+
## Command line options
138+
139+
### Primary command lines
140+
141+
Use the following command to get the machine diagnostic.
142+
143+
```console
144+
-h, --help show this help message and exit
145+
--output OUTPUT, -o OUTPUT
146+
Output path to export report
147+
--outdir OUTDIR Directory where diagnostics file will be generated
148+
--no-zip, -nz If set a directory will be created instead of an archive file
149+
--force, -f Will overwrite if output directory exists
150+
--diagnostic, -d Collect extensive machine diagnostic information
151+
--bypass-disclaimer Do not display disclaimer banner
152+
--interactive, -i Interactive diagnostic
153+
--delay DELAY, -dd DELAY
154+
Set MDATP log level. If you use interactive or delay mode, the log level will set to debug automatically, and reset after 48h.
155+
--mdatp-log {info,debug,verbose,error,trace,warning}
156+
Set MDATP log level
157+
--max-log-size MAX_LOG_SIZE
158+
Maximum log file size in MB before rotating(Will restart mdatp)
159+
```
160+
161+
Usage example: `sudo ./MDESupportTool -d`
162+
163+
NOTE: The log level autoreset feature only available in 2405 or newer client version.
164+
165+
### Positional arguments
166+
167+
#### Collect performance info
168+
169+
Collect extensive machine performance tracing for analysis of a performance scenario that can be reproduced on demand.
170+
171+
```console
172+
-h, --help show this help message and exit
173+
--frequency FREQUENCY
174+
profile at this frequency
175+
--length LENGTH length of time to collect (in seconds)
176+
```
177+
178+
Usage example: `sudo ./MDESupportTool performance --frequency 2`
179+
180+
#### Use OS trace (for macOS only)
181+
182+
Use OS tracing facilities to record Defender for Endpoint performance traces.
183+
184+
> [!NOTE]
185+
> This functionality exists in the Python solution only.
186+
187+
```console
188+
-h, --help show this help message and exit
189+
--length LENGTH Length of time to record the trace (in seconds).
190+
--mask MASK Mask to select with event to trace. Defaults to all
191+
```
192+
193+
On running this command for the first time, it installs a Profile configuration.
194+
195+
To approve profile installation, see the [Apple Support Guide](https://support.apple.com/guide/mac-help/configuration-profiles-standardize-settings-mh35561/mac#:~:text=Install%20a%20configuration%20profile%20you%E2%80%99ve%20received).
196+
197+
Usage example `./mde_support_tool.sh trace --length 5`
198+
199+
#### Exclude mode
200+
201+
Add exclusions for audit-d monitoring.
202+
203+
> [!NOTE]
204+
> This functionality exists for Linux only.
205+
206+
```console
207+
-h, --help show this help message and exit
208+
-e <executable>, --exe <executable>
209+
exclude by executable name, i.e: bash
210+
-p <process id>, --pid <process id>
211+
exclude by process id, i.e: 911
212+
-d <directory>, --dir <directory>
213+
exclude by target path, i.e: /var/foo/bar
214+
-x <executable> <directory>, --exe_dir <executable> <directory>
215+
exclude by executable path and target path, i.e: /bin/bash /var/foo/bar
216+
-q <q_size>, --queue <q_size>
217+
set dispatcher q_depth size
218+
-r, --remove remove exclusion file
219+
-s, --stat get statistics about common executables
220+
-l, --list list auditd rules
221+
-o, --override Override the existing auditd exclusion rules file for mdatp
222+
-c <syscall number>, --syscall <syscall number>
223+
exclude all process of the given syscall
224+
```
225+
226+
Usage example: `sudo ./MDESupportTool exclude -d /var/foo/bar`
227+
228+
### AuditD Rate Limiter
229+
230+
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.
231+
232+
> [!NOTE]
233+
> This functionality exists for Linux only.
234+
235+
```console
236+
-h, --help show this help message and exit
237+
-e <true/false>, --enable <true/false> enable/disable the rate limit with default values
238+
```
239+
240+
Usage example: `sudo ./mde_support_tool.sh ratelimit -e true`
241+
242+
> [!NOTE]
243+
> 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.
244+
245+
### AuditD Skip Faulty Rules
246+
247+
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.
248+
249+
> [!NOTE]
250+
> This functionality is only available on Linux.
251+
252+
```console
253+
-h, --help show this help message and exit
254+
-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.
255+
```
256+
257+
Usage example: `sudo ./mde_support_tool.sh skipfaultyrules -e true`
258+
259+
> [!NOTE]
260+
> This functionality skips faulty rules. The faulty rule then needs to be further identified and fixed.
261+
262+
## Result package contents on macOS and Linux
263+
264+
| File | Description |
265+
|---|---|
266+
| `report.html` | 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. |
267+
| `mde_diagnostic.zip` | Same diagnostic output that gets generated when running `mdatp diagnostic create` on either [macOS](mac-resources.md#collecting-diagnostic-information) or [Linux](linux-resources.md#collect-diagnostic-information). |
268+
| `mde.xml` | XML output that is generated while running and is used to build the html report file. |
269+
| `Processes_information.txt` | Contains the details of the running Microsoft Defender for Endpoint related processes on the system. |
270+
| `Log.txt` | Contains the same log messages written on screen during the data collection. |
271+
| `Health.txt` | The same basic health output that is shown when running *mdatp health* command. |
272+
| `Events.xml` | Another XML file used by the analyzer when building the HTML report. |
273+
| `Audited_info.txt` | Details on audited service and related components for [Linux](linux-resources.md) OS. |
274+
| `perf_benchmark.tar.gz` | The performance test reports. You see this file only if you're using the performance parameter. |
275+
276+
[!INCLUDE [Microsoft Defender for Endpoint Tech Community](../includes/defender-mde-techcommunity.md)]

0 commit comments

Comments
 (0)