Group agents

The Wazuh dashboard

To create agent groups from the Wazuh dashboard:

1. Navigate to Agents management > Groups and click the Add new group button.

2. Enter a name for the agent group and click on the Save new group button.

The agent_groups tool

The agent_groups tool offers the ability to create and manage Wazuh agent groups directly from the command line. The tool is used as follows to create a Wazuh agent group:

# /var/wazuh-manager/bin/agent_groups -a -g <GROUP_NAME> -q

Where:

• The flag -a -g adds a group.

• The <GROUP_NAME> indicates a unique group name. Replace <GROUP_NAME> with the name of the group you want to create.

• The flag -q triggers the silent or no confirmation mode.

Run the following commands on the Wazuh manager to create the agent groups Windows, macOS, and Linux:

# /var/wazuh-manager/bin/agent_groups -a -g Windows -q
# /var/wazuh-manager/bin/agent_groups -a -g macOS -q
# /var/wazuh-manager/bin/agent_groups -a -g Linux -q

An example output is as follows:

Group 'Windows' created.

To ensure the groups are created correctly, run the following command to list all existing groups:

# /var/wazuh-manager/bin/agent_groups -l

An example output is as follows:

Groups (5):
  Linux (0)
  Test (0)
  Windows (0)
  default (4)
  macOS (0)
Unassigned agents: 0.

The Wazuh manager API

Using the Wazuh manager API to create and manage groups programmatically is effective for automating group management tasks. Perform the steps below to create agent groups using the Wazuh manager API:

1. On the Wazuh dashboard, navigate to Server management, and select Dev Tools.

2. Run the queries below to create the agent groups Windows, macOS, and Linux:

   POST /groups {"group_id": "Windows"}
   POST /groups {"group_id": "macOS"}
   POST /groups {"group_id": "Linux"}
   

   

3. You can also use the command line interface to create agent groups via the Wazuh manager API. The equivalent command to run from the console with root user privileges to create the Linux group would be:

   # curl -k -X POST "https://<WAZUH_MANAGER_IP>:55000/groups?pretty=true" -H "Content-Type: application/json" -d '{"group_id": "Linux"}' -H  "Authorization: Bearer $(curl -u <WAZUH_MANAGER_API_USER>:<WAZUH_MANAGER_API_PASSWORD> -k -X POST 'https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true')"
   

   Replace:

   • The <WAZUH_MANAGER_IP> variable with the IP address of your Wazuh manager. In case you have a distributed deployment, use the IP address of the master node.

   • The <WAZUH_MANAGER_API_USER> variable with your Wazuh manager API username.

   • The <WAZUH_MANAGER_API_PASSWORD> variable with the password of your Wazuh manager API user.

   The output of the command is as follows:

   {
      "message": "Group 'Linux' created.",
      "error": 0
   }
   

merged.mg

When a Wazuh agent is enrolled in the Wazuh manager for the first time, the Wazuh manager generates a merged.mg file based on the Wazuh agent's configuration and group membership. Whenever the Wazuh agent's configuration or group membership changes, the Wazuh manager updates the merged.mg file and sends it to the Wazuh agent.

The merged.mg file plays a role in automatic re-assignment of agents to their original groups after re-enrollment (with the remoted.guess_agent_group=1 option enabled). The checksum of the merged.mg file is used for comparison with other agents to determine the appropriate group.

On the Wazuh manager, the file is located at var/wazuh-manager/etc/shared/<GROUP_NAME>/merged.mg.

On the Wazuh agent, it is located at /var/ossec/etc/shared/merged.mg for Linux and C:\Program Files (x86)\ossec-agent\shared\merged.mg on Windows.

Assign multiple groups to a Wazuh agent

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

• Using the Wazuh manager API

• Using the CLI (agent_groups tool)

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

{
   "data": {
      "affected_items": [
         "012"
      ],
      "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/012/group/apache?pretty=true" -H  "Authorization: Bearer $TOKEN"

{
   "data": {
      "affected_items": [
         "012"
      ],
      "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=012&select=group" -H  "Authorization: Bearer $TOKEN"

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

$ /var/wazuh-manager/bin/agent_groups -a -i 016 -g webserver

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

$ /var/wazuh-manager/bin/agent_groups -a -i 001 -g apache

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

List 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/wazuh-manager/bin/agent_groups tool:

# /var/wazuh-manager/bin/agent_groups -l -g webserver

Output

root@manager:/var/wazuh-manager/bin# /var/wazuh-manager/bin/agent_groups -l -g webserver
2 agent(s) in group 'webserver':
  ID: 012  Name: Ubuntu.
  ID: 016  Name: CentOS.

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

# /var/wazuh-manager/bin/agent_groups -s -i 012

Output

The agent 'Ubuntu' with ID '012' belongs to groups: default, webserver, 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.

Make 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 012 from the apache group:

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

Output

Agent '012' removed from apache.

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

# /var/wazuh-manager/bin/agent_groups -s -i 012

Output

The agent 'Ubuntu' with ID '012' belongs to groups: default, webserver.

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

# /var/wazuh-manager/bin/agent_groups -s -i 012

Output

The agent 'Ubuntu' with ID '012' belongs to groups: default, webserver.

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

# /var/wazuh-manager/bin/agent_groups -a -f -i 012 -g apache

Output

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

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

# /var/wazuh-manager/bin/agent_groups -s -i 012

Output

The agent 'Ubuntu' with ID '012' belongs to groups: 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.