Grouping agents

Managing multiple groups

• Assigning multiple groups to an agent

• Listing groups and configuration

• Making changes on multiple groups

• Shared files behavior

This capability is focused to customize the agents' configuration with a higher level of granularity. The ThreatLockDown API and agent_groups help to manage groups by listing them and also by allowing to assign/change/unassign groups to agents. Let see three use cases where managing multiple groups over existing agents.

Assigning multiple groups to an agent

Setting multiple groups to an agent is simple. There are three different ways to assign an agent to one or more groups: Registration, CLI and API.

In this example, the agent 001 has been added to webserver and apache groups. First of all, using the ThreatLockDown API endpoint PUT /agents/{agent_id}/group/{group_id}:

# curl -k -X PUT "https://localhost: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://localhost: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,
}

After that, we can ask about groups to which an agent belongs using the ThreatLockDown API endpoint GET /agents:

# curl -k -X GET "https://localhost: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,
}

In this case, the remote configuration for the group apache is the most priority of the three groups when there exist conflicts on any configuration parameter.

With the agent_groups CLI, agents can be registered to groups on the same way:

$ /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'.

To assign the agent to one or more groups during the registration process, register the agent by setting the groups where the agent will be included with the -G option:

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

Listing groups and configuration

It is possible to know agents belonging to groups in real-time, as well as the configuration and shared files applied to each one depending on which groups it belongs.

For example, to list the groups available for now, we could run the following query to agent_groups:

# /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

Same easy to query which groups are assigned to the agent 001:

# /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, being the last one the highest priority one.

Making changes on multiple groups

The same way it is possible to assign multiple groups to agents, it is possible to revert assignments and switch between available groups. Below is shown how to unset the group apache for the agent 001:

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

Group 'apache' unset for agent '001'.

# /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 overwriting 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']'.

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

Group 'apache' set to agent '001'.

# /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 groups assigned to the agent and forces it to only belong to the new group.

Finally, to check the synchronization status of the group configuration for agents, both following methods are available, agent_groups and ThreatLockDown API endpoint GET /agents:

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

Agent '001' is synchronized.

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

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

The rest of the capabilities of agent_groups can be found at its reference section. The same for the ThreatLockDown API, which offers calls with similar behavior.

Shared files behavior

As was explained above, traditionally, the manager shared configuration files with its agents according to the group they belong to.

In the case of belonging to multiple groups, the configuration files of every group are merged into one following the next criteria:

• Shared files such as CIS benchmarks for the rootkit detection are joined in the shared folder. If there were repeated files, the last one added would 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 agent will be the leading one. 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 agents.