Use the Cyberwatch agent command line

This documentation presents the different commands and arguments available when using the Cyberwatch agent program.

Once installed on a Windows or Linux assets, the program cyberwatch-agent can be used as any other program or executable.

Manual use of the Cyberwatch agent program from the command line can be used to solve some specific use cases. However, in nominal mode, the agent does not require any manual intervention on assets on which it is installed and will work on its own in accordance with the specificities of the system it is installed on.

Potential use cases of the program using the command line are for example:

  • to reconfigure the URL of an agent already installed on an asset (practical use case described below)
  • to re-register an agent already installed on the same Cyberwatch instance
  • any advanced debug tasks to help diagnose a problem regarding the agent or its communication with the Cyberwatch interface

Description of cyberwatch-agent positional arguments

The command line offers different arguments and options allowing to update the agent configuration or execute specific actions.

These parameters are exhaustively described thanks to the -h or --help options of the cyberwatch-agent command.

At the date of writing this documentation, here is the result of the help command:

$ 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

The check arguments checks the configuration and global status of the agent installed.

This command returns information on:

  • the environment (system, encoding…)
  • the installation status
  • the configuration status
  • the way logs are handled
  • the state of the connection with the Cyberwatch interface
  • rights and permissions granted to the agent

register

The register argument registers the agent on the Cyberwatch console.

This command is run by default when installing the agent on assets.

If the agent is already registered, the command does not have any effect.

get_tasks

The get_tasks requests the Cyberwatch interface to get the list of tasks to be executed on the asset.

These tasks are scheduled by the Cyberwatch instance and can for example be one of the following:

  • launching a scan
  • deploying a security fix
  • reboot the asset

set_config

The set_config argument modifies the configuration of the agent already installed and registered on an asset.

For example, it allows to update the agents configuration in case the Cyberwatch instance URL is modified.

Example use case: update the agents URL following an update of the Cyberwatch instance URL

In case the Cyberwatch instance URL is modified, agents will no longer be able to communicate with the Cyberwatch instance. To reestablish the connection, it is required to modify the API URL configured in the configuration file of each and every agent. This section describes the procedure to follow.

It is also required to update the URL configured in the web interface from the Administration > Nodes menu. This URL represents the address used by default by agents when they are generated from the Cyberwatch interface. Cyberwatch recommends using a DNS alias to avoid issues related to a potential modification of the Cyberwatch server IP address that this practical use case specifically deals with.

In case an update of the Cyberwatch agents URL is required, this operation can be done using the command below:

On Windows (PowerShell):

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

On Linux:

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

where [NEW_URL] should be replaced by the new URL/IP address of the Cyberwatch instance.

Back to top