Einleitung
Wazuh ist darauf ausgelegt, kontinuierliche Ereignisströme zu verarbeiten – nicht statische Datenbestände. In der Praxis entsteht jedoch häufig die Anforderung, bereits vorhandene Logdateien nachträglich in Wazuh zu integrieren, etwa bei Migrationen, forensischen Analysen oder beim initialen Onboarding neuer Datenquellen. Gerade bei JSON-Logs im NDJSON-Format scheint dies auf den ersten Blick trivial: Datei ablegen, Monitoring aktivieren, fertig. Tatsächlich greift hier jedoch ein grundlegendes Designprinzip der Wazuh-Logverarbeitung, das viele Anwender zunächst überrascht.
Ausgangslage / Problemstellung
Vorliegend sind bereits erzeugte Logdaten in Form von NDJSON-Dateien vorhanden. Diese befinden sich lokal auf dem Wazuh-Manager und sollen nachträglich analysiert werden. Die Konfiguration zur Logüberwachung (localfile) wurde korrekt gesetzt, und Tests mit echo zeigen, dass neu geschriebene Logzeilen problemlos verarbeitet werden. Wird jedoch eine bestehende Datei in das überwachte Verzeichnis verschoben, erfolgt keine Verarbeitung der enthaltenen Logs.
Dieses Verhalten führt häufig zu Verwirrung, insbesondere bei neuen Wazuh-Anwendern, da erwartet wird, dass bestehende Inhalte automatisch eingelesen werden.
Technische Analyse
Der entscheidende Punkt liegt im Verhalten des Wazuh Logcollectors. Dieser arbeitet nicht als klassischer Datei-Parser, sondern als Stream-Listener. Das bedeutet:
- Es werden ausschließlich neue Logeinträge verarbeitet, die nach Aktivierung des Monitorings in eine Datei geschrieben werden.
- Bereits vorhandene Inhalte werden ignoriert.
- Der Logcollector merkt sich intern die Leseposition sowie einen Hash (SHA1) der Datei, um nur neue Daten zu erfassen.
Dieses Verhalten ist bewusst gewählt und verhindert doppelte Verarbeitung sowie Inkonsistenzen in produktiven Logströmen.
Für bestehende Dateien bedeutet das konkret:
- Ein einfaches Verschieben oder Bereitstellen der Datei reicht nicht aus.
- Es erfolgt keine Initialverarbeitung historischer Daten.
Zusätzlich treten bei Versuchen des “Nachladens” (Backfilling) weitere technische Herausforderungen auf:
- Queue-Limitierungen auf Manager-Seite
- Standard: ~1024 Events im Logcollector-Output-Queue
- Bei hoher Last kommt es zu Event-Drops
- Agent-seitige Flood Protection
- Typisch: ~500 Events pro Sekunde
- Überschreitungen führen zu Buffer-Überläufen
- Kein Backpressure-Mechanismus
- Der Logcollector liest kontinuierlich weiter, auch wenn nachgelagerte Queues bereits überlastet sind
- Resultat: stille Eventverluste
Diese Architektur ist für Echtzeitverarbeitung optimiert, nicht für Bulk-Ingestion.
Lösung / Best Practices
1. Backfilling über kontrolliertes Re-Streaming
Der empfohlene und praxiserprobte Ansatz ist das sogenannte Backfilling über Append-Mechanismus:
- Bestehende Logdatei wird nicht direkt überwacht
- Stattdessen wird ihr Inhalt zeilenweise in eine neue, überwachte Datei geschrieben
Beispiel:
cat /var/log/old_logs.json >> /var/log/wazuh_ingest.log
Diese Methode funktioniert, weil Wazuh nur neue Schreibvorgänge erkennt.
2. Rate Limiting zwingend erforderlich
Ein unkontrolliertes Anhängen großer Datenmengen führt nahezu garantiert zu Eventverlusten. Deshalb sollte der Datenstrom gedrosselt werden.
Bewährtes Werkzeug: pv
cat /var/log/old_logs.json | pv --line-mode --rate-limit 150 >> /var/log/wazuh_ingest.log
Vorteile:
- Kontrolle über Events pro Sekunde
- Vermeidung von Queue-Überläufen
- Stabiler Ingest-Prozess
3. Queue-Tuning auf Manager-Seite
Für größere Backfills sollte die Queue-Größe erhöht werden:
# /var/ossec/etc/internal_options.conf
logcollector.queue_size=100000
Wichtige Hinweise:
- Änderungen erfordern einen Neustart des Wazuh Managers
- Höhere Werte erhöhen RAM-Nutzung
- Keine Garantie gegen Drops bei extremen Lastspitzen
4. Optional: Agent-basierte Verarbeitung
Falls Logs nicht direkt auf dem Manager verarbeitet werden sollen:
- Logs auf einen Wazuh-Agent verschieben
- Dort lokal überwachen lassen
- Weiterleitung erfolgt automatisch an den Manager
Aber auch hier gelten dieselben Einschränkungen bezüglich Backfilling und Rate Limits.
5. JSON-Verarbeitung sicherstellen
Da NDJSON verwendet wird:
- Der Wazuh JSON-Decoder greift automatisch
- Voraussetzung: jede Zeile ist ein valides JSON-Objekt
Falls keine Alerts entstehen:
- Eigene Regeln definieren (
ruleset) - Felder gezielt matchen
Beispielansatz:
<rule id="100100" level="5">
<if_sid>json</if_sid>
<field name="event_type">suspicious</field>
<description>Custom JSON Alert</description>
</rule>
Lessons Learned / Best Practices
- Wazuh ist ein Streaming-System, kein Batch-Ingestion-Tool.
- Historische Logs müssen aktiv “nachgespielt” werden.
- Backfilling ohne Rate-Limit führt fast immer zu Datenverlust.
- Queue-Tuning ist hilfreich, ersetzt aber keine Flusskontrolle.
- Große Datenmengen sollten in kontrollierten Batches verarbeitet werden.
- Vor produktivem Einsatz empfiehlt sich ein Testlauf mit kleinen Datenmengen.
- Monitoring der Wazuh-internen Queues ist essenziell bei Bulk-Operationen.
Fazit
Das scheinbar einfache Einlesen bestehender Logdateien widerspricht dem grundlegenden Funktionsprinzip von Wazuh. Der Logcollector verarbeitet ausschließlich neue Datenströme und ignoriert vorhandene Inhalte konsequent. Wer historische Logs analysieren möchte, muss diese aktiv und kontrolliert in den Datenstrom einspeisen. Mit einem durchdachten Backfilling-Ansatz, Rate Limiting und angepassten Queue-Settings lässt sich dieses Szenario jedoch zuverlässig und ohne Datenverlust umsetzen. Entscheidend ist dabei, Wazuh nicht als Datei-Importer, sondern als Echtzeit-Analyseplattform zu verstehen.
Quellenverweis
Wazuh Log Data Collection
https://documentation.wazuh.com/current/user-manual/capabilities/log-data-collection/monitoring-log-files.html
Wazuh Ruleset Syntax
https://documentation.wazuh.com/current/user-manual/ruleset/ruleset-xml-syntax/index.html
Wazuh Logcollector Source Code (Verhalten)
https://github.com/wazuh/wazuh/blob/866c3bd680fae86e64966971adbf9658cac0a06b/src/logcollector/logcollector.h
Mehr zu Wazuh …
https://wazuh.com/?utm_source=ambassadors&utm_medium=referral&utm_campaign=ambassadors+program
Mehr zum Wazuh Ambassador Program …
https://wazuh.com/ambassadors-program/?utm_source=ambassadors&utm_medium=referral&utm_campaign=ambassadors+program
https://wazuh.slack.com/archives/C07CCCCGHHP/p1774839423241349