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.
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
--help options of the
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]
-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
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 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 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 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 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 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.
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:
& 'C:\Program Files\CYBERWATCH SAS\CyberwatchAgent\cyberwatch-agent.exe' set_config --api-url 'https://[NEW_URL]/api/v2/'
sudo cyberwatch-agent set_config --api-url 'https://[NEW_URL]/api/v2/'
[NEW_URL] should be replaced by the new URL/IP address of the Cyberwatch instance.