01.2 Wazuh Installation prüfen

Einleitung

Das Dashboard geht auf – schön. Aber ist Wazuh damit wirklich fertig installiert? Nicht unbedingt. Ein Dienst kann laufen und trotzdem keine Daten verarbeiten, ein Agent kann „active“ sein und seine Queue verlieren, und ein Indexer kann Anfragen beantworten, obwohl bereits Shards fehlen.

Diese Seite sammelt deshalb die Checks, mit denen ich eine frische Wazuh-Installation abnehmen würde. Erst kommt der schnelle Rundgang, danach die gründliche Variante. Ganz am Ende gibt es eine kleine Fehlersuchhilfe für den Fall, dass ein Ergebnis nicht so aussieht wie erwartet.

Die Beispiele passen zu einer nativen Installation mit systemd. Bei Docker oder Kubernetes bleiben die fachlichen Prüfungen gleich, nur Dienststatus und Logpfade sehen anders aus.

Was bedeutet eigentlich „funktioniert“?

Für mich ist eine Installation erst dann in Ordnung, wenn diese Kette einmal komplett nachgewiesen wurde:

1. Betriebssystem, DNS und Uhrzeit stimmen.
2. Wazuh Manager, Indexer und Dashboard laufen nach einem Neustart.
3. Die vorgesehenen Ports sind erreichbar – und die anderen eben nicht.
4. Manager-API und Indexer-API antworten mit plausiblen Daten.
5. Der Indexer hat alle benötigten Primary Shards und die erwartete Node-Anzahl.
6. Mindestens ein Agent ist verbunden und hat seine Gruppenkonfiguration übernommen.
7. Ein kontrolliertes Ereignis kommt vom Agent bis ins Dashboard.
8. Manager und Agents verwerfen keine Ereignisse.
9. Datenträger und Arbeitsspeicher haben noch vernünftige Reserve.

Der 5-Minuten-Check

Wenn es erst einmal schnell gehen soll, liefern diese fünf Schritte einen guten Überblick.

1. Laufen die drei zentralen Dienste?

systemctl --no-pager --full status \
  wazuh-manager wazuh-indexer wazuh-dashboard

Erwartet werden dreimal active (running) und keine ständigen Neustarts. Mit diesem Befehl sieht man zusätzlich, ob ein Dienst zwar läuft, aber direkt nach dem Start Fehler protokolliert hat.

Etwas kompakter und gut für Skripte:

systemctl is-active wazuh-manager wazuh-indexer wazuh-dashboard
systemctl is-enabled wazuh-manager wazuh-indexer wazuh-dashboard

2. Hören die erwarteten Ports?

sudo ss -lntup | grep -E ':(443|1514|1515|55000|9200)\b'

Je nach Architektur müssen nicht alle Ports auf derselben Adresse lauschen. Wichtiger als „alles ist offen“ ist: Jeder Dienst lauscht nur dort, wo er wirklich gebraucht wird.

3. Ist der Indexer gesund?

Im Dashboard unter Indexer management → Dev Tools:

GET _cluster/health

Beispiel aus dieser Installation: green, ein Node, keine unzugewiesenen Shards und 100 % aktive Shards.

Das finden wir so natürlich nur raus, wenn wir auch auf das Dahsboard kommen :) Theoretisch auch per curl API Abfrage.

Auf die Felder status, number_of_nodes, active_primary_shards, unassigned_shards, number_of_pending_tasks und active_shards_percent_as_number achten. Was die Farben genau bedeuten, steht weiter unten.

4. Sieht das Dashboard Agents und Alerts?

Die Startseite sollte ohne API-Fehler laden, mindestens den erwarteten Manager sehen und aktuelle Alert-Zahlen anzeigen.

Die Übersicht zeigt auf einen Blick, ob Agents und aktuelle Alerts überhaupt im Dashboard ankommen.

Eine hohe Zahl ist hier nicht automatisch gut. Für den Installationstest geht es erst einmal darum, dass aktuelle Daten überhaupt sichtbar sind und der Zeitraumfilter stimmt.

5. Ist mindestens ein Agent wirklich aktiv?

Unter Endpoints prüfen:

• Status active;
• erwartete Wazuh-Version;
• richtige Gruppe oder Gruppen;
• plausibles Betriebssystem und IP-Adresse;
• erwarteter Cluster-Node.

Die öffentliche Endpoint-Ansicht zeigt Status und Betriebssystemmix. Hostnamen, IP-Adressen, Gruppenprofile und die Agententabelle sind bewusst nicht enthalten.

Damit ist der schnelle Check fertig. Für eine echte Abnahme würde ich trotzdem noch die folgenden Punkte durchgehen.

Erst die Linux-Basis prüfen

Name, DNS und Zeit

hostnamectl
hostname --fqdn
getent ahosts "$(hostname --fqdn)"
timedatectl status
chronyc tracking
chronyc sources -v

Der FQDN muss zum Zertifikats- und Konfigurationskonzept passen. Die Uhr sollte synchronisiert sein; größere Abweichungen machen Zertifikate, Korrelationen und spätere Zeitlinien unzuverlässig.

Ressourcen und Dateisysteme

free -h
df -hT
df -ih
lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS

Nicht nur auf Prozentwerte schauen. Wenige freie GiB können bei Index-Merges sehr schnell verschwinden, und ein Dateisystem kann auch durch volle Inodes ausfallen. Für den Indexer sollte nach Installation und erstem Agenten-Rollout noch reichlich Reserve vorhanden sein.

Die größten Wazuh-Verzeichnisse findet man zum Beispiel so:

sudo du -xhd1 /var/ossec /var/lib/wazuh-indexer 2>/dev/null | sort -h

Zertifikate

openssl s_client -connect wazuh.example.lan:443 \
  -servername wazuh.example.lan </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName

Prüfen:

• Name steht als SAN im Zertifikat;
• Zertifikat ist noch gültig;
• Aussteller ist der erwartete;
• die Zertifikatskette wird auf dem Admin-Client vertraut;
• private Schlüssel sind nicht für normale Benutzer lesbar.

Manager und Server-API

Managerprozesse

sudo /var/ossec/bin/wazuh-control status

Mindestens die zur eigenen Konfiguration gehörenden Kernprozesse müssen laufen, insbesondere wazuh-analysisd, wazuh-remoted, wazuh-db und die API. Optionale Module dürfen fehlen, wenn sie bewusst deaktiviert wurden.

Konfiguration validieren

sudo /var/ossec/bin/wazuh-analysisd -t
sudo /var/ossec/bin/verify-agent-conf

Beide Prüfungen müssen ohne Fehler enden. Eigene Decoder und Regeln werden zusätzlich mit wazuh-logtest gegen bekannte Testereignisse geprüft:

sudo /var/ossec/bin/wazuh-logtest

wazuh-logtest beweist Decoder und Regelpfad, aber noch nicht den Transport von einem echten Agenten. Dafür kommt später noch ein Ende-zu-Ende-Test.

Antwortet die Server-API?

Zuerst ein JWT mit einem eigens dafür vorgesehenen API-Konto holen und dann die API-Wurzel abfragen:

TOKEN=$(curl -sk -u '<API-USER>:<API-PASSWORT>' \
  -X POST 'https://127.0.0.1:55000/security/user/authenticate?raw=true')

curl --fail --silent --show-error \
  -H "Authorization: Bearer $TOKEN" \
  'https://127.0.0.1:55000/?pretty=true'

unset TOKEN

Im Regelbetrieb gehört das Passwort nicht in die Shell-History. Für Skripte kommen Benutzer und Passwort aus dem Secret-Store; das Konto erhält nur die wirklich benötigten API-Rechte.

Die Antwort sollte error: 0, API-Version, Hostname und einen aktuellen Zeitstempel enthalten.

Den Indexer genauer ansehen

Die folgenden Abfragen laufen unter Indexer management → Dev Tools. Auf der Shell geht das ebenfalls über Port 9200 mit einem passenden Indexer-Konto.

Was bedeuten green, yellow und red?

Status	Bedeutung	Einordnung
green	Alle Primary Shards und alle konfigurierten Replicas sind zugewiesen.	Zielzustand eines korrekt replizierten Clusters; auch bei einem Single-Node möglich, wenn Replicas bewusst auf 0 stehen.
yellow	Alle Primary Shards sind da, aber mindestens eine Replica fehlt.	Daten sind durchsuchbar. Bei nur einem Node und number_of_replicas: 1 technisch erwartbar, aber ohne Redundanz. In einem Multi-Node-Cluster untersuchen.
red	Mindestens ein Primary Shard ist nicht zugewiesen.	Daten fehlen oder sind nicht verfügbar. Sofort untersuchen.

Darum reicht die Farbe allein nicht. Zur Abnahme gehören immer number_of_nodes, number_of_data_nodes, unassigned_shards und die bewusst geplante Replica-Anzahl.

Nodes und Rollen

GET _cat/nodes?v

Die Ausgabe muss genau die geplanten Indexer-Nodes zeigen. Nach einer Clustererweiterung ist dieser Check wichtiger als die bloße Erreichbarkeit eines einzelnen Nodes.

Speicherbelegung

GET _cat/allocation?v&s=node

Damit sieht man, wie viele Shards auf welchem Node liegen und wie viel Datenträger belegt beziehungsweise noch frei ist.

Indizes und Shards

GET _cat/indices/wazuh-*?v&s=health,index
GET _cat/shards/wazuh-*?v

red oder UNASSIGNED ist ein echter Befund. Bei unklarer Zuweisung hilft:

GET _cluster/allocation/explain

Häufige Ursachen sind ein voller Datenträger, eine fehlende Node-Rolle, eine nicht erreichbare Node, ungeeignete Allocation-Regeln oder mehr Replicas als verfügbare Nodes.

Kommen aktuelle Alert-Indizes an?

GET _cat/indices/wazuh-alerts-*?v&s=index:desc

Es sollte ein zum aktuellen Datum passender Index existieren und dessen Dokumentzahl nach einem kontrollierten Testereignis steigen.

Dashboard prüfen

Im Dashboard selbst kontrollieren:

• Anmeldung mit persönlichem Admin- und Read-only-Konto;
• API-Auswahl zeigt die erwartete Verbindung;
• App Settings → Miscellaneous → Health check läuft ohne Fehler;
• About zeigt die erwartete Dashboard-Version;
• Zeitfilter steht auf einem sinnvollen Zeitraum;
• keine Meldung „Wazuh server API seems to be down“;
• ein Read-only-Benutzer kann suchen, aber keine Konfiguration verändern.

Ein funktionierendes Dashboard beweist noch nicht, dass alle Agents Daten liefern. Es beweist aber, dass Browser, Reverse Proxy, Dashboard, Server-API und Indexer grundsätzlich zusammenspielen.

Agents prüfen

Status und Gruppensynchronisation

Über die Server-API:

curl --fail --silent --show-error \
  -H "Authorization: Bearer $TOKEN" \
  'https://127.0.0.1:55000/agents?select=id,name,status,version,group,group_config_status&pretty=true'

Wichtig sind:

• status: active für erwartete Systeme;
• eindeutige Namen und IDs;
• keine alten Dubletten;
• möglichst konsistente Agentversionen;
• group_config_status: synced nach zentralen Änderungen.

disconnected ist nicht automatisch ein Sicherheitsvorfall – ein Notebook kann schlicht aus sein. Bei einem Server oder einer Firewall ist derselbe Status dagegen sofort erklärungsbedürftig.

Agentqueue

Für einen einzelnen Agenten:

curl --fail --silent --show-error \
  -H "Authorization: Bearer $TOKEN" \
  'https://127.0.0.1:55000/agents/001/stats/agent?pretty=true'

msg_buffer sollte sich im Normalbetrieb immer wieder abbauen. Wiederholte Queue-Warnungen bedeuten, dass Ereignisse verloren gehen können. Dann nicht nur den Puffer vergrößern, sondern zuerst die laute Quelle finden und filtern.

Gehen irgendwo Ereignisse verloren?

Auf dem Manager:

grep -E '^(events_dropped|.*discarded_count)' \
  /var/ossec/var/run/wazuh-analysisd.state \
  /var/ossec/var/run/wazuh-remoted.state

Die relevanten Zähler events_dropped und discarded_count sollen 0 bleiben. Steigende Werte weisen auf Überlastung oder Queue-Probleme hin – auch dann, wenn Dashboard und Dienste äußerlich normal aussehen.

Zusätzlich nach frischen Fehlern schauen:

sudo journalctl -u wazuh-manager -u wazuh-indexer -u wazuh-dashboard \
  --since '30 minutes ago' --priority=warning

sudo tail -n 200 /var/ossec/logs/ossec.log
sudo tail -n 200 /var/log/filebeat/filebeat

Logpfade können je nach Paketversion und Distribution abweichen.

Ende-zu-Ende-Test

Der sauberste Test verwendet einen dafür vorgesehenen Test-Agenten und ein Ereignis, das die vorhandenen Regeln sicher erkennen. Geeignet sind zum Beispiel:

• ein einzelner, kontrollierter SSH-Fehlversuch mit Testbenutzer;
• Erstellen und Löschen einer harmlosen Datei in einem bewusst per FIM überwachten Testpfad;
• ein vorher mit wazuh-logtest geprüftes Anwendungsereignis in einer Testlogdatei.

Danach im Dashboard prüfen:

1. korrekter Agentname;
2. plausibler Zeitstempel;
3. erwartete Regel und Severity;
4. erwartete Felder und Gruppen;
5. Dokument erscheint im aktuellen wazuh-alerts-*-Index;
6. ein gegebenenfalls vorgesehener Benachrichtigungskanal löst genau einmal aus.

Keine beliebigen Alarmtexte als logger -t sshd in produktive Logs schreiben. Das sieht später wie ein echter Angriff aus und macht die Forensik unnötig spannend.

Neustarttest

Eine frische Installation sollte mindestens einen kontrollierten Neustart überstehen:

sudo reboot

Danach noch einmal prüfen:

• Dienste aktiv und aktiviert;
• Indexerzustand stabil;
• erwartete Node-Anzahl;
• Dashboard und APIs erreichbar;
• Agents verbinden sich wieder;
• keine neuen Zertifikats-, Rechte- oder Mountfehler;
• Datenträger wurden wie geplant eingehängt.

Wenn etwas nicht stimmt

Symptom	Als Erstes prüfen
Dashboard nicht erreichbar	wazuh-dashboard, Reverse Proxy, TLS, Port 443
Dashboard meldet API down	wazuh-manager, Port 55000, API-Zugang, wazuh.yml
Indexer yellow	Node-Anzahl, Replica-Anzahl, unassigned_shards, Allocation Explain
Indexer red	freie Platte, Indexerlogs, fehlende Nodes, Primary Shards, Allocation Explain
Agent disconnected	Endpoint eingeschaltet, Port 1514, Schlüssel, Uhrzeit, Agentlog
Agent active, aber keine Alerts	Logquelle, Agentqueue, Managerqueue, Decoder/Regel, Zeitfilter
Gruppenkonfiguration nicht synchron	verify-agent-conf, Gruppenzuweisung, Agentlog, agent.remote_conf
Dokumente kommen nicht im Index an	Filebeat, TLS zum Indexer, aktuelle Indizes, Indexer-Schreibschutz
Platte wächst sehr schnell	größte Indizes, lauteste Agents, Journald-/Docker-Filter, Aufbewahrung

Mein kleines Abnahmeprotokoll

Prüfung	Erwartet	Ergebnis	Erledigt
Dienste	alle aktiv und aktiviert		☐
DNS und Zeit	FQDN korrekt, Uhr synchron		☐
TLS	gültige Kette und passende SANs		☐
Indexer	erwartete Farbe, Nodes und Shards		☐
Manager-API	error: 0, Version plausibel		☐
Dashboard	keine API-Fehler, aktuelle Daten		☐
Test-Agent	active und synced		☐
Ende-zu-Ende-Ereignis	im aktuellen Index sichtbar		☐
Queue-Zähler	keine Drops oder Discards		☐
Speicher	ausreichend Reserve		☐
Neustart	alles kommt selbstständig zurück		☐
Backup	Sicherung vorhanden, Restore geplant		☐

Weiterlesen

• Wazuh Indexer API: Cluster Health
• Wazuh Indexer Cluster Management
• Wazuh Indexer API – Getting Started
• Wazuh Dashboard Troubleshooting
• Wazuh Dashboard bedienen und Health Check ausführen
• Wazuh Server Hardware und Queue-Zähler
• wazuh-logtest