Dettagli tecnici sul funzionamento dell’agent macOS

Prerequisiti e installazione dell’agent

Prerequisiti

I prerequisiti necessari per l’installazione dell’agent variano in base alla versione del sistema operativo da monitorare e, di conseguenza, alla versione di Python di sistema installata.

Per le versioni di macOS precedenti alla 12.3, è da privilegiare l’installazione dell’agent Python2 (versione installata per impostazione predefinita sul sistema), che non comporta alcun prerequisito aggiuntivo da considerare.

La situazione è diversa per l’agent Python3, che richiede la verifica dei tre elementi seguenti prima della sua installazione:

  • La macchina deve disporre di un’installazione di Xcode Command Line Tools, versione ridotta del pacchetto Xcode, che consente in parte di estendere le funzionalità legate all’esecuzione dei moduli Python. L’assenza di questo prerequisito comporta la generazione del messaggio di errore xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun, che può essere risolto eseguendo xcode-select --install
  • Una macchina con processore Mac M1 o M2 deve disporre del programma Rosetta 2 per essere compatibile con l’agent macOS di Cyberwatch. Questa installazione richiede l’esecuzione del comando softwareupdate --install-rosetta e l’accettazione di un contratto di licenza. A fini di automazione, il comando softwareupdate --install-rosetta --agree-to-license consente di ignorare l’accettazione di questo contratto
  • La gestione delle dipendenze legate ai moduli Python3 è automatica a partire dalla versione 4.12 dell’agent. La comparsa dell’errore ModuleNotFoundError: No module named 'requests' indica che questa gestione non è andata a buon fine; in questo caso è necessario seguire questa procedura

Installazione

L’agent macOS si presenta sotto forma di un pacchetto macOS standard (.pkg).

L’installazione dell’agent macOS sugli asset avviene tramite l’esecuzione di un comando di installazione da recuperare dall’interfaccia Cyberwatch, tramite il modulo di creazione di un agent macOS. Questo comando di installazione include i parametri selezionati in Cyberwatch per la sua installazione, come ad esempio: i gruppi, l’URL dell’istanza Cyberwatch…

L’installazione dell’agent su un sistema macOS prevede i passaggi seguenti:

  • configurazione del repository dell’asset di destinazione affinché riconosca il pacchetto
  • installazione del pacchetto tramite il gestore dell’asset, recuperato dal repository ospitato sul server Cyberwatch
  • registrazione dell’agent sul server Cyberwatch tramite il metodo register dell’agent
  • eliminazione del pacchetto di installazione

Per un singolo asset, l’agent macOS può essere installato copiando e incollando il comando di installazione proposto da Cyberwatch direttamente sull’asset da monitorare. Per una distribuzione su larga scala, è possibile automatizzare l’installazione dell’agent sugli asset macOS tramite una soluzione che consenta l’esecuzione di comandi su un insieme di asset (ad es. Ansible).

Disinstallazione dell’agent

La disinstallazione completa di un agent macOS si effettua eseguendo i comandi seguenti:

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

Funzionamento dell’agent

Sui sistemi macOS, l’agent funziona tramite un servizio che esegue ogni cinque minuti il pacchetto cyberwatch-agent. Questi due file si trovano rispettivamente nei percorsi /Library/Cyberwatch/cyberwatch-agent/launchd/fr.cyberwatch.agent.pkg.plist, con collegamento simbolico in /Library/LaunchDaemons/fr.cyberwatch.agent.pkg.plist, e /Library/Cyberwatch/cyberwatch-agent/cyberwatch-agent.py, con collegamento simbolico in /usr/local/bin/cyberwatch-agent.

Di seguito sono elencati i file relativi al funzionamento dell’agent Cyberwatch creati sul sistema durante l’installazione:

  • /Library/Cyberwatch/cyberwatch-agent/launchd/fr.cyberwatch.agent.pkg.plist daemon avviato ogni 5 minuti
  • /Library/Cyberwatch/cyberwatch-agent/cyberwatch-agent.py file Python di esecuzione dell’agent Cyberwatch
  • /etc/cyberwatch-agent/agent.conf file di configurazione dell’agent
  • la directory /var/log/cyberwatch-agent/ contenente i file agent.log.*

L’esecuzione dell’agent comporta semplicemente una comunicazione con l’API dell’istanza Cyberwatch, che risponderà con gli eventuali job da eseguire sull’asset in questione.

Aggiornamenti dell’agent

Le modifiche dell’agent sono elencate nella cronologia delle versioni dell’agent Cyberwatch.

Quando Cyberwatch pubblica una nuova versione dell’agent macOS, questa viene resa disponibile sul repository dell’istanza on-premise ed è quindi a disposizione degli asset su cui il repository è stato configurato durante l’installazione. È quindi sufficiente eseguire nuovamente i comandi di installazione disponibili dal modulo di creazione di un agent macOS.

Gestire manualmente l’installazione della dipendenza requests

Nonostante la gestione automatica delle dipendenze durante il processo di installazione, è possibile che pip3 non riesca a scaricare il modulo requests da PyPI. Ciò può essere causato da un blocco dei flussi, da un errore di verifica del certificato di PyPI… e si manifesta con la comparsa del codice di errore ModuleNotFoundError: No module named 'requests' durante l’installazione.

In questo caso, è sufficiente installare manualmente questo modulo come utente root (affinché il modulo sia caricato per l’utente che esegue l’agent), quindi eseguire nuovamente il comando di registrazione:

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