Utiliser le programme de l’agent Cyberwatch manuellement

Cette page de documentation présente les différentes commandes et sous-commandes proposées par le programme de l’agent Cyberwatch.

Une fois installé sur un actif Windows ou Linux, le programme cyberwatch-agent peut être exécuté comme tout autre programme ou exécutable.

L’utilisation manuelle de l’agent Cyberwatch à partir de lignes de commande peut permettre de répondre à certains cas d’usage spécifiques. En fonctionnement nominal, l’agent ne nécessite pas d’intervention sur les actifs une fois installé et doit fonctionner de manière autonome conformément aux spécificités du système sur lequel il est installé.

Les cas d’usage potentiels d’utilisation du programme en ligne de commande sont par exemple :

  • la reconfiguration de l’URL d’un agent déjà installé sur un actif (cas pratique illustré ci-dessous) ;
  • le réenregistrement d’un agent déjà installé sur une même instance Cyberwatch ;
  • toute tâche de debug avancée pouvant aider à diagnostiquer un problème de fonctionnement de l’agent ou de communication avec l’interface Cyberwatch.

Description des sous-commandes et options du programme cyberwatch-agent

Le programme propose différentes sous-commandes et options permettant de modifier la configuration de l’agent ou d’exécuter certaines actions.

Ces éléments sont décrits exhaustivement à l’aide de l’option -h ou --help de la commande cyberwatch-agent :

A la date de rédaction de cette documentation, voici le résultat de l’exécution de cette commande :

$ cyberwatch-agent -h
usage: cyberwatch-agent [-h] [-V] [-q] [-d] [--api-url URL] [--access-key-id KEY] [--secret-access-key KEY] [--category CATEGORY] [--later]
                        [--allow_selfsigned bool] [--proxy_enabled bool] [--proxy_host URL] [--groups GROUPS]
                        [{check,register,get_tasks,set_config}]

positional arguments:
  {check,register,get_tasks,set_config}

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -q, --quiet           quiet output: print only errors
  -d, --debug           debug output
  --api-url URL         set api base url when registering
  --access-key-id KEY   set api access key id when registering
  --secret-access-key KEY
                        set api secret access key when registering
  --category CATEGORY   set the category of the computer when registering
  --later               Register only the next time the agent starts
  --allow_selfsigned bool
                        allow selfsigned certificates from the Cyberwatch server (default false)
  --proxy_enabled bool  enable proxy for Cyberwatch API requests (default false)
  --proxy_host URL      set the proxy for Cyberwatch API requests (https://username:password@host:port/ format)
  --groups GROUPS       set the server's groups by separating each one with a coma

check

La sous-commande check permet de vérifier l’état de la configuration de l’agent installé sur l’actif.

Cette commande permet d’obtenir des informations sur :

  • l’environnement (système, encodage…) ;
  • l’état de l’installation ;
  • l’état de la configuration ;
  • le fonctionnement des logs ;
  • la connectivité à Cyberwatch ;
  • les droits accordés à l’agent.

register

La sous-commande register enregistre l’agent auprès de l’instance Cyberwatch.

C’est la commande lancée par défaut lors de l’installation de l’agent sur les actifs.

Si l’agent est déjà enregistré, la commande n’aura aucun effet.

get_tasks

La sous-commande get_tasks interroge l’instance Cyberwatch afin d’obtenir la liste des tâches à exécuter sur l’actif.

Ces tâches sont ordonnées par l’instance Cyberwatch et peuvent notamment inclure :

  • lancer un scan ;
  • déployer un correctif ;
  • redémarrer l’actif.

set_config

La sous-commande set_config modifie la configuration de l’agent actuellement installé à partir des options proposées par l’agent.

Elle permet par exemple de reconfigurer les agents dans le cas d’un changement d’URL de l’instance Cyberwatch.

Modifier l’URL de configuration des agents suite à un changement d’URL de l’instance Cyberwatch

Si l’URL d’accès à l’instance Cyberwatch change, les agents ne seront plus capable de communiquer avec l’instance Cyberwatch. Pour rétablir la connexion, il faut modifier l’URL de l’API configuré dans le fichier de configuration de chacun des agents. Cette section décrit comment procéder.

Il est également nécessaire de modifier l’URL configuré dans le logiciel depuis le menu Administration > Nœuds. Cet URL représente l’adresse utilisée par défaut par les agents lors de leur création depuis l’interface Cyberwatch. Cyberwatch recommande l’utilisation d’un alias DNS afin de s’affranchir des problématiques liées à un potentiel changement de l’adresse IP du serveur Cyberwatch traitées dans ce cas pratique.

Dans le cas où une reconfiguration de l’URL de l’API des agents est nécessaire, cette opération est réalisable à l’aide de la commande suivante.

Sur Windows (PowerShell) :

& 'C:\Program Files\CYBERWATCH SAS\CyberwatchAgent\cyberwatch-agent.exe' set_config --api-url 'https://[NOUVEL_URL]/api/v2/'

Sur Linux :

sudo cyberwatch-agent set_config --api-url 'https://[NOUVEL_URL]/api/v2/'

où [NOUVEL_URL] est à remplacer par le nouvel URL de l’instance Cyberwatch.

Retour en haut