Key Takeaways
- Enrollment is the hard part at scale. Manual key copying does not scale past a handful of agents. Use the enrollment daemon (authd) with a password or certificate so agents self-register on first boot.
- Agent groups drive centralised configuration. Assign agents to groups (by OS, role or location) and push shared
agent.confso you manage policy per group, not per endpoint. - Each platform has a native mass-deployment path: Group Policy or Intune for Windows, Ansible or a config-management tool for Linux, and an MDM for macOS. Use the channel you already own.
- Version drift is the silent killer. Agents older than the manager mostly work, but new detection features and bug fixes assume current agents. Plan staged, group-by-group upgrades.
- Fleet health needs active governance: monitor for disconnected and never-connected agents, prune stale registrations, and alert when coverage drops, or your SIEM quietly goes blind on parts of the estate.
Enrollment: The Real Bottleneck at Scale
Every Wazuh agent must register with the manager before it can send data, and registration produces a unique key stored in client.keys on both sides. For a lab you can generate a key on the manager, copy it to the agent and start the service. That manual flow collapses immediately at fleet scale, because copying keys to two thousand endpoints by hand is neither feasible nor auditable.
The scalable answer is the enrollment daemon, authd, which lets agents self-register over the network on first start. You enable authd on the manager and configure an enrollment method: a shared enrollment password, or, for higher assurance, certificate-based enrollment where each agent presents a certificate signed by a trusted CA. The agent contacts the manager on the enrollment port (1515 by default), authenticates, receives its key automatically and immediately begins reporting on the data port (1514).
Password enrollment is simple to roll out but the password is a shared secret you must protect and rotate. Certificate enrollment is more work to set up but binds enrollment to your PKI, lets you revoke individual agents, and avoids a single shared secret across the estate. For regulated environments certificate enrollment is the defensible choice; for a fast SMB rollout, password enrollment with a rotated secret is usually acceptable.
Bake enrollment into the install. The deployment package or script should install the agent, write the manager address and enrollment credential, and start the service so that registration happens automatically the first time the endpoint comes online. Done correctly, onboarding a new machine requires zero manual SOC action: the agent appears in the manager, lands in its default group and starts reporting within minutes.
Agent Groups and Centralised Configuration
An agent's local configuration can be set on the endpoint, but managing per-endpoint config across a fleet is unsustainable. Wazuh solves this with agent groups and centralised configuration. You define groups on the manager, assign each agent to one or more groups, and place a shared agent.conf in each group's directory. The manager pushes that configuration to every member automatically.
Design your group taxonomy deliberately. The most useful dimensions are operating system (Windows servers, Linux servers, workstations, macOS), role (domain controllers, web servers, database servers, developer laptops) and sometimes location or business unit for regulatory or retention reasons. An agent can belong to several groups, and configuration merges, so a Windows database server can inherit both the Windows baseline and the database-server policy.
Centralised configuration is what makes group design pay off. File integrity monitoring paths, log file locations, security configuration assessment policies, vulnerability detection settings and active-response scoping all live in the group agent.conf. When you decide every Linux web server should monitor a new log path, you edit one file and the manager distributes it to the whole group on the next agent check-in. No per-host edits, no drift.
Keep the default group lean and explicit. Newly enrolled agents land in the default group, so its configuration should be a safe minimum baseline. A common operational discipline is to alert whenever an agent has been sitting in the default group for more than a short window, because that usually means someone forgot to assign it to its proper role group and it is running with incomplete monitoring policy.
Need a Managed SOC Without Splunk-Level Costs?
Codesecure designs, deploys and operates open-source SOC stacks built on Wazuh, n8n, TheHive, Cortex and MISP for businesses across India, Singapore, UAE and Malaysia. ISO/IEC 27001:2022 certified delivery, named OSCP and CISSP analysts, fixed-price proposals.
See SOC Services →Mass Deployment per Platform: Windows, Linux, macOS
There is no single best way to deploy agents because each operating system has a mature management channel you should reuse rather than reinvent. The principle is the same everywhere, push the installer with the manager address and enrollment credential pre-set, but the mechanics differ by platform.
On Windows, the native channels are Group Policy software installation or a modern endpoint manager such as Microsoft Intune or SCCM. Package the MSI with the manager address and enrollment password as MSI properties so the agent self-registers on install. Group Policy is the path of least resistance in an Active Directory estate; Intune suits cloud-managed and remote fleets. Either way the agent is deployed silently and reports within minutes of the policy applying.
On Linux, configuration management is the right tool: Ansible, Puppet, Salt or Chef. An Ansible role that adds the Wazuh repository, installs the agent package, templates ossec.conf with the manager address and enrollment credential, and enables the service gives you idempotent, repeatable deployment across hundreds of hosts. The same role doubles as your upgrade and configuration-drift remediation mechanism, which is a major operational advantage.
On macOS, the agent installs from a PKG and the scalable channel is your Mobile Device Management platform (Jamf, Kandji, Intune for Mac). Push the PKG with a configuration profile that supplies the manager address and credential. macOS adds a wrinkle: the agent needs Full Disk Access granted via an MDM privacy preferences profile to monitor protected paths, so include that profile in the deployment or file integrity monitoring will silently miss files. Plan the long tail too: laptops with intermittent connectivity will trickle in over two to four weeks after the bulk rollout completes.
Agent Upgrades and Version Management
Wazuh maintains backward compatibility so an older agent generally keeps reporting to a newer manager, which tempts teams into never upgrading agents. That is a slow trap. New detection content, bug fixes, performance improvements and security patches assume current agents, and a fleet spread across many versions becomes hard to reason about when you are tuning rules or chasing a detection gap.
Wazuh offers a remote upgrade capability: the manager can push a new agent version to selected agents over the existing secure channel using the agent_upgrade tooling, without touching the endpoint by hand. This is convenient for servers and always-on hosts. For laptops and managed endpoints, driving the upgrade through the same channel you used to deploy, Intune, Ansible, Jamf, is often more reliable because it respects maintenance windows and reporting.
Stage upgrades by group rather than upgrading everything at once. Upgrade a small canary group first, confirm agents reconnect and continue reporting normally and that no detection regressions appear, then roll the upgrade out group by group. This contains the blast radius if a new agent version behaves unexpectedly in your environment, and it lets you pause if something looks wrong.
Always upgrade the manager and indexer before the agents, never the other way around. A newer agent reporting to an older manager is the unsupported direction and can produce subtle parsing or compatibility issues. Keep a documented version policy, for example agents no more than one minor version behind the manager, and report against it so version drift is visible and actively managed rather than discovered during an incident.
Fleet Health: Disconnected, Stale and Never-Connected Agents
A deployed agent is not the same as a working agent. Endpoints get decommissioned, reimaged, firewalled, powered off or simply break, and every one of those events creates an agent that is registered but not reporting. If you do not actively watch for this, your monitoring coverage degrades silently and you only discover the gap when an incident happens on a host that stopped sending data three weeks ago.
Wazuh classifies agents by connection state: active, disconnected, pending and never-connected. Build operational alerting around these states. An agent that flips to disconnected and stays there is either a dead endpoint to be cleaned up or a real coverage gap to investigate. A never-connected agent means enrollment succeeded but the agent never reported, often a firewall rule blocking the data port or a service that failed to start.
Prune stale registrations on a schedule. Decommissioned endpoints leave behind registrations that clutter the manager, consume agent IDs and distort coverage metrics. A regular cleanup, automated through the Wazuh API and gated so it only removes agents disconnected beyond a defined threshold, keeps the fleet accurate. Always alert before deleting, so a genuinely important host that simply went quiet is investigated rather than silently removed.
Treat coverage as a first-class metric. Track the ratio of active agents to the known asset inventory and alert when it drops below a threshold, because a falling ratio is an early signal of a deployment failure, a network change or a configuration push that broke connectivity. The mature operational posture is to reconcile the Wazuh agent list against your authoritative asset inventory regularly, so that every asset that should have an agent does, and every agent maps to a real asset.
Frequently Asked Questions
How do I deploy Wazuh agents to thousands of endpoints?
Use the enrollment daemon (authd) so agents self-register on first start, and push the installer through the management channel you already own: Group Policy or Intune for Windows, Ansible or another config-management tool for Linux, and an MDM such as Jamf for macOS. Bake the manager address and enrollment credential into the install package so registration is automatic and no SOC analyst has to touch each endpoint.
What is the difference between password and certificate enrollment?
Password enrollment uses a shared secret that every agent presents to register, which is simple to roll out but must be protected and rotated. Certificate enrollment binds registration to your PKI: each agent presents a certificate signed by a trusted CA, which lets you revoke individual agents and avoids a single shared secret. Certificate enrollment is the more defensible choice for regulated environments; password enrollment is usually acceptable for a fast SMB rollout.
How do agent groups work in Wazuh?
You define groups on the manager and assign each agent to one or more of them, typically by operating system, role or location. Each group has a shared agent.conf that the manager pushes to all members, so you manage file integrity monitoring paths, log sources, security configuration assessment policies and other settings per group rather than per endpoint. An agent can belong to several groups and their configurations merge.
Do I need to upgrade Wazuh agents, or can older versions keep running?
Older agents generally keep reporting to a newer manager, but you should still upgrade. New detection content, bug fixes and security patches assume current agents, and large version spread makes the fleet hard to reason about. Always upgrade the manager and indexer before the agents, stage upgrades group by group starting with a canary, and keep a version policy such as agents no more than one minor version behind the manager.
How do I find Wazuh agents that have stopped reporting?
Wazuh classifies agents as active, disconnected, pending or never-connected. Alert on agents that flip to disconnected and stay there (a dead endpoint or a real coverage gap) and on never-connected agents (usually a blocked data port or a service that failed to start). Reconcile the agent list against your asset inventory regularly and track the ratio of active agents to known assets as a coverage metric.
Can I deploy Wazuh agents on Windows, Linux and macOS the same way?
The principle is the same, push an installer with the manager address and enrollment credential pre-set, but the channel differs per platform: MSI via Group Policy or Intune on Windows, a config-management role such as Ansible on Linux, and a PKG via MDM on macOS. macOS additionally needs Full Disk Access granted through an MDM privacy profile, or file integrity monitoring will silently miss protected paths.
Roll Out Wazuh Across Your Whole Estate, Cleanly
Codesecure deploys and operates Wazuh fleets across Windows, Linux and macOS with automated enrollment, group-based policy, staged upgrades and active coverage monitoring. ISO/IEC 27001:2022 certified delivery, named OSCP and CISSP analysts, fixed-price implementation and managed-SOC retainers across India, Singapore, UAE and Malaysia.
