imported>TechCorner-Redaktion: Neuer Artikel: Wazuh-Agent-Plugin (os-wazuh-agent 1.3, Agent 4.14), Stand OPNsense 26.7

2026-10-06T00:00:00Z

Neuer Artikel: Wazuh-Agent-Plugin (os-wazuh-agent 1.3, Agent 4.14), Stand OPNsense 26.7

Neue Seite

{{Steckbrief
| gilt_fuer = OPNsense 26.1/26.7 mit Plugin os-wazuh-agent 1.3 (Wazuh-Agent 4.14), Wazuh-Manager im eigenen Netz oder Wazuh Cloud
| bereich = IT-Security
| dauer = ca. 30 Minuten (Anbindung), Active Response zusätzlich ca. 30 Minuten
| rechte = Administrator (OPNsense-WebUI), Zugriff auf den Wazuh-Manager
| stand = Oktober 2026
}}
'''Wazuh''' ist eine Open-Source-Plattform für '''[[SIEM]] und XDR''' (Security Information and Event Management bzw. Extended Detection and Response). Mit dem Plugin '''os-wazuh-agent''' wird die OPNsense ein vollwertiger Wazuh-Agent: Sie übermittelt Firewall-, System- und Dienstprotokolle sowie '''Suricata-Alarme''' an den Wazuh-Manager, wird per '''Dateiintegritätsüberwachung''' und '''Rootcheck''' überwacht, liefert ein '''Systeminventar''' – und kann vom Manager per '''Active Response''' angewiesen werden, Angreifer-IP-Adressen auf der Firewall zu sperren. So wird die Firewall vom reinen Logsender zum aktiven Baustein der Angriffserkennung.

== Agent statt Syslog: Was bringt das Plugin? ==
{| class="wikitable"
! Funktion !! Klassisches Syslog an Wazuh !! os-wazuh-agent
|-
| Firewall- und Dienstlogs || ja || ja – Auswahl pro Anwendung, normiertes RFC3164-Format
|-
| Suricata-Alarme (EVE JSON) || eingeschränkt || ja, als strukturierte JSON-Events
|-
| Dateiintegritätsüberwachung (FIM) || nein || ja
|-
| Rootcheck / Anomalieerkennung || nein || ja
|-
| Systeminventar (Pakete, Ports, Netzwerk) || nein || ja (Syscollector)
|-
| Active Response (IP sperren) || nein || ja (Aktion ''opnsense-fw'')
|-
| Verschlüsselte, authentifizierte Übertragung || nein (UDP/TCP-Klartext) || ja
|}

[[Datei:OPNsense-Wazuh-Agent.png|thumb|center|750px|OPNsense als Wazuh-Agent: Logs, Suricata-Events, Integritäts- und Inventardaten gehen verschlüsselt an den Wazuh-Manager; dieser kann per Active Response die Aktion opnsense-fw auslösen und Angreifer-IPs auf der Firewall sperren.]]

{{Hinweis|Das Plugin bringt nur den '''Agent'''. Die zentralen Wazuh-Komponenten (Manager, Indexer, Dashboard) gehören '''nicht''' auf die OPNsense, sondern auf eigene Server oder in die Wazuh Cloud. Das Plugin wird vom OPNsense-Team mit eingeschränktem Community-Support (Tier 3) bereitgestellt.}}

== Voraussetzungen ==
* Ein laufender '''Wazuh-Manager''' (z. B. Wazuh 4.14 on-premises oder Wazuh Cloud).
* '''Versionen beachten:''' Der Agent darf nicht neuer sein als der Manager. Das Plugin bringt derzeit den Wazuh-Agent der 4.14-Reihe mit; bei einem Manager der 5.x-Reihe die Kompatibilität mit 4.x-Agents in der Wazuh-Dokumentation prüfen.
* Netzwerkverbindung von der Firewall zum Manager: '''TCP 1514''' (Ereignisse) und '''TCP 1515''' (Registrierung/Enrollment).

== Schritt 1: Plugin installieren ==
'''System → Firmware → Plugins''': '''os-wazuh-agent''' installieren und die Seite neu laden. Das Menü befindet sich unter '''Services → Wazuh Agent''' mit ''Settings'', ''Logfile / ossec'' und ''Logfile / active-responses''.

== Schritt 2: Verbindung zum Manager ==
'''Services → Wazuh Agent → Settings''' (bei Bedarf ''advanced mode'' aktivieren):
{| class="wikitable"
! Bereich !! Feld !! Empfehlung
|-
| General Settings || '''Enable''' || aktivieren
|-
| || '''Manager hostname''' || IP oder DNS-Name des Wazuh-Managers, z. B. <code>wazuh.firma.local</code>
|-
| || '''Agent hostname''' || sprechender Name, z. B. <code>fw-zentrale</code> (leer = Hostname der Firewall)
|-
| || '''Protocol''' / '''Manager port''' || TCP / 1514 (Standard)
|-
| || '''Debug''' || nur zur Fehlersuche erhöhen
|-
| Enrollment || '''Password''' || Registrierungspasswort des Managers (falls dort Passwort-Enrollment aktiviert ist)
|-
| || '''Enrollment port''' || 1515 (Standard)
|}
'''Apply''' – der Agent registriert sich beim Manager. Im Wazuh-Dashboard unter ''Agents'' erscheint die Firewall als ''active''. Probleme zeigt ''Services → Wazuh Agent → Logfile / ossec''.

== Schritt 3: Welche Logs gesendet werden ==
{| class="wikitable"
! Feld !! Empfehlung
|-
| '''Applications''' || die relevanten Syslog-Quellen auswählen, z. B. ''filter'' (Firewall-Log), ''audit''/''configd''/Anmeldungen der Weboberfläche, ''openvpn'', ''charon'' (IPsec), ''unbound'', ''haproxy'', ''caddy'', ''squid'' … – je nachdem, was auf der Firewall läuft
|-
| '''Intrusion detection events''' || aktivieren, wenn Suricata (''Services → Intrusion Detection'') läuft – die EVE-Events kommen strukturiert als JSON beim Manager an
|-
| '''Logcollector remote commands''' || '''deaktivieren''' (Standard: an) – verhindert, dass der Manager über die zentrale Konfiguration beliebige Befehle als Logquelle auf der Firewall ausführt
|}
Wazuh verarbeitet Syslog im Format RFC3164. Das Plugin schreibt deshalb eine Kopie der ausgewählten Meldungen in <code>/var/ossec/logs/opnsense_syslog.log</code> und liest sie von dort ein.

{{Hinweis|Das Firewall-Log (''filter'') kann je nach Regelwerk sehr viele Ereignisse erzeugen. Nur Regeln mit ''Log'' versehen, deren Treffer wirklich ausgewertet werden sollen (z. B. Block-Regeln, Zugriffe auf Management-Dienste), und im Manager die Indexgröße im Blick behalten.}}

== Schritt 4: Integritäts- und Systemüberwachung ==
{| class="wikitable"
! Bereich !! Standard !! Wirkung
|-
| '''Policy monitoring and anomaly detection''' (Rootcheck) || an || Prüft auf Rootkits, verdächtige Dateien und Richtlinienverstöße
|-
| '''System inventory''' (Syscollector) || an || Meldet installierte Pakete, offene Ports, Netzwerkschnittstellen und Hardware – Grundlage für Schwachstellenerkennung im Manager
|-
| '''File integrity monitoring''' (Syscheck) || an || Meldet Änderungen an Systemdateien und Konfigurationen, z. B. <code>/conf/config.xml</code>
|}
Die Standardwerte können in der Regel übernommen werden. Bei vielen Fehlmeldungen nach Firmware-Updates die Ereignisse im Manager entsprechend bewerten bzw. unterdrücken.

== Schritt 5: Active Response – Angreifer automatisch sperren ==
Das Plugin bringt die Aktion '''opnsense-fw''' mit: Der Manager kann damit eine Quell-IP auf der Firewall für eine bestimmte Zeit sperren – etwa nach Brute-Force-Versuchen auf die Weboberfläche, nach Suricata-Alarmen oder nach Angriffen auf einen Webserver, den der Manager per Agent überwacht.

=== Auf der OPNsense ===
Bereich '''Active response''':
* '''Enable''' aktivieren.
* '''Firewall command ignore''': einen Alias mit Adressen auswählen, die '''nie''' gesperrt werden dürfen – eigene Netze, Admin-PCs, VPN-Netze, Monitoring, wichtige Partner. Das verhindert, dass Fehlalarme die eigene Infrastruktur aussperren.
* '''Repeated offenders''': steigende Sperrzeiten in Minuten für Wiederholungstäter, z. B. <code>30,60,120,240</code>.
* '''Wazuh remote commands''': deaktiviert lassen, sofern keine zentral verteilten Befehle benötigt werden.

=== Auf dem Wazuh-Manager ===
In <code>/var/ossec/etc/ossec.conf</code> die Aktion definieren und einer oder mehreren Regeln zuordnen:
<syntaxhighlight lang="xml">
<ossec_config>
<command>
<name>opnsense-fw</name>
<executable>opnsense-fw</executable>
<timeout_allowed>yes</timeout_allowed>
</command>

<active-response>
<disabled>no</disabled>
<command>opnsense-fw</command>
<location>defined-agent</location>
<agent_id>001</agent_id> 
<rules_id>87702</rules_id> 
<timeout>180</timeout> 
</active-response>
</ossec_config>
</syntaxhighlight>
Mit <code>location</code> ''defined-agent'' wird die Sperre immer auf der Firewall ausgeführt – auch wenn das auslösende Ereignis von einem anderen Agent (z. B. einem Webserver) stammt. Die Regel-IDs passend zum eigenen Szenario wählen (z. B. Brute-Force-Korrelationen, Webangriffs- oder Suricata-Regeln).

=== Testen ===
Im Wazuh-Dashboard unter ''Tools → API console'' (Agent-ID und Test-IP anpassen):
<syntaxhighlight lang="text">
PUT /active-response?agents_list=001
{
"command": "!opnsense-fw",
"custom": false,
"alert": { "data": { "srcip": "172.16.1.30" } }
}
</syntaxhighlight>
Ausgeführte Aktionen zeigt '''Services → Wazuh Agent → Logfile / active-responses'''.

== Eigene Logquellen ergänzen ==
Für Logquellen, die nicht in der Oberfläche angeboten werden, können eigene <code>ossec.conf</code>-Abschnitte als Datei in <code>/usr/local/opnsense/service/templates/OPNsense/WazuhAgent/ossec_config.d/</code> abgelegt werden, z. B. <code>099-eigener-feed.conf</code>:
<syntaxhighlight lang="xml">
<localfile>
<log_format>json</log_format>
<location>/pfad/zur/datei.json</location>
</localfile>
</syntaxhighlight>
Danach in der Oberfläche ''Apply'' ausführen. Eigene Dateien bei Plugin-Updates und Firmware-Wechseln sichern.

== Ereignisse im Manager auswerten ==
* Kommen Ereignisse in <code>/var/ossec/logs/opnsense_syslog.log</code> an, aber nicht als Alarme im Dashboard, im Manager unter ''Tools → Ruleset test'' prüfen, wie die Zeilen dekodiert werden.
* Für OPNsense-spezifische Logs sind teilweise eigene Decoder und Regeln nötig – Beispiele und Lösungen für typische Stolperfallen finden sich in den Wazuh-Artikeln dieses Wikis (siehe unten).
* Bewährte Anwendungsfälle: fehlgeschlagene Anmeldungen an Weboberfläche und VPN, Konfigurationsänderungen, neue Admin-Konten, Suricata-Alarme mit hoher Priorität, blockierte Verbindungen zu Threat-Intelligence-Listen (z. B. [[OPNsense - Q-Feeds Threat Intelligence|Q-Feeds]]).

== Sicherheitsempfehlungen ==
* '''Logcollector remote commands''' und '''Wazuh remote commands''' deaktivieren, wenn sie nicht benötigt werden.
* '''Ignore-Alias''' für Active Response konsequent pflegen und Sperrzeiten begrenzen – eine fehlerhafte Regel darf nicht zum Selbst-DoS führen.
* Verbindung zum Manager über ein internes bzw. VPN-Netz führen; Enrollment per Passwort absichern.
* Agent und Manager aktuell halten (Versionsreihenfolge beachten).
* Für den Betrieb: Speicherbedarf des Indexers, Aufbewahrungsfristen und Alarmierung planen – siehe [[NIS2 und Wazuh]].

== Typische Probleme ==
{| class="wikitable"
! Symptom !! Lösung
|-
| Agent erscheint nicht im Manager || Erreichbarkeit TCP 1514/1515 prüfen, Enrollment-Passwort, Manager-Hostname; ''Logfile / ossec'' auswerten, ggf. Debug erhöhen.
|-
| Agent ''disconnected'' nach Update || Agent neuer als Manager – Manager aktualisieren.
|-
| Keine Firewall-Events || Anwendung ''filter'' nicht ausgewählt oder Regeln ohne Logging.
|-
| Events kommen an, aber keine Alarme || Decoder/Regeln im Manager fehlen – ''Ruleset test'' nutzen, eigene Decoder anlegen.
|-
| Active Response greift nicht || Command/Active-Response im Manager nicht definiert, falsche Agent-ID, Quell-IP im Ignore-Alias, Active Response auf der OPNsense nicht aktiviert.
|}

== Fazit ==
Mit os-wazuh-agent fügt sich die OPNsense nahtlos in eine Wazuh-SIEM/XDR-Umgebung ein: verschlüsselte Logübertragung, Suricata-Events, Integritätsüberwachung, Inventar – und mit Active Response die Möglichkeit, erkannte Angreifer automatisch an der Firewall zu stoppen. Mit sauber gewählten Logquellen, deaktivierten Fernbefehlen und einer gepflegten Ausnahmeliste ist das ein starker Baustein für Angriffserkennung und NIS2-konforme Protokollierung.

== Unterstützung von m.a.x. it ==
Sie möchten Ihre OPNsense-Firewalls an Wazuh anbinden, Decoder und Regeln für Ihre Umgebung entwickeln oder Active Response sicher einführen? m.a.x. it betreibt Wazuh-Umgebungen für Unternehmen – mit einem [https://www.max-it.de/it-services/siem-open-source/ Open-Source-SIEM auf Wazuh-Basis] bzw. als [https://www.max-it.de/it-services/managed-siem/ Managed SIEM von m.a.x. it] sowie mit [https://www.max-it.de/it-services/opnsense/ OPNsense-Firewall-Services].

== Siehe auch ==
* [[NIS2 und Wazuh]]
* [[OPNsense-WebGUI-Login-Logs korrekt dekodieren: Wenn der Solaris-Decoder dazwischenfunkt]]
* [[PfSense-Logs in Wazuh: Custom Decoder für fehlenden Hostnamen im BSD-Syslog-Format]]
* [[Wazuh-Agent meldet „agent buffer is full at 90%“: Ursachenanalyse und saubere Entlastung]]
* [[Wazuh-Korrelation für Brute-Force über mehrere Systeme: Warum nicht triggert – und wie du es stabil löst]]
* [[OPNsense - Q-Feeds Threat Intelligence]]
* [[OPNsense - Maltrail Erkennung von Schadverkehr]]
* [[SIEM]]
* [[Suricata]]

== Links und Quellen ==
* [https://docs.opnsense.org/manual/wazuh-agent.html OPNsense-Doku – Wazuh Agent]
* [https://documentation.wazuh.com/current/user-manual/capabilities/active-response/index.html Wazuh-Doku – Active Response]
* [https://github.com/opnsense/plugins/tree/master/security/wazuh-agent Quellcode und Changelog des Plugins os-wazuh-agent]
* [https://www.max-it.de/it-services/siem-open-source/ m.a.x. it – SIEM Open Source]

{{Uebermax}}
[[Kategorie:IT-Security]]
[[Kategorie:Wazuh]]

OPNsense - Wazuh-Agent - Versionsgeschichte

imported>TechCorner-Redaktion: Neuer Artikel: Wazuh-Agent-Plugin (os-wazuh-agent 1.3, Agent 4.14), Stand OPNsense 26.7