Technical details on Linux agent

Installation and uninstallation of the agent

The Linux agent is published as a package, its format depends on the target operating system it will be installed on (.deb, .rpm…). The Cyberwatch agent follows best practices on how to create and publish a Linux installation package.

Installing the Linux agent on your assets can be done executing an installation command line provided by your Cyberwatch web interface, through the Linux agent creation form. This installation line gathers configurations chosen in Cyberwatch for its generation, for example: groups, Cyberwatch interface URL…

Installation of the agent on a Linux systems includes the steps below:

  • configuration of the asset’s package repository so that he has access to the repository of the Cyberwatch server;
  • installation of the package using the package manager of the asset, directly downloaded from the Cyberwatch repository;
  • registration of the agent on the Cyberwatch server using the register method of the agent.

Installing the Linux agent can be done by copying and pasting the installation command provided in Cyberwatch directly on the asset to monitor. To industrialize the deployment, it is possible to automate the installation using any solution that allows command execution or package installation on a set of assets (e.g. Ansible).

Uninstalling the Cyberwatch agent is done the same way as any other Linux packages, and should be done using the relevant commands provided by the asset’s package manager.

Optional: it is also possible to get the packages directly through these download links:

How the agent works

On Linux systems, the agent works using a systemd service and timer both created during the installation. Both these files are located under the directory /lib/systemd/system/.

Here are the files related to the Cyberwatch agent created on the system after its installation:

  • /lib/systemd/system/cyberwatch-agent.timer systemd timer executed every 5 minutes;
  • /lib/systemd/system/cyberwatch-agent.service systemd service triggered by the timer responsible for running the cyberwatch-agent program;
  • /usr/bin/cyberwatch-agent executable python file to run the Cyberwatch agent;
  • /etc/cyberwatch-agent/agent.conf agent configuration file;
  • directory /var/log/cyberwatch-agent/ containing agent.log.* files.

Similar as Windows, running the agent simply triggers a communication with the Cyberwatch API that will respond with the potential tasks to be run on the asset.

Linux agent offers customization possibilities, such as modifying the systemd timer or service. This allows to modify some permissions related to the agent execution or the frequency of the systemd timer for example.

Agent updates

As for the Windows agent, changes on the Linux agent are all described in the changelog of the Cyberwatch agent.

On Linux systems, agent updates are handled by the asset’s package manager, as any other Linux package. When Cyberwatch publishes a new agent version, it is available for download on the repository of the on premise Cyberwatch instance, and is therefore available to assets on which the source repositories have been configured when the agent was installed.

Please note that if the agent update is done after a management server change, and before installing the new Cyberwatch agent, it will be necessary to take care about deleting the configuration file that belongs to the old agent: apt purge cyberwatch-agent && rm -f /etc/cyberwatch-agent/agent.conf

Allow to run as a different user

To run the agent as a different user, permissions for configuration and log files must be changed. Moreover, the systemd timer must be instantiated with the right user:

export RESTRICTED_USER=cyberwatch-agent

chown $RESTRICTED_USER /etc/cyberwatch-agent/ -R
chown $RESTRICTED_USER /var/log/cyberwatch-agent/ -R

systemctl disable --now cyberwatch-agent@root.timer
systemctl enable --now cyberwatch-agent@$RESTRICTED_USER.timer

Restrict privileges of the agent

By default, the agent is run via systemd with the user root. The privileges of the runtime environment are restricted to the minimum necessary for optimal Cyberwatch operation.

It is possible to fine tune the privileges granted to the Cyberwatch agent and run it with an unprivileged user. This section details how to do that. These steps are valid for agents in version 4.8 or later. These commands must be run with a privileged user.

  1. Create an unprivileged user:

    export RESTRICTED_USER=cyberwatch-agent
    useradd $RESTRICTED_USER
    
  2. Deactivate the systemd timer that runs the agent every 5 minutes:

    systemctl disable --now cyberwatch-agent@root.timer
    
  3. Grant the unprivileged user read and write access to configuration and log files:

    chown $RESTRICTED_USER /etc/cyberwatch-agent -R
    chown $RESTRICTED_USER /var/log/cyberwatch-agent -R
    
  4. Activate the agent’s systemd timer with the new user:

    systemctl enable --now cyberwatch-agent@$RESTRICTED_USER.timer
    

Cyberwatch is able to run its vulnerability scans when the agent uses a unprivileged user. For some operations, however, such as deploying patches, running certain scans or checking compliance scripts compliance scripts, it is necessary that commands be executed in privileged mode. executed in privileged mode.

Optional - Allow the agent to execute certain commands with privileges

To allow a non privileged user to execute certain commands with privileges, Cyberwatch recommends using the sudoers mechanism.

  1. Edit file /etc/sudoers.d/cyberwatch-agent:

    sudo visudo -f /etc/sudoers.d/cyberwatch-agent
    
  2. Write the following content to the file, commenting or uncommenting lines as needed:

    # Cyberwatch-agent privileges
    
    ## 'id' is the first command ran by Cyberwatch when monitoring an asset, it
    ## helps determine whether or not Cyberwatch has sudoers rights on the asset;
    
    cyberwatch-agent ALL=(ALL) NOPASSWD:SETENV: /usr/bin/id
    
    # ---
    
    ## 'apt-get/yum/pacman' are typical package managers commands, these will be used
    ## in case you ask Cyberwatch to deploy patches on your assets depending on the
    ## type of system monitored;
    
    # cyberwatch-agent ALL=(ALL) NOPASSWD:SETENV: /usr/bin/apt-get
    # cyberwatch-agent ALL=(ALL) NOPASSWD:SETENV: /usr/bin/yum
    # cyberwatch-agent ALL=(ALL) NOPASSWD:SETENV: /usr/bin/pacman
    
    # ---
    
    ## 'shutdown' will be used if you wish to perform reboots on your assets directly
    ## from Cyberwatch;
    
    cyberwatch-agent ALL=(ALL) NOPASSWD:SETENV: /usr/sbin/shutdown
    
    # ---
    
    ## 'ss' is used for ports scans, allowing to run the command with sudoers rights
    ## allows Cyberwatch to get the processes that own the ports;
    
    cyberwatch-agent ALL=(ALL) NOPASSWD:SETENV: /usr/bin/ss
    
    # ---
    
    ## 'dmidecode' is used to retrieve the BIOS metadata, the command requires sudoers
    ## rights to be run.
    
    cyberwatch-agent ALL=(ALL) NOPASSWD:SETENV: /usr/sbin/dmidecode
    
    # ---
    
    ## 'docker' is needed with sudoers rights to perform a vulnerability scan on all 
    ## found Docker images.
    
    cyberwatch-agent ALL=(ALL) NOPASSWD:SETENV: /usr/bin/docker
    
  3. Override the systemd service configuration file:

    systemctl edit --full cyberwatch-agent@$RESTRICTED_USER.service
    

    This command opens a new configuration file in the system’s text editor that takes precedence over the installed service file.

    By default, the systemd service is configured to prevent elevation of privileges. It is necessary to disable these protections to allow the use of sudo.

  4. Comment the following lines:

    # LockPersonality=true
    # NoNewPrivileges=true
    # ProtectClock=true
    # ProtectHostname=true
    # ProtectKernelLogs=true
    # ProtectKernelTunables=true
    # RestrictAddressFamilies=AF_INET AF_INET6 AF_NETLINK AF_UNIX
    # RestrictSUIDSGID=true
    

    When enabled, each of these rules implies that the NoNewPrivileges option is also enabled. It is therefore necessary to disable these options.

  5. Save the file.

  6. Reload systemd configurations:

    systemctl daemon-reload