Skip to content

Commit 3b78fed

Browse files
YongRhee-MSFTYongRhee-MSFT
committed
Learn Editor: Update run-analyzer-linux.md
1 parent ddac2fa commit 3b78fed

File tree

1 file changed

+293
-1
lines changed

1 file changed

+293
-1
lines changed

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

Lines changed: 293 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,296 @@ ms.topic: # Add the ms.topic value
1313
ms.date: 10/30/2024
1414
---
1515

16-
Run the client analyzer on Linux
16+
# Run the client analyzer on Linux
17+
18+
The XMDEClientAnalyzer is used for diagnosing Microsoft Defender for Endpoint health or reliability issues on onboarded devices running Linux.
19+
20+
There are two ways to run the client analyzer tool:
21+
22+
1. Using a binary version (no external Python dependency)
23+
2. Using a Python-based solution
24+
25+
## Running the binary version of the client analyzer
26+
27+
1. Download the [XMDE Client Analyzer Binary](https://aka.ms/XMDEClientAnalyzerBinary) tool to the Linux machine you need to investigate.
28+
If you're using a terminal, download the tool by entering the following command:
29+
30+
```bash
31+
wget --quiet -O XMDEClientAnalyzerBinary.zip https://aka.ms/XMDEClientAnalyzerBinary
32+
```
33+
34+
1. Verify the download.
35+
36+
- Linux
37+
38+
```bash
39+
echo '2A9BF0A6183831BE43C7BCB7917A40D772D226301B4CDA8EE4F258D00B6E4E97 XMDEClientAnalyzerBinary.zip' | sha256sum -c
40+
```
41+
42+
2. Extract the contents of _XMDEClientAnalyzerBinary.zip_ on the machine.
43+
44+
If you're using a terminal, extract the files by entering the following command:
45+
46+
```bash
47+
unzip -q XMDEClientAnalyzerBinary.zip -d XMDEClientAnalyzerBinary
48+
```
49+
50+
3. Change to the tool's directory by entering the following command:
51+
52+
```bash
53+
cd XMDEClientAnalyzerBinary
54+
```
55+
56+
4. Two new zip files are produced:
57+
58+
- **SupportToolLinuxBinary.zip** : For all Linux devices
59+
- **SupportToolMacOSBinary.zip** : For Mac devices
60+
61+
5. Unzip one of the above 2 zip files based on the machine you need to investigate.
62+
63+
When using a terminal, unzip the file by entering one of the following commands based on OS type:
64+
65+
- Linux
66+
67+
```bash
68+
unzip -q SupportToolLinuxBinary.zip
69+
```
70+
71+
- Mac
72+
73+
```bash
74+
unzip -q SupportToolMacOSBinary.zip
75+
```
76+
77+
6. Run the tool as _root_ to generate diagnostic package:
78+
79+
```bash
80+
sudo ./MDESupportTool -d
81+
```
82+
83+
## Running the Python-based client analyzer
84+
85+
> [!NOTE]
86+
> - The analyzer depends on few extra PIP packages (`decorator`, `sh`, `distro`, `lxml`, and `psutil`) 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](https://pypi.org/search/?q=lxml).
87+
> - In addition, the tool currently requires Python version 3 or later to be installed on your device.
88+
> - 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"`.
89+
90+
> [!WARNING]
91+
> 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.
92+
93+
1. Download the [XMDE Client Analyzer](https://aka.ms/XMDEClientAnalyzer) tool to the macOS or Linux machine you need to investigate.
94+
95+
If you're using a terminal, download the tool by running the following command:
96+
97+
```bash
98+
wget --quiet -O XMDEClientAnalyzer.zip https://aka.ms/XMDEClientAnalyzer
99+
```
100+
101+
2. Verify the download
102+
103+
- Linux
104+
105+
```bash
106+
echo '84C9718FF3D29DA0EEE650FB2FC0625549A05CD1228AC253DBB92C8B1D9F1D11 XMDEClientAnalyzer.zip' | sha256sum -c
107+
```
108+
109+
- macOS
110+
111+
```bash
112+
echo '84C9718FF3D29DA0EEE650FB2FC0625549A05CD1228AC253DBB92C8B1D9F1D11 XMDEClientAnalyzer.zip' | shasum -a 256 -c
113+
```
114+
115+
3. Extract the contents of XMDEClientAnalyzer.zip on the machine.
116+
If you're using a terminal, extract the files by using the following command:
117+
118+
```bash
119+
unzip -q XMDEClientAnalyzer.zip -d XMDEClientAnalyzer
120+
```
121+
122+
4. Change directory to the extracted location.
123+
124+
```bash
125+
cd XMDEClientAnalyzer
126+
```
127+
128+
5. Give the tool executable permission:
129+
130+
```bash
131+
chmod a+x mde_support_tool.sh
132+
```
133+
134+
6. Run as a non-root user to install required dependencies:
135+
136+
```bash
137+
./mde_support_tool.sh
138+
```
139+
140+
7. To collect actual diagnostic package and generate the result archive file, run again as root:
141+
142+
```bash
143+
sudo ./mde_support_tool.sh -d
144+
```
145+
146+
## Command line options
147+
148+
### Primary command lines
149+
150+
Use the following command to get the machine diagnostic.
151+
152+
```console
153+
-h, --help show this help message and exit
154+
--output OUTPUT, -o OUTPUT
155+
Output path to export report
156+
--outdir OUTDIR Directory where diagnostics file will be generated
157+
--no-zip, -nz If set a directory will be created instead of an archive file
158+
--force, -f Will overwrite if output directory exists
159+
--diagnostic, -d Collect extensive machine diagnostic information
160+
--bypass-disclaimer Do not display disclaimer banner
161+
--interactive, -i Interactive diagnostic
162+
--delay DELAY, -dd DELAY
163+
Set MDATP log level. If you use interactive or delay mode, the log level will set to debug automatically, and reset after 48h.
164+
--mdatp-log {info,debug,verbose,error,trace,warning}
165+
Set MDATP log level
166+
--max-log-size MAX_LOG_SIZE
167+
Maximum log file size in MB before rotating(Will restart mdatp)
168+
```
169+
170+
Usage example: `sudo ./MDESupportTool -d`
171+
172+
NOTE: The log level auto-reset feature only available in 2405 or newer client version.
173+
174+
### Positional arguments
175+
176+
#### Collect performance info
177+
178+
Collect extensive machine performance tracing for analysis of a performance scenario that can be reproduced on demand.
179+
180+
```console
181+
-h, --help show this help message and exit
182+
--frequency FREQUENCY
183+
profile at this frequency
184+
--length LENGTH length of time to collect (in seconds)
185+
```
186+
187+
Usage example: `sudo ./MDESupportTool performance --frequency 2`
188+
189+
#### Use OS trace (for macOS only)
190+
191+
Use OS tracing facilities to record Defender for Endpoint performance traces.
192+
193+
> [!NOTE]
194+
> This functionality exists in the Python solution only.
195+
196+
```console
197+
-h, --help show this help message and exit
198+
--length LENGTH Length of time to record the trace (in seconds).
199+
--mask MASK Mask to select with event to trace. Defaults to all
200+
```
201+
202+
On running this command for the first time, it installs a Profile configuration.
203+
204+
Follow this to approve profile installation: [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).
205+
206+
Usage example `./mde_support_tool.sh trace --length 5`
207+
208+
#### Exclude mode
209+
210+
Add exclusions for audit-d monitoring.
211+
212+
> [!NOTE]
213+
> This functionality exists for Linux only.
214+
215+
```console
216+
-h, --help show this help message and exit
217+
-e <executable>, --exe <executable>
218+
exclude by executable name, i.e: bash
219+
-p <process id>, --pid <process id>
220+
exclude by process id, i.e: 911
221+
-d <directory>, --dir <directory>
222+
exclude by target path, i.e: /var/foo/bar
223+
-x <executable> <directory>, --exe_dir <executable> <directory>
224+
exclude by executable path and target path, i.e: /bin/bash /var/foo/bar
225+
-q <q_size>, --queue <q_size>
226+
set dispatcher q_depth size
227+
-r, --remove remove exclusion file
228+
-s, --stat get statistics about common executables
229+
-l, --list list auditd rules
230+
-o, --override Override the existing auditd exclusion rules file for mdatp
231+
-c <syscall number>, --syscall <syscall number>
232+
exclude all process of the given syscall
233+
```
234+
235+
Usage example: `sudo ./MDESupportTool exclude -d /var/foo/bar`
236+
237+
### AuditD Rate Limiter
238+
239+
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.
240+
241+
> [!NOTE]
242+
> This functionality exists for Linux only.
243+
244+
```console
245+
-h, --help show this help message and exit
246+
-e <true/false>, --enable <true/false> enable/disable the rate limit with default values
247+
```
248+
249+
Usage example: `sudo ./mde_support_tool.sh ratelimit -e true`
250+
251+
> [!NOTE]
252+
> 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.
253+
254+
### AuditD Skip Faulty Rules
255+
256+
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.
257+
258+
> [!NOTE]
259+
> This functionality is only available on Linux.
260+
261+
```console
262+
-h, --help show this help message and exit
263+
-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.
264+
```
265+
266+
Usage example: `sudo ./mde_support_tool.sh skipfaultyrules -e true`
267+
268+
> [!NOTE]
269+
> This functionality will be skipping the faulty rules. The faulty rule then needs to be further identified and fixed.
270+
271+
## Result package contents on macOS and Linux
272+
273+
- report.html
274+
275+
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.
276+
277+
- mde_diagnostic.zip
278+
279+
Description: 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).
280+
281+
- mde.xml
282+
283+
Description: XML output that is generated while running and is used to build the html report file.
284+
285+
- Processes_information.txt
286+
287+
Description: contains the details of the running Microsoft Defender for Endpoint related processes on the system.
288+
289+
- Log.txt
290+
291+
Description: contains the same log messages written on screen during the data collection.
292+
293+
- Health.txt
294+
295+
Description: The same basic health output that is shown when running *mdatp health* command.
296+
297+
- Events.xml
298+
299+
Description: Additional XML file used by the analyzer when building the HTML report.
300+
301+
- Audited_info.txt
302+
303+
Description: details on audited service and related components for [Linux](linux-resources.md) OS.
304+
305+
- perf_benchmark.tar.gz
306+
307+
Description: The performance test reports. You'll see this only if you're using the performance parameter.
308+
[!INCLUDE [Microsoft Defender for Endpoint Tech Community](../includes/defender-mde-techcommunity.md)]

0 commit comments

Comments
 (0)