Taegis™ macOS Agent Troubleshooting
This document provides guidance on initial agent troubleshooting steps you can take and information you can gather prior to reaching out to Secureworks support for assistance with agent issues.
Additional Taegis™ Agent troubleshooting, tutorial, and informational articles are available in the Secureworks Knowledge Base.
The new Diagnostics functionality released with version 1.4.9 provides two operations:
- A mode to gather logs and system information into an archive file to send to Secureworks support, eliminating the need for the support team to request system details and reducing the time to resolve issues.
- A troubleshooting mode that analyzes configuration and runtime operation of all agent components and provides feedback on which items need to be addressed.
To access and use Diagnostics via the preferred method of the agent UI:
- Select the Taegis™ icon from the menu bar and choose Open Secureworks Taegis.
Open Secureworks Taegis
- From the left navigation menu of the app, choose Diagnostics.
- From either the Collect Information or Troubleshoot sections, select Run.
Diagnostics can also be run from the command-line program located at
/Applications/SecureworksTaegis.app/Contents/bin/taegisctl and must be run with
Connectivity Issues ⫘
- Verify the agent's Connection Status from the Endpoint Agents Summary table of Endpoint Agents in Taegis™ XDR.
- Ensure connectivity requirements are met by allowing communication to the domains through any firewalls.
- Incorrect registration details may have been presented. Check the registration key and server for any unintended white spaces.
- Is this a cloned device from a prior registered endpoint? If so, it may be considered duplicate and is being rejected. We recommend you uninstall and reinstall the agent with the correct registration details.
- If using mobile device management (MDM), follow the Workspace ONE Deployment instructions.
- If installing outside MDM, follow the UI Deployment instructions.
- Open Taegis by selecting the status icon from the menu bar and choosing Open Secureworks Taegis to verify Full Disk Access is granted and System Extensions are allowed.
Auto Upgrade Failures ⫘
- Examine logs for any obvious errors:
log stream --level debug --predicate 'subsystem == "scwx"'.
Performance Issues ⫘
In order to troubleshoot performance issues like CPU, memory spike, and application crashing, provide Secureworks support the following information and logs. If the log files are too large, ask Secureworks for a file share link to upload the logs.
Provide the following Information ⫘
- The hostname of the machine
- The version the agent is running
- List of system extensions enabled:
systemextensionsctl list|grep secureworks
- Results of the command
topwith Irix mode off (run
topcommand and press Shift + i)
- Which process/extension is consuming the most CPU? Open Activity Monitor, select View from the toolbar, and choose
All Processes, Hierarchically; search for
- What applications are running on the endpoint?
- Is it a VM or physical hardware?
- What is the memory usage? This is available within Activity Monitor
- Download the following troubleshooting script: mac_gather_sysinfo.sh
- Change the script permissions to 744:
chmod 744 mac_gather_sysinfo.sh
- Provide the redirected script output log file to Secureworks for analysis:
./mac_gather_sysinfo.sh > Mac_gather-$HOSTNAME.$(date +%Y-%m-%d).log
- Change the script permissions to 744:
- Share the output of:
log stream --level debug --predicate 'subsystem == "scwx"'; only ERROR and WARN are kept longer term, while INFO, DEBUG, and TRACE are only available for an hour or two. Use
log streamto view logging as it happens. With version 1.0.49, longer term logs are captured in
/Library/Logs/Secureworksand should also be shared
Service Not Starting ⫘
Open up the Console app to view any available crash reports from the agent (filter for
secureworks). Additionally the crash file is available under
- Uninstall may leave behind active system/network extensions due to an Apple bug. The agent cannot avoid this due to its dependency on the OS.
- Logs such as
system.logor any crash report for the application may be helpful for further diagnosis.