Wazuh Agent


Wazuh is an open source unified XDR (Extended Detection and Response) and SIEM (Security Information en Event Management) system capable of offering protection for endpoints and cloud workloads.

The Wazuh architecture is based on agents, running on the monitored endpoints, which collect information and are capable of executing active responses directed by the manager.

The goal of this plugin is to offer an easily installable plugin to connect to the Wazuh manager.


The scope of Wazuh on OPNsense is only to offer configurable agent support. We do not plan nor advise to run the Wazuh central components on OPNsense. Detailed information on how to install these on supported platforms are available directly from the Wazuh website or you can use their cloud based offering available here


This plugin is provided “as-is” and with very limited [tier 3] community support from the OPNsense team. Using a SIEM/XDR system requires knowledge which usually is out of the (free) community support scope.


Installation of this plugin is rather easy, go to System ‣ Firmware ‣ Plugins and search for os-wazuh-agent, use the [+] button to install it.

Next go to Services ‣ Wazuh Agent ‣ Settings to configure the service.


When the ossec log offers too limited insights when debugging issues, try to increase the debug level. You can find this setting under General settings when “advanced mode” is enabled.

Connecting the agent

To connect the agent to the manager, just fill in a hostname under General Settings/Manager hostname, make sure the agent is marked enabled and optionally specify a connect password under Authentication/Password.

Next go to the manager to see if the agent registered itself.

Selecting which logs to ingest

Our Wazuh agent plugin supports syslog targets like we use in the rest of the product, so if an application sends its feed to syslog and registers the application name as described in our development documentation it can be selected to send to Wazuh as well.

For Intrusion detection we can send the events as well using the same (eve) datafeed used in OPNsense, just mark the Intrusion detection events in the general settings.


Wazuh only supports rfc3164 formatted syslog messages, for that reason we record a copy of the requested events into a file named /var/ossec/logs/opnsense_syslog.log using that format.

Installing custom ossec.conf entries

Some Wazuh modules are directly selectable from the gui, but when a feature is needed, which is not offered in the plugin, it’s possible to add static sections manually.

You can add these in /usr/local/opnsense/service/templates/OPNsense/WazuhAgent/ossec_config.d/, for example, to add a custom json feed, add a file containing the following content in there:

2  <log_format>json</log_format>
3  <location>/path/to/my/file.json</location>

Use active responses

Wazuh supports active responses so the manager can direct defensive actions when needed. The plugin ships with one action named opnsense-fw to drop traffic from a specified source address.


The opnsense-fw action is stateful and can add and delete addresses from the firewall, more context on these type of actions can be found in the Wazuh documentation.

To use this action, you need to add some configuration in the manager, starting with the definition of this action.

2  <command>
3    <name>opnsense-fw</name>
4    <executable>opnsense-fw</executable>
5    <timeout_allowed>yes</timeout_allowed>
6  </command>

After which you can use it in active-response rules, like this:

 2  <active-response>
 3    <disabled>no</disabled>
 4    <command>opnsense-fw</command>
 5    <location>defined-agent</location>
 6    <agent_id>001</agent_id>
 7    <rules_id>100201</rules_id>
 8    <timeout>180</timeout>
 9  </active-response>

The official documentation contains more information about the options available.


Active responses are logged into Services ‣ Wazuh Agent ‣ Logfile / active-responses, including the messages received from the manager.

To quickly test if an active-response can be executed on the agent, we advise to use the API console under Wazuh ‣ Tools ‣ API console. Executing the opnsense-fw command for address on agent 001 can be done using:

 1PUT /active-response?agents_list=001
 3  "command": "!opnsense-fw",
 4  "custom": false,
 5  "alert": {
 6    "data": {
 7      "srcip": ""
 8    }
 9  }


Wazuh offers quite some proof of concept documents and blog posts, like this document explaining how Suricata and Wazuh can be combined to respond to detected threats.

Test rule detection

In case log entries are being collected in /var/ossec/logs/opnsense_syslog.log and no events are being collected in the Manager, it’s usually a good idea to check how Wazuh processes these lines.

The Wazuh ‣ Tools ‣ Ruleset test menu item in the manager offers an easy to use tool to inspect log events.