From e3eef04970dfa6846c4d5c5ec1d32e4419593430 Mon Sep 17 00:00:00 2001 From: Ad Schellevis Date: Wed, 16 Aug 2023 21:15:50 +0200 Subject: [PATCH] add wazuh-agent documentation --- source/manual/wazuh-agent.rst | 173 ++++++++++++++++++++++++++++++++++ source/plugins.rst | 1 + 2 files changed, 174 insertions(+) create mode 100644 source/manual/wazuh-agent.rst diff --git a/source/manual/wazuh-agent.rst b/source/manual/wazuh-agent.rst new file mode 100644 index 00000000..134b9fa7 --- /dev/null +++ b/source/manual/wazuh-agent.rst @@ -0,0 +1,173 @@ +========================== +Wazuh Agent +========================== + +-------------------------------------- +Introduction +-------------------------------------- + +`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. + +.. Note:: + 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 `__ + + +.. Warning:: + 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 +-------------------------------------- + +Installation of this plugin is rather easy, go to :menuselection:`System --> Firmware --> Plugins` and search for **os-wazuh-agent**, +use the [+] button to install it. + +Next go to :menuselection:`Services --> Wazuh Agent --> Settings` to configure the service. + + +-------------------------------------- +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. + +.. Note:: + Wazuh only supports `rfc3164 `__ formatted syslog messages, for that reason + we record a copy of the requested events into a file named :code:`/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 :code:`/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: + +.. code-block:: xml + :linenos: + :caption: /usr/local/opnsense/service/templates/OPNsense/WazuhAgent/ossec_config.d/099-my-feed.conf + + + json + /path/to/my/file.json + + + +-------------------------------------- +Use active responses +-------------------------------------- + +Wazuh supports `active responses `__ +so the manager can direct defensive actions when needed. The plugin ships with one action named :code:`opnsense-fw` to +drop traffic from a specified source address. + +.. Note:: + + 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. + +.. code-block:: xml + :linenos: + :caption: /var/ossec/etc/ossec.conf + + + + opnsense-fw + opnsense-fw + yes + + + +After which you can use it in active-response rules, like this: + +.. code-block:: xml + :linenos: + :caption: /var/ossec/etc/ossec.conf + + + + no + opnsense-fw + defined-agent + 001 + 100201 + 180 + + + + +The official `documentation `__ +contains more information about the options available. + +.. Tip:: + Active responses are logged into :menuselection:`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 :menuselection:`Wazuh --> Tools --> API console`. +Executing the :code:`opnsense-fw` command for address :code:`172.16.1.30` on agent :code:`001` can be done using: + +.. code-block:: xml + :linenos: + + PUT /active-response?agents_list=001 + { + "command": "!opnsense-fw", + "custom": false, + "alert": { + "data": { + "srcip": "172.16.1.30" + } + } + } + + +.. Tip:: + + 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 :code:`/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 :menuselection:`Wazuh --> Tools --> Ruleset test` menu item in the manager offers an easy to use tool to inspect log +events. + diff --git a/source/plugins.rst b/source/plugins.rst index 6e8523b9..b9f03191 100644 --- a/source/plugins.rst +++ b/source/plugins.rst @@ -81,6 +81,7 @@ Other manual/how-tos/mailgateway manual/git-backup manual/relayd + manual/wazuh-agent ---------------- Reporting