SSSO Product Version |
Release Date |
SSSO 22.10 | December 2022 |
SSSO 21.9 | September 2021 |
SSSO 21.4 | April 2021 |
SSSO 20.11 | November 2020 |
SSSO 20.8 | August 2020 |
SSSO 1.0 | April 2020 |
Self-Service Supportability Orchestrator data collection tool
Technical Articles ID:
KB92519
Last Modified: 2022-12-14 09:32:45 Etc/GMT
Last Modified: 2022-12-14 09:32:45 Etc/GMT
Environment
Self-Service Supportability Orchestrator (SSSO) 22.10 – data collection tool
Summary
SSSO
SSSO is a data collection tool. It brings several supportability tools that endpoint customers use under a single orchestrator. The tool invokes the right tool at the right time, and eases the data collection effort. This tool captures the context in which data collection occurs, which helps in reporting accurate telemetry data.
The SSSO tool is available on the Tools support portal landing page.
Recent updates to this article
Click to expand the section you want to view:
Use this tool in the following situations:
The SSSO comes as a .zip file named SSSO_1.0.0.xxx.zip . The tool folder structure when executed contains the following:
Four SSSO GUI workflows are available:
Command-Line Parameters:
Use:SSSSLauncher.exe [options...]
Example problem: Data Collection when an Endpoint Security process is consuming high CPU on a system.
Playbook name:ENS_Process_HighCPU_Level1.yml
What the playbook does:
For instructions to create an EEDK Workflow, see the "SSSO GUI Workflows" section in the SSSO Product Guide.
How to deploy SSSO to multiple hosts from ePO:
A one-stop solution to deploy SSSO using ePO is through an EEDK package. To use it, follow the steps below:
A set of playbooks that comes with the package that you can use for data collection.
ENS Playbooks
VSE Playbooks
Trellix Agent Playbooks
Application Control Playbooks
Management for Optimized Virtual Environments (MOVE) Antivirus Playbooks
Author your own playbook
It isn't difficult to create your own playbook. Theplaybook.yml file under the doc folder helps create a playbook with little effort.
There are a few things to remember when you create a playbook:
IMPORTANT:
Playbook Execution failed
Playbook execution can fail for many reasons. Some common case examples:
SSSO is a data collection tool. It brings several supportability tools that endpoint customers use under a single orchestrator. The tool invokes the right tool at the right time, and eases the data collection effort. This tool captures the context in which data collection occurs, which helps in reporting accurate telemetry data.
The SSSO tool is available on the Tools support portal landing page.
Recent updates to this article
Date | Update |
December 14, 2022 | Added the link to the updated Product Guide. |
December 9, 2022 | Updated for SSSO Version 22.10. |
Click to expand the section you want to view:
- When you open a Service Request with Technical Support, and need data collection
- When the data collection effort is complex or simple
- When the tool or tools you need are many or difficult to use
- When the issue is sporadic, random, or reproducible on demand
Examples:- Capture data for a high CPU issue that occurs randomly in the environment. This issue requires tools from both Trellix and Microsoft to run in tandem, and only when the CPU usage is high.
- Run the Trellix and Microsoft tools needed to capture the behavior when a third-party application starts, and also where the third-party randomly experiences an Access Denied failure and crashes. Don't collect logs if failure doesn't occur.
- Enable debug logging for Endpoint Security and Trellix Agent when a certain third-party process starts. Collect the process dump of that third party when it crashes within two minutes of startup. Disable debug logging, and collect files when the crash occurs. Otherwise, stop logging until the next time the process starts.
- Doc folder - The doc folder consists of the help documents. The
Playbook.yml file contains the steps to create your own playbook pertinent to the issue. TheTelemetryData.txt file contains details about telemetry information collected for product improvement and Enterprise support purposes. This file is created in the root folder. - Playbooks folder - Consists of two subfolders, custom and default. The default folder contains a few playbooks that have been authored based on customer escalations. Use the custom folder when a new playbook has been authored.
- Plug-ins folder - Plug-ins consist of two subfolders, custom and default. In the default folder, there are a few
PowerShell scripts that monitor specific use cases. The plug-ins are basicallyPowerShell modules. You can write and save custom plug-ins to the custom folder. There are many resources on the internet forPowerShell scripting.
NOTE: The default plug-ins are checked for signing while executing, but the custom plug-ins aren't checked for signing. Trellix isn't responsible for customer-created custom plug-ins.
- Run folder - By default, the run folder isn't present when the tool is freshly extracted from
SSSO_1.0.0.xxx.zip . The folder gets created automatically whenSSSOLauncher.exe is executed. This folder contains the output of the command executed in a compressed (.tgz ) format saved according to the time stamp. This compressed file holds theSSSO.log ,SSSO_Telemetry.xml files, and other dump files or logs. The files depend on the tools used in the command execution. - Tools folder - The tools folder is categorized into custom and default. Each of the folders has subfolders within them, namely x64 and x86. The default tools are shipped with all relevant Trellix tools.
The tools can be updated to latest versions by running the Update Tools Workflow. For details, either see the SSSO Product Guide, or run theSSSOLauncher.exe command.-update
NOTE: The default tools are checked for signing while being executed, but the custom tools aren't checked for signing. Trellix isn't responsible for customer-created custom tools.
License.txt - License information of components used. This file is added as a reference.SSSOLauncher.exe - The main executable that's used to start the SSSO application. It also accepts command-line arguments. To learn more about the input arguments for the binary, see thehelp.txt document in the doc folder.SSSO.log - A log file generated after you run SSSOLauncher.exe . It displays the log output of the last command execution only.SSSO_Updater.log - An updater log file generated after you runSSSOLauncher.exe . It displays the auto-update and log upload output of the last executed command only.SSSO_Telemetry.xml - This XML file displays the telemetry output of the last command executed.Royalty-Free Tools License.txt - This file contains the SSSOend-user license agreement (EULA ). By default, this file isn't present in the root folder. When executed for the first-time, the EULA page is displayed. After acceptance, this file is created in the root folder.
- Collect MER Workflow (SSSO supports all GUI and
WebMER command-line options) - Playbook Execution Workflow (running the SSSO playbooks on a host)
- Create an ePO Endpoint Deployment Kit (EEDK) Workflow
- Update Tools Workflow
Command-Line Parameters:
Use:
Options | Description |
Help details displayed. | |
Download or update third-party tools. | |
Specify the process name to be used inside the playbook. Example: |
|
Specify the filepath to be used inside the playbook. Example: |
|
Run the specified playbook. Example: |
|
Silently accept the SSSO EULA. | |
Specify the CPU threshold to be used inside the playbook. Example: |
|
Use this switch to upload results automatically to a Trellix Server against the given valid Service Request (SR) number. Example: |
|
Skip auto upgrade of SSSO binaries for a particular run. | |
Specify the delay (in seconds) to be used inside the YAML.
Example: |
|
Specify multiple memory thresholds (in MB) separated by a comma, to be used inside the YAML. Example: |
|
Create an ePO deployable package. | |
Silently accept the NOTE: The |
|
Sets the proxy server details. Use one of the options below: Disables the proxy settings; connects directly to the internet without a proxy.
Applies the system proxy settings. Sets the proxy to the specified URL and port. Example: |
|
Turn off SSSO telemetry. | |
Runs the MER for all detected Trellix products with event logs for the default number of days. | |
Specify the supported Trellix products for which MER must be collected. | |
Number of days of Application Logs, System Logs, and Security logs to collect. Specify -1 to avoid collection for any of the event logs.
|
|
Remove IP address, MAC address, domain names, and computer names from the MER result file. | |
Use this switch to sanitize the MER logs from a regex file, or from a regex argument. |
Running SSSO in Air-Gapped Environments:
For a detailed workflow on SSSO execution in air-gapped environments, see the SSSO Product Guide.Playbook name:
What the playbook does:
- Run
SSSOLauncher.exe . - After you accept the EULA, select the playbook
ENS_Process_HighCPU_Level1.yml . For more details, see the SSSO Product Guide and look at the section "Playbook Execution Workflow (Running the SSSO Playbooks on a Host)."
NOTE: TheSSSOLauncher.exe executable waits for the CPU utilization to breach the 40% threshold. - Reproduce the issue, and wait for CPU to breach the threshold value.
- Initiate a full Endpoint Security on-demand scan on the system.
NOTE: When a full on-demand scan is triggered, the CPU utilization exceeds the threshold limit. TheSSSOLauncher.exe starts collecting thePerfCounters ,Procmon , andAMTrace data. At the end, the MER logs are collected.
- After the execution is complete, navigate to
SSSO_1.0.0.xxx\run .
NOTE: The output logs are displayed in theSSSO.log file. The file is found in the root directorySSSO_1.0.0.xxx\run\<timestamp>.tgz . The file displays the output of the command executed, and shows different internal tool activities. Reports generated by all third-party tools are compressed in aSSSO_1.0.0.xxx\run\<timestamp>.tgz file.
- If you use the option
-sr:<SR number> , the data collected is automatically uploaded to the specific Service Request (SR).
For example: Using the option-SR: 1–123456789 , you can upload the collected data to the respective SR 1–123456789.
How to deploy SSSO to multiple hosts from ePO:
A one-stop solution to deploy SSSO using ePO is through an EEDK package. To use it, follow the steps below:
- Upload the package
SSSO to the Master Repository in ePO._EEDK.zip - Select the list of systems or groups in the System Tree.
- Create a
Run Client Task Now task by clicking Actions, Agent, Run Client Task Now. - In the Run Client Task Now window, select the product Trellix
Agent , the task type as Product Deployment, and then click Create New Task. - On the Run Client Task Now page, select the following:
- The Target Platform
- The product as
Self Service Supportability 1.0.0.xxx
- Provide the command-line option
-acceptThirdPartyEULA , and provide the respective command-line argument to run the playbook. For example:
-acceptThirdPartyEULA -play <Playbook_Name.yml>
- Provide appropriate command-line options to run the specific playbook.
Example: You runENS_Process_HighCPU_Level1.yml to collect data formcsheild.exe at a CPU threshold of 40%. The command would be as follows:
-acceptThirdPartyEULA -play ENS_Process_HighCPU_Level1.yml -procname:mcshield.exe -threshold:40
NOTE: Any parameter with a double quote (") must be prefixed with a backslash \. For example:
acceptthirdpartyeula -MERprods \"Endpoint Security\"
Package and command-line information example:
NOTES:- If there are any SSSO failures, you can look in the
SSSO_Updater.log andSSSO.log in%ProgramData%\McAfee\SSSO . - The location of the output logs is
%ProgramData%\McAfee\SSSO\<Timestamp>.tgz . - The following applies for any playbook that needs to be executed on the client using the EEDK package. You must first accept an EULA for third-party tools on the client system.
- You can't run playbooks with
LiveKD.exe andNotMyFault.exe references from ePO.
- If there are any SSSO failures, you can look in the
NOTES:
- All playbooks require that the minimum
PowerShell version of 3.0 or later to be installed. - If Exploit Prevention is enabled, the rule Execution Policy Bypass in PowerShell mustn't be configured to Block.
- For all Memory-related playbooks, if either of the following products are installed, self-protection must be disabled before executing the playbook.
- Endpoint Security (ENS)
- VirusScan Enterprise (VSE)
- Basic Playbooks
- Advanced Playbooks
Basic | |
Playbook Name | Playbook Description |
Checks if the third-party tool EULA is accepted. Any software to be installed before running playbook: No |
|
Advanced | |
Playbook Name | Playbook Description |
Shows the usage of all Trellix tools. Collects: Any software to be installed before running playbook: No |
|
Monitors high CPU usage of a specified process ( Collects: Any software to be installed before running playbook: No |
|
Looks for a pattern in any log file. Collects: Any software to be installed before running playbook: No |
|
Monitors the event of a process crash ( Collects: Any software to be installed before running playbook: No |
|
Monitors the event of a process crash ( Collects: Process dump, MER. Any software to be installed before running playbook: No |
|
Monitors the event of a process hang ( Collects: Any software to be installed before running playbook: No |
|
Monitors the event of a process: ( Collects: Any software to be installed before running playbook: No |
|
Monitors the event of a process: ( Collects: Any software to be installed before running playbook: Yes1 |
|
Collects multiple crash dumps for a specified process. Any software to be installed before running playbook: No |
|
Useful in detecting memory leaks for a given process and given memory thresholds ( Collects: Any software to be installed before running playbook: Yes1,2 |
1 | Windows Debugging tools that need to be installed to run |
2 | Windows Development Kit (WDK) needs to be installed to run |
ENS Playbooks
Basic | |
Playbook Name | Playbook Description |
Collects data for a certain event ID. Collects: Any software to be installed before running playbook: No |
|
Monitors for installation failures for the ePO deployment of ENS. Collects: Any software to be installed before running playbook: No |
|
Monitors the CPU usage of the specified ENS process
Any software to be installed before running playbook: No( ( Collects: |
|
Useful in detecting memory leaks for a given ENS process.
Any software to be installed before running playbook: Yes1Collects: |
|
Used to collect dumps for a slow on-demand scan (ODS). Collects: Multiple Any software to be installed before running playbook: No |
|
The playbook monitors the process: ( Collects: Any software to be installed before running playbook: No |
|
Monitors the CPU usage of the entire system. Collects: Any software to be installed before running playbook: Yes2 |
|
Advanced | |
Playbook Name | Playbook Description |
Collects data for a certain event ID and messages. Collects: Any software to be installed before running playbook: No |
|
Collects the ENS Firewall configuration, policy, and Any software to be installed before running playbook: No |
|
Monitors for installation failures for the standalone installation of ENS. Collects: Any software to be installed before running playbook: Yes2 |
|
Monitors the CPU usage of the specified ENS process: ( Collects: Any software to be installed before running playbook: No |
|
Monitors the CPU and memory usage of the specified ENS process ( Collects: Complete memory dump if there's a threshold breach. Any software to be installed before running playbook: No |
|
Monitors a process if it takes a long time to startup. Collects: Any software to be installed before running playbook: No |
|
Configures boot logs for ENS Windows. Since it's a manual execution, the user has to execute the Collects: Any software to be installed before running playbook: No |
|
This playbook has to be executed after Collects: Any software to be installed before running playbook: No |
1 |
Windows Debugging tools need to be installed to run the
|
2 | Windows Assessment and Deployment Kit (ADK) needs to be installed to run |
VSE Playbooks
Playbook Name | Playbook Description |
Monitors for an event ID 21, which relates to execution denied for an application, and collects the MER file when this event occurs. Any software to be installed before running playbook: No |
|
Collects information by running Any software to be installed before running playbook: No |
|
Can be used to set the needed log levels. Any software to be installed before running playbook: No |
Trellix Agent Playbooks
Basic | |
Playbook Name | Playbook Description |
Useful when detecting memory leaks for a given Trellix Agent process. Collects: Any software to be installed before running playbook: Yes1 |
Windows Debugging tools need to be installed to run
|
Application Control Playbooks
Basic | |
Playbook Name | Playbook Description |
Monitors execution denied event by Application Control. Collects: Any software to be installed before running playbook: No |
|
Collects: Any software to be installed before running playbook: No |
|
Sets the needed log levels for a specified ACC module. Any software to be installed before running playbook: No |
|
Advanced | |
Playbook Name | Playbook Description |
Monitors the CPU usage of a specified Application Control process ( Collects: Any software to be installed before running playbook: Yes2 |
|
Useful in detecting memory leaks for a given Application Control process. Collects: Any software to be installed before running playbook: No |
|
Monitors for installation failures of Application Control. Collects: Any software to be installed before running playbook: No |
|
Monitors package changes prevention events by Application Control. Collects: MER. Any software to be installed before running playbook: No |
|
Monitors execution prevention event by Application Control for any binary. Collects: MER. Any software to be installed before running playbook: No |
|
Useful in detecting memory leaks for a given Application Control process. Collects: Any software to be installed before running playbook: Yes1 |
|
Collects: Any software to be installed before running playbook: No |
|
Monitors system crash for Application Control. Collects: Any software to be installed before running playbook: No |
|
Monitors system crash for Application Control. Collects: Any software to be installed before running playbook: No |
|
Zips the data generated on a system crash, after execution of MACC_ Any software to be installed before running playbook: No |
|
Monitors write denied event by Application Control. Collects: Any software to be installed before running playbook: No |
WDK needs to be installed to run
|
|
2 | Windows ADK needs to be installed to run |
Management for Optimized Virtual Environments (MOVE) Antivirus Playbooks
Basic | |
Playbook Name | Playbook Description |
Changes the Collects: Any software to be installed before running playbook: No |
|
Advanced | |
Playbook Name | Playbook Description |
Monitors for the installation failures of 32-bit MOVE client. Collects: Any software to be installed before running playbook: No |
|
Monitors for the installation failures of 64-bit MOVE client. Collects: Any software to be installed before running playbook: No |
|
Useful in detecting memory leaks for a given MOVE process. Collects: MER, multiple Any software to be installed before running playbook: Yes1 |
Windows Debugging tools need to be installed to run
|
Author your own playbook
It isn't difficult to create your own playbook. The
There are a few things to remember when you create a playbook:
- Outline your use case in simple tasks. Break down what's needed and when it's needed.
- Follow the conventions as described in the file
doc\playbook.yml . - Avoid using tab spaces in the
YAML software. The following is an FAQ from the officialYAML website:
"Tabs have been outlawed, since different editors and tools treat them differently. And since indentation is so critical to proper interpretation of YAML, this issue is just too tricky to even attempt. Indeed, Guido van Rossum of Python has acknowledged that allowing TABs in Python source is a headache for many people."
- The SSSO supports playbooks of well-known workflows, which include product-specific workflows.
- The user-specific or product-specific workflows can reduce the time for auto-remediation or effective data collection.
- The SSSO also supports building custom playbooks based on your needs.
- The playbook also supports invoking different tools based on time, events, or external triggers.
Operating System | SSSO Tool 21.9 and later |
Clients | |
Microsoft Windows 11 | Yes |
Microsoft Windows 10 version 21H2 Microsoft Windows 10 version 21H1 Microsoft Windows 10 version 20H2 October 2020 Update Microsoft Windows 10 version 2004 May 2020 Update Microsoft Windows 10 version 1909 November 2019 Update Microsoft Windows 10 version 1903 May 2019 Update (64-bit, 32-bit) |
Yes |
Microsoft Windows 8 (64-bit, 32-bit) | Yes |
Microsoft Windows 7 (64-bit, 32-bit) | Yes |
Microsoft Windows Vista (64-bit, 32-bit) | No |
Servers | |
Microsoft Windows Server 2022 | Yes |
Microsoft Windows Server 2019 | Yes |
Microsoft Windows Server 2016 | Yes |
Microsoft Windows Server 2012 R2 | Yes |
Microsoft Windows Server 2012 | Yes |
Microsoft Windows Server 2008 Release 2 (64-bit) | Yes |
Microsoft Windows Server 2008 | No |
Product | Debug Logging Article |
Application Control | KB90755 - Minimum Data Collection to troubleshoot Application Control |
MOVE | KB87799 - How to enable debug logging for MOVE Agentless and Multi-Platform via the command line |
ENS | KB91797 - Enable debug logging to troubleshoot Endpoint Security issues |
- If you try to execute the SSSO tool with Application Control (Application Control enabled), you might observe some denials.
- You need to add a Trellix certificate as a trusted publisher. For more information, see KB94861 - How to use the SSSO tool with ACC enabled.
- "
Another Instance of Self Service Supportability Orchestrtor is already running. "
Comment: You can only run one instance of SSSO at a time.
- "
Unsupported OS! SSSO requires Windows 7/ Windows 2008 R2 or above. "
Blocking Execution.
Comment: SSSO can run only on operating systems listed in the "Supported operating systems" section. Running SSSO on older operating system versions returns an unsupported operating system error.
- "
PowerShell version not supported! Please upgrade PowerShell version is less than 3.0 or higher version.
Blocking Execution. "
Comments:
- For all workflows except 'Collect MER Workflow', the
PowerShell version must be 3.0 or later. - If Exploit Prevention is enabled, the rule Execution Policy Bypass in PowerShell mustn't be configured to Block.
- "
Self Service Supportability Orchestrtor validation Failed! Exiting."
Comment: This error appears if any unauthorized files are present in the SSSO folders. To understand the reason for the failure, look at the logs.
- "
Self Service Supportability Orchestrtor validation Failed! "
Invalid File SSSSO_1.0.0.1522/test.xml
Blocking SSSO Execution!
Comment: You can't run SSSO from case-sensitive paths. If any of the folders in the path are case-sensitive, see below.
Playbook Execution failed
Playbook execution can fail for many reasons. Some common case examples:
- "
ENS Self Protection not disabled "- For all memory-related playbooks, if ENS or VSE is installed, self-protection must be disabled before running the playbook.
- "
Required tool missing "- Make sure that the needed software is installed, and paths are set correctly in the playbook.
- For other errors, look at the logs for details. You can click View Logs Folder on the Summary page.
- "
Waiting for Process to Launch - Memory Playbooks. "- In playbooks like
MA_Process_MemoryLeak.yml , while enabling or disablinggFlags , SSSO stops the process and expects it to restart. - Ideally, the process starts automatically. But, sometimes the process might not start if the playbook is run multiple times within a short duration.
- In that case, SSSO is waiting for the process to start. If you see that the process hasn't started for a long time, check and manually start the process. If it's a service like
masvc.exe , start it through the Windows Service Control Manager.
- In playbooks like
Related Information
Known Issues
Related Article | Issue Description |
- | Issue: SSSO doesn't work on a non-English language OS. The keywords used in the scripts aren't automatically translated into foreign languages. Workaround: You can manually adjust the scripts (e.g. Use " |
- | Issue: SSSO auto update fails from earlier versions. You can't update SSSO from version 21.4 or earlier. Workaround: You can download the latest SSSO package (ZIP) from the tools portal, and run it. |
KB92811 | Issue: Resolution: You must place third-party tools in the |
- | Issue: SSSO Create EEDK workflow fails, when SSSO is run from paths with parenthesis. Workaround: Copy SSSO Orchestrator in a folder without parenthesis in the path and run the EEDK workflow. |
Affected Products
Languages:
This article is available in the following languages: