Wazuh Agent Fleet Management at Scale: Groups, Centralized Config & Upgrades

Managing 20 Wazuh agents by hand is fine. Managing 2,000 by hand is impossible. The trick is to treat the fleet like cattle: agents are members of groups, groups own configuration, and individual agents are interchangeable.

1. Design your group taxonomy first

A good rule: 3 dimensions, not more. We typically use os, environment and role:

• os: linux, windows, macos
• env: prod, staging, dev
• role: web, db, k8s-node, workstation, dmz

An agent can belong to multiple groups. linux,prod,web is a clean, queryable label.

2. Create groups + centralized agent.conf

sudo /var/ossec/bin/agent_groups -a -g linux-prod-web -q
sudoedit /var/ossec/etc/shared/linux-prod-web/agent.conf

Any settings in that agent.conf (SCA policies, FIM directories, wodles) push automatically to every member, no SSH, no Ansible needed for config drift.

3. Automate enrollment

Bake the registration into your image / cloud-init / GPO. Use enrollment passwords so rogue boxes cannot self-register:

WAZUH_MANAGER="manager.internal" \
WAZUH_AGENT_GROUP="linux-prod-web" \
WAZUH_REGISTRATION_PASSWORD="$(cat /etc/wazuh/enroll.pw)" \
apt-get install -y wazuh-agent

The agent picks up the group on first enrollment, no manual assignment.

4. Inventory + drift detection

Query the API daily to spot drift, agents in the wrong group, stale heartbeats, version mismatch:

curl -k -H "Authorization: Bearer $T" \
  "https://manager:55000/agents?status=disconnected&pretty=true"

Pipe the JSON into a daily Slack/email report. Any agent stale > 24h gets investigated.

5. Rolling upgrades

Never upgrade an entire fleet at once. The supported pattern:

1. Upgrade the manager first (test in staging).
2. Upgrade 5% of agents via the API agent-upgrade endpoint.
3. Watch for crashes / disconnections for 24h.
4. Roll the remaining 95% in batches of 20%.

curl -k -H "Authorization: Bearer $T" -X PUT \
  "https://manager:55000/agents/upgrade?agents_list=001,002,003"

6. Decommissioning

Remove dead agents weekly, they pollute dashboards and skew alert counts:

sudo /var/ossec/bin/manage_agents -r 042

Track 3 fleet KPIs

• % agents active in last 24h (target > 98%).
• % agents on current minor version (target > 95% within 30 days of release).
• % agents in a group (target 100%, ungrouped agents are config debt).