Monitoring Wazuh agents in Zabbix via the REST API
- Monitoring , Security
- October 24, 2023
Table of Contents
Wazuh is a popular open-source SIEM/XDR: agents on servers and workstations collect logs, file-integrity events and vulnerability data, and send them to the Wazuh manager. It works well — as long as the agents are actually connected.
The catch: when an agent stops reporting, Wazuh doesn’t make much noise about it. The server simply stops sending events, and nobody notices until someone needs those events. A host that is silent in your SIEM is a blind spot, and blind spots are exactly what attackers like.
Most teams already watch their servers with Zabbix. So instead of looking at the Wazuh dashboard every morning, let Zabbix check each agent and raise an alert like for any other problem.
Template: custom-zabbix-templates/wazuh-agent — Zabbix 6.4 and newer, no external scripts.
How it works
The template is linked to the same Zabbix host as the server running the Wazuh agent. Every 10 minutes a Zabbix Script item (JavaScript running on the Zabbix server or proxy):
- authenticates against the Wazuh API with basic auth and obtains a token;
- requests
GET /agents?name=<host name>— the agent whose name matches the Zabbix host name; - returns the agent’s data as JSON.
Two dependent items extract what matters:
| Item | Values |
|---|---|
| Agent status | active, disconnected, pending, never_connected (or unavailable if the agent isn’t found) |
| Agent group config status | synced / not synced |
And triggers fire when something is wrong:
| Trigger | Severity |
|---|---|
| Wazuh Agent Disconnected | Average |
| Wazuh Agent Unavailable (not found in Wazuh) | Average |
| Wazuh Agent Pending | Warning |
| Wazuh Agent Never Connected | Warning |
| Wazuh Agent Config Not Synced | Warning |
| Wazuh Agent No Data (the API check itself stopped working) | Warning |
Status triggers require two consecutive bad values, so a short agent restart doesn’t wake anyone up.
Setup
-
Create an API user in Wazuh with read-only access to agents. Don’t use the admin account — the password is stored in a Zabbix macro.
-
Import the template in Zabbix: Data collection → Templates → Import and select
zabbix-wazuh-agent.json. -
Set the macros — ideally once on a host group or globally rather than on every host:
Macro Example {$WAZUH.API.URL}https://wazuh.example.local:55000{$WAZUH.USER}zabbix-ro{$WAZUH.PASSWORD}(secret macro) {$WAZUH.HTTP.PROXY}optional, e.g. http://proxy:3128{$WAZUH.DATA.TIMEOUT}10(seconds)Mark
{$WAZUH.PASSWORD}as a secret text macro so it is not shown in the UI. -
Link the template to the hosts that run a Wazuh agent.
Warning
The agent is looked up by the visible name of the Zabbix host. If the agent is registered in Wazuh as web01 but the Zabbix host is called web01.example.local, the lookup returns nothing and you get “Wazuh Agent Unavailable”. Keep the names consistent — or rename the host’s visible name in Zabbix.
The Zabbix server (or the proxy that monitors the host) needs network access to the Wazuh API, by default on TCP 55000. If it can only get there through a proxy, set {$WAZUH.HTTP.PROXY}.
Why “never_connected” and “pending” matter
- never_connected usually means an agent was registered (often by an automated deployment) but never started or never reached the manager — a host you think is protected but isn’t.
- pending means the agent registered but the handshake didn’t complete — typically a firewall or certificate issue.
- not synced means the agent hasn’t received its group’s configuration, so it may be running with outdated rules.
All three are easy to miss in the Wazuh UI and obvious in a Zabbix problem list.
Summary
- One template, linked to the hosts you already monitor; no scripts on the hosts.
- Alerts when an agent disconnects, never connected, is stuck in pending or out of sync.
- Use a read-only Wazuh API user and a secret macro for its password.
- Keep Zabbix host names and Wazuh agent names aligned.
Building or tuning a security monitoring setup with Wazuh and Zabbix? Talk to us.
