Creating an agent

A KUMA agent consists of two parts: one part is created inside the KUMA web interface, and the second part is installed on a server or on an asset in the network infrastructure.

An agent is created in several steps:

1. Creating a set of resources for the agent in the KUMA web interface
2. Creating an agent service in the KUMA web interface
3. Installing the server portion of the agent to the asset that will forward messages

A KUMA agent for Windows assets can be created automatically when you create a collector with the wmi or wec transport type. Although the set of resources and service of these agents are created in the Collector Installation Wizard, they must still be installed to the asset that will be used to forward a message.

Creating a set of resources for an agent

In the KUMA web interface, an agent service is created based on the set of resources for an agent that unites connectors and destinations.

To create a set of resources for an agent in the KUMA web interface:

1. In the KUMA web interface, under Resources → Agents, click Add agent.

   This opens a window for creating an agent with the Base settings tab active.

2. Fill in the settings on the Base settings tab:
   • In the Agent name field, enter a unique name for the created service. The name must contain from 1 to 128 Unicode characters.
   • In the Tenant drop-down list, select the tenant that will own the storage.
   • If you want, select the Debug check box to log service operations.
   • You can optionally add up to 256 Unicode characters describing the service in the Description field.
3. Create a connection for the agent by using the button and switch to the added Connection <number> tab.

   You can delete tabs by using the button.

4. In the Connector settings block, add a connector resource:
   • If you want to select an existing resource, select it from the drop-down list.
   • If you want to create a new resource, select it in the Create new drop-down list and define its settings:
     • Specify the connector name in the Name field. The name must contain from 1 to 128 Unicode characters.
     • In the Type drop-down list, select the connector type and define its settings on the Basic settings and Advanced settings tabs. The available settings depend on the selected type of connector:
       • tcp
       • udp
       • nats
       • kafka
       • http
       • file
       • ftp
       • nfs
       • wmi
       • wec
       • snmp

       The agent type is determined by the connector that is used in the agent. The only exception is for agents with a destination of the diode type. These agents are considered to be diode agents.

       When using the tcp or upd connector type at the normalization stage, IP addresses of the assets from which the events were received will be written in the DeviceAddress event field if it is empty.

   • You can optionally add up to 256 Unicode characters describing the resource in the Description field.

   The connector resource is added to the selected connection of the agent's set of resources. The created resource is only available in this resource set and is not displayed in the web interface Resources → Connectors section.

5. In the Destinations settings block, add resources of destinations.
   • If you want to select an existing resource, select it from the drop-down list.
   • If you want to create a new resource, select it in the Create new drop-down list and define its settings:
     • Specify the destination name in the Name field. The name must contain from 1 to 128 Unicode characters.
     • In the Type drop-down list, select the destination type and define its settings on the Basic settings and Advanced settings tabs. The available settings depend on the selected type of destination:
       • nats—used for NATS communications.
       • tcp—used for communications over TCP.
       • http—used for HTTP communications.
       • diode—used to transmit events using a data diode.
       • kafka—used for Kafka communications.
       • file—used for writing to a file.
   • You can optionally add up to 256 Unicode characters describing the resource in the Description field.

     The advanced settings for an agent destination (such as TLS mode and compression) must match the advanced destination settings for the collector that you want to link to the agent.

   There can be more than one destination point. You can add them by clicking the Add destination button and can remove them by clicking the button.

6. Repeat steps 3–5 for each agent connection that you want to create.
7. Click Save.

The set of resources for the agent is created and displayed under Resources → Agents. Now you can create an agent service in KUMA.

Creating an agent service in the KUMA web interface

When a set of resources is created for an agent, you can proceed to create an agent service in KUMA.

To create an agent service in the KUMA web interface:

1. In the KUMA web interface, under Resources → Active services, click Add service.
2. In the opened Choose a service window, select the set of resources that was just created for the agent and click Create service.

The agent service is created in the KUMA web interface and is displayed under Resources → Active services. Now agent services must be installed to each asset from which you want to forward data to the collector. A service ID is used during installation.

Installing an agent in a KUMA network infrastructure

When an agent service is created in KUMA, you can proceed to installation of the agent to the network infrastructure assets that will be used to forward data to a collector.

Prior to installation, verify the network connectivity of the system and open the ports used by its components.

Installing a KUMA agent on Linux assets

To install a KUMA agent to a Linux asset:

1. Log in to the server where you want to install the service.
2. Create the following directories:
   • /opt/kaspersky/kuma/
   • /opt/kaspersky/agent/
3. Copy the "kuma" file to the /opt/kaspersky/kuma/ folder. The file is located in the installer in the /kuma-ansible-installer/roles/kuma/files/ folder.

   Make sure the kuma file has sufficient rights to run.

4. Execute the following command:

   sudo /opt/kaspersky/kuma/kuma agent --core https://<KUMA Core server FQDN>:<port used by KUMA Core server for internal communication (port 7210 by default)> --id <service ID copied from the KUMA web interface> --wd <path to the directory that will contain the files of the installed agent. If this flag is not specified, the files will be stored in the directory where the kuma file is located>

   Example: sudo /opt/kaspersky/kuma/kuma agent --core https://kuma.example.com:7210 --id XXXX --wd /opt/kaspersky/kuma/agent/XXXX

The KUMA agent is installed on the Linux asset. The agent forwards data to KUMA, and you can set up a collector to receive this data.

Installing a KUMA agent on Windows assets

Prior to installing a KUMA agent to a Windows asset, the server administrator must create a user account with the EventLogReaders and Log on as a service permissions on the Windows asset. This user account must be used to start the agent.

To install a KUMA agent to a Windows asset:

1. Copy the kuma.exe file to a folder on the Windows asset. C:\Users\<User name>\Desktop\KUMA folder is recommended for installation.

   The kuma.exe file is located inside the installer in the /kuma-ansible-installer/roles/kuma/files/ folder.

2. Start the Command Prompt on the Windows asset with Administrator privileges and locate the folder containing the kuma.exe file.
3. Execute the following command:

   kuma agent --core https://<fullly qualified domain name of the KUMA Core server>:<port used by the KUMA Core server for internal communications (port 7210 by default)> --id <ID of the agent service that was created in KUMA> --user <name of the user account used to run the agent, including the domain> --install

   Example: kuma agent --core https://kuma.example.com:7210 --id XXXXX --user domain\username --install

   You can get help information by executing the kuma help agent command.

4. Enter the password of the user account used to run the agent.

The C:\Program Files\Kaspersky Lab\KUMA\agent\<Agent ID> folder is created in which the KUMA agent service is installed. The agent forwards Windows events to KUMA, and you can set up a collector to receive them.

When the agent service is installed, it starts automatically. The service is also configured to restart in case of any failures. The agent can be restarted from the KUMA web interface, but only when the service is active. Otherwise, the service needs to be manually restarted on the Windows asset.

Removing a KUMA agent from Windows assets

When configuring services, you can test the configuration for errors before installation by running the agent with the following command: kuma agent --core https://<fully qualified domain name of the KUMA Core server>:<port used by the KUMA Core server for internal communications (port 7210 by default)> --id <ID of the agent service that was created in KUMA> --user <name of the user account used to run the agent, including the domain>.

Automatically created agents

When creating a collector with wec or wmi connectors, agents are automatically created for receiving Windows events.

Automatically created agents have the following special conditions:

• Automatically created agents can have only one connection.
• Automatically created agents are displayed under Resources → Agents, and auto created is indicated at the end of their name. Agents can be reviewed or deleted.
• The settings of automatically created agents are defined automatically based on the collector settings from the Connect event sources and Transport sections. You can change the settings only for a collector that has a created agent.
• The description of an automatically created agent is taken from the collector description in the Connect event sources section.
• Debugging of an automatically created agent is enabled and disabled in the Connect event sources section of the collector.
• When deleting a collector with an automatically created agent, you will be prompted to choose whether to delete the collector together with the agent or to just delete the collector. When deleting only the collector, the agent will become available for editing.
• When deleting automatically created agents, the type of collector changes to http, and the connection address is deleted from the URL field of the collector.

In the KUMA interface, automatically created agents appear at the same time when the collector is created. However, they must still be installed on the asset that will be used to forward a message.

Update agents

When updating KUMA versions, the WMI and WEC agents installed on remote machines must also be updated.

To update the agent:

1. Install the new agent on a remote machine.

   The agent has been updated, but no data is coming from it due to an invalid certificate.

2. In the KUMA web interface, under Resources → Active services, reset the certificate of the agent being upgraded.
3. On the remote machine with the installed agent, start the "KUMA Windows Agent <service ID>" service.

   For more information on Windows services, see the documentation for your version of Windows.

The agent and its certificates have been updated.