Grouping agents

Assigning agents to a group

Below are the steps to assign agents to a group with a specific configuration:

1. Once a Wazuh agent has been added and connected to the Wazuh manager, assign it to a group using the /var/ossec/bin/agent_groups tool or the Wazuh server API. Below are examples of how to assign a Wazuh agent with ID 002 to the group dbms using these methods:

   • Using the /var/ossec/bin/agent_groups tool:

     # /var/ossec/bin/agent_groups -a -i 002 -g dbms
     

     Note

     The group must be created and configured before assigning agents. You can create agent groups using the /var/ossec/bin/agent_groups tool. The group name can only contain upper/lower case letters, numbers, dots, underscores, and hyphens.

   • Using the Wazuh server API endpoint PUT /agents/{agent_id}/group/{group_id}:

     # curl -k -X PUT "https://<WAZUH_MANAGER_IP>:55000/agents/002/group/dbms?pretty=true" -H  "Authorization: Bearer $TOKEN"
     

     {
         "data": {
             "affected_items": ["002"],
             "total_affected_items": 1,
             "total_failed_items": 0,
             "failed_items": [],
         },
         "message": "All selected agents were assigned to dbms",
         "error": 0,
     }
     

   Agents assigned to a group can be checked using one of the following commands:

   • Using /var/ossec/bin/agent_groups:

     # /var/ossec/bin/agent_groups -l -g dbms
     

     5 agent(s) in group 'dbms':
       ID: 002  Name: agent-dbms-e1.
       ID: 003  Name: agent-dbms-e2.
       ID: 004  Name: agent-dbms-a1.
       ID: 005  Name: agent-dbms-a2.
       ID: 006  Name: agent-dbms-a3.
     

   • Using the Wazuh server API endpoint GET /groups/{group_id}/agents:

     # curl -k -X GET "https://<WAZUH_MANAGER_IP>:55000/groups/dbms/agents?pretty=true&select=id,name" -H  "Authorization: Bearer $TOKEN"
     

     {
         "data": {
             "affected_items": [
                 {"name": "agent-dbms-e1", "id": "002"},
                 {"name": "agent-dbms-e2", "id": "003"},
                 {"name": "agent-dbms-a1", "id": "004"},
                 {"name": "agent-dbms-a2", "id": "005"},
                 {"name": "agent-dbms-a3", "id": "006"},
             ],
             "total_affected_items": 5,
             "total_failed_items": 0,
             "failed_items": [],
         },
         "message": "All selected agents information was returned",
         "error": 0,
     }
     

2. Once a group is created, its agent.conf file can be edited to include the specific configuration you wish to assign to this group. For this example, the file to be edited is located at /var/ossec/etc/shared/dbms/agent.conf and each agent belonging to this group will receive this file.

3. After connecting to the Wazuh manager, each agent assigned to the group will receive the files contained in the /var/ossec/etc/shared/dbms/ folder from the Wazuh manager, including the agent.conf file that was modified in the previous step. The length of time it takes for the Wazuh manager to push these files to the Wazuh agents depends on the size of the files, the number of agents in the group, and the connection protocol used. For example, depending on network bandwidth and performance, it may take 8 minutes to receive a 10 MB folder (excluding merged.mg file) on 100 agents using UDP. However, if TCP is used, it may take less time.

4. Once a specific agent belongs to a group, it will not be automatically reassigned to this group even if it is re-enrolled under another name or ID. After re-enrollment, it will be added to the default group which is the default behavior. If you want the Wazuh agent to be automatically reassigned after re-enrollment, it must be explicitly activated by the user in the /var/ossec/etc/local_internal_options.conf file by adding the option remoted.guess_agent_group=1 (see section remoted in internal options).

   When this option is added, on re-enrollment, the checksum of the merged.mg file sent by the Wazuh agent is compared with that of the other agents enrolled with the Wazuh manager.

Multiple groups

Agents can be members of multiple groups. When a Wazuh agent is associated with multiple groups, it will receive configuration files from each group. However, the configuration received from the most recently assigned group takes precedence over those from other groups.

Managing multiple groups

The following activities can be carried out when managing multiple Wazuh agent groups.

• Assigning multiple groups to a Wazuh agent

• Listing groups and configuration

• Making changes to group assignment

• Shared files behavior

The /var/ossec/bin/agent_groups tool and the Wazuh server API help to manage agent groups by listing them and allowing them to assign/change/unassign groups to Wazuh agents. We explore three use cases managing multiple groups over existing Wazuh agents.

Assigning multiple groups to a Wazuh agent

There are three different methods to assign a Wazuh agent to one or more groups:

# curl -k -X PUT "https://<WAZUH_MANAGER_IP>:55000/agents/001/group/webserver?pretty=true" -H  "Authorization: Bearer $TOKEN"

{
    "data": {
        "affected_items": ["001"],
        "total_affected_items": 1,
        "total_failed_items": 0,
        "failed_items": [],
    },
    "message": "All selected agents were assigned to webserver",
    "error": 0,
}

# curl -k -X PUT "https://<WAZUH_MANAGER_IP>:55000/agents/001/group/apache?pretty=true" -H  "Authorization: Bearer $TOKEN"

{
    "data": {
        "affected_items": ["001"],
        "total_affected_items": 1,
        "total_failed_items": 0,
        "failed_items": [],
    },
    "message": "All selected agents were assigned to apache",
    "error": 0,
}

# curl -k -X GET "https://<WAZUH_MANAGER_IP>:55000/agents?pretty=true&agents_list=001&select=group" -H  "Authorization: Bearer $TOKEN"

{
    "data": {
        "affected_items": [{"group": ["default", "webserver", "apache"], "id": "001"}],
        "total_affected_items": 1,
        "total_failed_items": 0,
        "failed_items": [],
    },
    "message": "All selected agents information was returned",
    "error": 0,
}

$ /var/ossec/bin/agent_groups -a -i 001 -g webserver

Do you want to add the group 'webserver' to the agent '001'? [y/N]: y
Group 'webserver' added to agent '001'.

$ /var/ossec/bin/agent_groups -a -i 001 -g apache

Do you want to add the group 'apache' to the agent '001'? [y/N]: y
Group 'apache' added to agent '001'.

# /var/ossec/bin/agent-auth -m WAZUH_MANAGER_IP -G webserver,apache

Listing groups and configuration

It is possible to query agents belonging to groups in real-time, and the configuration and shared files applied to each one, depending on which groups they belong to.

For example, to list the Wazuh agents in the webserver group, we could run the following query using the /var/ossec/bin/agent_groups tool:

# /var/ossec/bin/agent_groups -l -g webserver

3 agent(s) in group 'webserver':
  ID: 001 Name: ag-windows-12.
  ID: 003 Name: ag-windows-east.
  ID: 004 Name: centos-7-apache

We can also query which groups the Wazuh agent 001 is a member of:

# /var/ossec/bin/agent_groups -s -i 001

The agent 'ag-windows-12' with ID '001' has the group: '[u'webserver', u'apache']'.

The priority of the groups increases from the left to the right, meaning the last group has the highest priority. In the example above, apache is the group that has the highest priority.

Making changes to group assignment

Just as agents can be assigned to multiple groups, it is also possible to revert assignments and switch between available groups. The command below removes the Wazuh agent 001 from the apache group:

# /var/ossec/bin/agent_groups -r -i 001 -g apache -q

Group 'apache' unset for agent '001'.

To verify the successful removal from the group, run this command on the Wazuh server to check which groups Wazuh agent 001 belongs to.

# /var/ossec/bin/agent_groups -s -i 001

The agent 'ag-windows-12' with ID '001' has the group: '[u'webserver']'.

It is also possible to switch between groups and overwrite the existing assignment:

# /var/ossec/bin/agent_groups -s -i 001

The agent 'ag-windows-12' with ID '001' has the group: '[u'default', u'webserver']'.

From the output above, the Wazuh agent has the existing group assignment: default, webserver.

# /var/ossec/bin/agent_groups -a -f -i 001 -g apache

Group 'apache' set to agent '001'.

The previous group assignment has been overwritten and changed to apache.

# /var/ossec/bin/agent_groups -s -i 001

The agent 'ag-windows-12' with ID '001' has the group: '[u'apache']'.

The -f parameter resets the groups assigned to the Wazuh agent and forces it to belong only to the new group.

Shared files behavior

As previously mentioned, the Wazuh manager shares configuration files with its agents according to their group. In the case of belonging to multiple groups, the configuration files of every group are merged into one following these criteria:

• Shared files, such as CIS benchmarks for rootkit detection, are joined in the shared folder. If there are repeated files, the last one added will overwrite the old ones.

• The new agent.conf file added is appended to the existing one. When two groups have conflicting configurations, the last group assigned to the Wazuh agent will take precedence. Learn more about the configuration precedence in centralized configuration manual.

• Custom shared files set from the user to a particular group are also joined to send them to the Wazuh agents.