macOS Agent
The UTMStack macOS agent is a service you install on each Mac. It collects macOS system and security log activity and sends it to UTMStack v12 over an encrypted connection on port 443. It also lets your team run response commands on the Mac.
Before you begin
The Mac must run macOS 11 (Big Sur) or later on Apple Silicon (M1, M2, M3 or newer). Intel-based Macs are not supported.
The Mac must reach your UTMStack server directly on 443/TCP. No other port is needed. The agent has no proxy setting.
You need administrator rights (
sudo) on the Mac.You need the install command from your own UTMStack instance. It contains your connection key, which only administrators can see. See How Data Reaches UTMStack.
The install command downloads everything it needs from your UTMStack instance.
Install the agent
- 1
Open the macOS card
In UTMStack, go to Configure > Integrations and open the Macos card.
- 2
- 3
Copy the command
Copy the command shown. It contains a sensitive enrollment token: do not share it.
- 4
Run it in Terminal
Paste the command into Terminal on the Mac and press Enter. Run it on every Mac you want to monitor. To install through a device management tool, see Deploying Agents at Scale.
The command looks like this (the product fills in your server address and key):
sudo bash -c "mkdir -p /opt/utmstack-macos-agent &&
curl -k -o /opt/utmstack-macos-agent/utmstack_agent_service_darwin_arm64
https://<server>/private/dependencies/agent/utmstack_agent_service_darwin_arm64 &&
chmod +x /opt/utmstack-macos-agent/utmstack_agent_service_darwin_arm64 &&
/opt/utmstack-macos-agent/utmstack_agent_service_darwin_arm64 install <server> <connection-key> yes"The command downloads the agent into /opt/utmstack-macos-agent, checks that the server answers on 443, registers the agent and starts it as a system service (a launch daemon). The agent then downloads its log collection helper, utmstack-collector-mac, into the same folder. A successful run ends with UTMStackAgent service installed correctly. If it stops with an error, see Agent Troubleshooting.
Install options
| Option | Default | Effect |
|---|---|---|
| Skip TLS certificate validation (self-signed server) | On | The agent accepts the server's certificate without checking it. Leave it on if your UTMStack server uses its self-signed certificate. Turn it off if the server has a certificate your Macs trust. In the command this is the last argument, yes or no. |
| Disable remote command execution on this host | Off | Adds --no-remote-control. The agent then refuses every remote command, from the Data Sources console and from SOAR. This can only be undone by reinstalling the agent on the Mac. |
What is installed
| Item | Value |
|---|---|
| Folder | /opt/utmstack-macos-agent |
| Collection helper | /opt/utmstack-macos-agent/utmstack-collector-mac, downloaded from your UTMStack server and started by the agent |
| Launch daemons | /Library/LaunchDaemons/UTMStackAgent.plist and /Library/LaunchDaemons/UTMStackUpdater.plist |
| Agent log file | /opt/utmstack-macos-agent/logs/utmstack_agent.log |
| Local log store | logs_process/logs.db in the agent folder, 20 MB by default. See Agent Command Line. |
What the agent collects
The agent sends macOS system and security log activity under the data type macos. The data source name is the Mac's host name. The collection itself is done by the helper utmstack-collector-mac; the agent restarts it if it stops.
The shipped detection rules for macOS read this data type. To see what your Macs send, open the Macos card and click View logs, then look at the fields of a few events.
You cannot choose sources on the Mac. To discard events you do not need, use a pipeline with a drop step for the macos data type. See Pipelines.
Check that events arrive
Open the Macos card and click View logs. Log Explorer opens with the data type
macosfor the last 24 hours.Filter on
dataSourcewith the Mac's host name. Events normally appear within a minute of the install.On Configure > Data Sources, the Mac appears under Agents within about a minute, with the status Live.
On the Mac, check the services and the helper:
sudo launchctl list | grep UTMStack
pgrep -fl utmstack-collector-mac
sudo /opt/utmstack-macos-agent/utmstack_agent_service_darwin_arm64 statusUninstall the agent
Open the Macos card and expand Uninstall the agent at the bottom of the guide. Run the command in Terminal. It:
runs the agent's own
uninstallcommand, which also removes the agent's registration on the UTMStack server,unloads and deletes the launch daemons
/Library/LaunchDaemons/UTMStackAgent.plistand/Library/LaunchDaemons/UTMStackUpdater.plist,waits 10 seconds and deletes
/opt/utmstack-macos-agent.
The Mac's row stays on the Data Sources page and turns Idle, then Offline. Delete it there if you no longer need it. See Reinstall, Move or Remove an Agent.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Bad CPU type in executable | The Mac has an Intel processor. | Intel Macs are not supported. |
Error trying to connect to server: cannot connect to <server> on port 443 | No direct route to the server on 443. | Open 443 from the Mac to the server. |
Error registering agent: … invalid connection key | The key is wrong or was regenerated, or the command was copied by a non-administrator (*). | Copy the command again as an administrator. |
The Mac is Live but no macos events arrive | The collection helper is missing or not running. The agent log says macOS collector binary not found at: …. | Check that /opt/utmstack-macos-agent/utmstack-collector-mac exists and that the Mac can download from the server; restart the agent with sudo launchctl kickstart -k system/UTMStackAgent. |
| The Mac shows Offline | The Mac is asleep or off, the service is stopped, or the Mac cannot reach UTMStack. | Wake the Mac, check sudo launchctl list | grep UTMStack, then read the agent log. |
For more, see Agent Troubleshooting.