Detalls tècnics del funcionament de l’agent macOS

Requisits i instal·lació de l’agent

Requisits previs

Els requisits necessaris per instal·lar l’agent varien segons la versió del sistema operatiu que cal supervisar i, per extensió, segons la versió de Python del sistema instal·lada.

Per a les versions de macOS anteriors a la 12.3, cal prioritzar la instal·lació de l’agent Python2 (versió instal·lada per defecte al sistema), que no comporta cap requisit addicional que calgui tenir en compte.

No és el cas de l’agent Python3, que requereix verificar els tres elements següents abans de la instal·lació:

  • La màquina ha de tenir instal·lades les Xcode Command Line Tools, una versió reduïda del paquet Xcode que permet, en part, ampliar les funcionalitats relacionades amb l’execució de mòduls de Python. Si no es compleix aquest requisit, es genera el missatge d’error xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun, que es pot resoldre executant xcode-select --install
  • Una màquina amb un processador Mac M1 o M2 ha de disposar del programa Rosetta 2 per ser compatible amb el nostre agent macOS. Aquesta instal·lació requereix executar l’ordre softwareupdate --install-rosetta i acceptar després un acord de llicència. Per automatitzar-ho, l’ordre softwareupdate --install-rosetta --agree-to-license permet ometre l’acceptació d’aquest acord
  • Pel que fa a la gestió de les dependències dels mòduls de Python3, és automàtica des de la versió 4.12 de l’agent. Si apareix l’error ModuleNotFoundError: No module named 'requests', vol dir que aquesta gestió no s’ha pogut completar correctament i, en aquest cas, cal seguir aquest procediment

Instal·lació

L’agent macOS es distribueix en forma de paquet macOS clàssic (.pkg).

L’agent macOS s’instal·la als actius executant una ordre d’instal·lació que s’obté de la interfície de Cyberwatch, al formulari de creació d’un agent macOS. Aquesta ordre d’instal·lació inclou els paràmetres seleccionats a Cyberwatch per a la instal·lació, com ara, per exemple, els grups, l’URL de la instància de Cyberwatch…

La instal·lació de l’agent en un sistema macOS segueix els passos següents:

  • configuració del repositori de l’actiu de destinació perquè conegui el paquet
  • instal·lació del paquet amb el gestor de l’actiu, obtingut del repositori allotjat al servidor de Cyberwatch
  • registre de l’agent al servidor de Cyberwatch amb el mètode register de l’agent
  • supressió del paquet d’instal·lació

De manera individual, l’agent macOS es pot instal·lar copiant i enganxant l’ordre d’instal·lació que proporciona Cyberwatch directament a l’actiu que cal supervisar. Per a qualsevol desplegament a gran escala, es pot automatitzar la instal·lació de l’agent als actius macOS amb una solució que permeti executar ordres en un conjunt d’actius (per exemple, Ansible).

Desinstal·lació de l’agent

Per desinstal·lar completament un agent macOS, executeu les ordres següents:

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

Funcionament de l’agent

Als sistemes macOS, l’agent funciona amb un servei que executa cada cinc minuts el paquet cyberwatch-agent. Aquests dos fitxers es troben, respectivament, a /Library/Cyberwatch/cyberwatch-agent/launchd/fr.cyberwatch.agent.pkg.plist, amb un enllaç simbòlic a /Library/LaunchDaemons/fr.cyberwatch.agent.pkg.plist, i a /Library/Cyberwatch/cyberwatch-agent/cyberwatch-agent.py, amb un enllaç simbòlic a /usr/local/bin/cyberwatch-agent.

Aquests són els fitxers relacionats amb el funcionament de l’agent de Cyberwatch que es creen al sistema durant la instal·lació:

  • /Library/Cyberwatch/cyberwatch-agent/launchd/fr.cyberwatch.agent.pkg.plist: dimoni que s’executa cada 5 minuts
  • /Library/Cyberwatch/cyberwatch-agent/cyberwatch-agent.py: fitxer Python d’execució de l’agent de Cyberwatch
  • /etc/cyberwatch-agent/agent.conf: fitxer de configuració de l’agent
  • el directori /var/log/cyberwatch-agent/, que conté els fitxers agent.log.*

L’execució de l’agent només comporta una comunicació amb l’API de la instància de Cyberwatch, que respon amb les possibles tasques que cal fer a l’actiu en qüestió.

Actualitzacions de l’agent

Els canvis de l’agent es recullen a l’historial de versions de l’agent de Cyberwatch.

Quan Cyberwatch publica una versió nova de l’agent macOS, aquesta es posa a disposició al repositori de la instància on-premise i, per tant, és a disposició dels actius en què es va configurar el repositori durant la instal·lació. Per tant, n’hi ha prou de tornar a executar les ordres d’instal·lació disponibles al formulari de creació d’un agent macOS.

Gestionar manualment la instal·lació de la dependència requests

Tot i la gestió automàtica de les dependències durant el procés d’instal·lació, és possible que pip3 no aconsegueixi baixar el mòdul requests de PyPI. Això pot ser causat per un bloqueig de fluxos, un error en la verificació del certificat de PyPI… I es manifesta amb l’aparició del codi d’error ModuleNotFoundError: No module named 'requests' durant la instal·lació.

En aquest cas, n’hi ha prou d’instal·lar manualment aquest mòdul amb l’usuari root (perquè el mòdul es carregui per a l’usuari que executa l’agent) i, després, tornar a executar l’ordre de registre:

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