Technical details on macOS agent

Agent prerequisites and installation

Prerequisites

Agent prerequisites depend on the monitored OS version and by extension on the default python version installed on the system.

For macOS versions lower than 12.3, the installation of the Python2 agent (installed version by default) has to be prioritized, resulting in the lack of any more prerequisites.

In other hand, some verifications are required before a python3 agent installation:

  • The asset needs an installation of Xcode Command Line Tools, a lighter version of the Xcode package, which extends functionalities related to Python module execution. The absence of this prerequisite will raise the following error xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun, which can be solved by running xcode-select --install.
  • An asset with M1 or M2 Mac processor, needs Rosetta 2, in order to be compatible with our agent. This installation involves running the command softwareupdate --install-rosetta and then accepting a License Agreement. For automation purposes, the command softwareupdate --install-rosetta --agree-to-license allows to override the acceptance of this agreement.
  • Concerning Python3 dependencies management, it’s automatic since version 4.12 of the agent. The appearance of a ModuleNotFoundError: No module named 'requests' error means the request could not be successful, and requires to follow this procedure.

Installation

The macOS agent is published as a classic macOS package(.pkg).

Installing the macOS agent on your assets can be done executing an installation command line provided by your Cyberwatch web interface, through the macOS agent creation form. This installation line gathers configurations chosen in Cyberwatch for its generation, for example: groups, Cyberwatch interface URL…

Installation of the agent on a macOS systems includes the steps below:

  • configuration of the asset’s package repository so that he has access to the repository of the Cyberwatch server;
  • installation of the package using the package manager of the asset, directly downloaded from the Cyberwatch repository;
  • registration of the agent on the Cyberwatch server using the register method of the agent;
  • cyberwatch agent package deletion.

Installing the macOS agent can be done by copying and pasting the installation command provided in Cyberwatch directly on the asset to monitor. To industrialize the deployment, it is possible to automate the installation using any solution that allows command execution or package installation on a set of assets (e.g. Ansible).

Agent uninstallation

The complete uninstallation of the macOS agent requires running the following commands:

sudo launchctl unload -w /Library/LaunchDaemons/fr.cyberwatch.agent.pkg.plist
sudo rm -rf /Library/LaunchDaemons/fr.cyberwatch.agent.pkg.plist
sudo rm -rf /Library/Cyberwatch
sudo rm -rf /var/log/cyberwatch-agent
sudo rm -rf /usr/local/bin/cyberwatch-agent
sudo rm -rf /etc/cyberwatch-agent
sudo pkgutil --forget fr.cyberwatch.agent.pkg

How the agent works

On macOS systems, the agent works using a service executing every five minutes the cyberwatch-agent package. These files are respectively located under the directory /Library/Cyberwatch/cyberwatch-agent/launchd/fr.cyberwatch.agent.pkg.plist, symbolically referenced at /Library/LaunchDaemons/fr.cyberwatch.agent.pkg.plist and /Library/Cyberwatch/cyberwatch-agent/cyberwatch-agent.py, symbolically referenced at /usr/local/bin/cyberwatch-agent.

Here are the files related to the Cyberwatch agent created on the system after its installation:

  • /Library/Cyberwatch/cyberwatch-agent/launchd/fr.cyberwatch.agent.pkg.plist daemons launched every 5 minutes;
  • /Library/Cyberwatch/cyberwatch-agent/cyberwatch-agent.py executable python file to run the Cyberwatch agent;
  • /etc/cyberwatch-agent/agent.conf agent configuration file;
  • directory /var/log/cyberwatch-agent/ containing agent.log.* files.

Running the agent simply triggers a communication with the Cyberwatch API that will respond with the potential tasks to be run on the asset.

Agent updates

Agent changes are all described in the changelog of the Cyberwatch agent.

When Cyberwatch releases a new version of the macOS agent, it is available on the instance repository and therefore on assets which can reach it since the first installation. In this case, you just need to run again the installation commands available from the agent creation form macOS.

Manually manage installation of requests dependency

Despite automatic dependency handling during the installation process, pip3 may fail to download the requests module from PyPI-. This can be caused by a flow block, a failure of PyPI’s certificate verification… And results in the error code ModuleNotFoundError: No module named 'requests' during installation.

In this case, it requires to manually install the module as root (so that the module is loaded for the user running the agent), then run the registration command again:

sudo su -
pip3 install requests
sudo cyberwatch-agent register --access-key-id '' --secret-access-key '' --api-url '' --allow_selfsigned true --groups ','