Wazuh mit Ansible ausrollen: Aufbau, Agent-Rollout und die Stolpersteine

Wer viele Server betreut, braucht einen zentralen Überblick, welcher Server welche offenen Schwachstellen hat, statt Hinweise aus Herstellermeldungen und Einzelprüfungen zusammenzusuchen. Deshalb haben wir im Oktober 2026 Wazuh eingeführt, zuerst für unsere eigene Infrastruktur, dann für Server unserer Kunden. Hier beschreiben wir, wie der Aufbau aussieht und was wir dabei gelernt haben.

Was Wazuh bei uns leisten soll

Wir nutzen Wazuh vor allem für drei Dinge:

Schwachstellen erkennen: Der Agent meldet die installierten Pakete, der Manager gleicht sie mit bekannten CVEs ab.
Härtung prüfen: Die Härtungsprüfung (Security Configuration Assessment) vergleicht die Konfiguration alle zwölf Stunden mit CIS-orientierten Richtlinien.
Änderungen an kritischen Dateien sehen: Die Dateiintegritätsprüfung läuft ebenfalls alle zwölf Stunden.

Dazu kommen die Log-Auswertung und ein stündlich aktualisiertes Systeminventar.

Der Aufbau

Manager, Indexer und Dashboard laufen als All-in-one-Installation mit Docker auf einer eigenen VM. Die VM legen wir mit Terraform auf unserem Proxmox-Cluster an, die Installation übernimmt eine Ansible-Rolle. Für unsere Größenordnung reicht diese Variante; einen verteilten Indexer-Cluster brauchen wir dafür nicht.

Das Dashboard ist nur aus dem internen Netz und per VPN erreichbar. Angemeldet wird per Single Sign-on mit Microsoft Entra, über dieselbe App-Registrierung wie bei Grafana und NetBox.

Der Agent-Rollout per Ansible

Kern des Rollouts ist eine kurze Rolle. Das Wazuh-Paket liest bei der Installation einige Umgebungsvariablen aus und registriert den Agent damit selbstständig am Manager:

- name: Agent installieren und registrieren (nur bei Erstinstallation)
  ansible.builtin.apt:
    name: "wazuh-agent={{ wazuh_agent_version }}-1"
    state: present
  environment:
    WAZUH_MANAGER: "{{ wazuh_manager_address }}"
    WAZUH_REGISTRATION_PASSWORD: "{{ wazuh_enrollment_password }}"
    WAZUH_AGENT_GROUP: "kunde-{{ wazuh_kunde }},standort-{{ wazuh_standort }}"
  when: not wazuh_installed.stat.exists
  no_log: true

- name: Version festhalten (Agent nie neuer als Manager)
  ansible.builtin.dpkg_selections:
    name: wazuh-agent
    selection: hold

Das Registrierungspasswort liegt verschlüsselt in Ansible Vault. Am Ende prüft die Rolle, ob die Schlüsseldatei des Agents existiert und nicht leer ist. Schlägt die Registrierung fehl, bricht der Lauf mit einem Hinweis auf Port, Passwort und Gruppe ab, statt still weiterzulaufen.

Gruppen nach Kunde und Standort

Jeder Agent bekommt zwei Gruppen: kunde-<name> und standort-<name>. Die Namen entsprechen den Mandanten und Standorten in NetBox, unserer Quelle für das Inventar. So lassen sich Befunde nach Kunde filtern, und Richtlinien oder Ausnahmen gelten gezielt für eine Gruppe.

Netzwerk: so wenig offen wie möglich

Die Agents verbinden sich über zwei Ports mit dem Manager: 1514 für die laufenden Meldungen, 1515 für die Registrierung. Im eigenen Netz ist das unkritisch. Für Server außerhalb, etwa bei einem Hoster oder beim Kunden, leiten wir die beiden Ports auf der Firewall weiter, aber nur für einen Alias mit den bekannten Absenderadressen. Wer nicht auf der Liste steht, erreicht den Manager nicht, und wer auf der Liste steht, braucht zusätzlich das Registrierungspasswort. Die Server-API auf Port 55000 ist von außen nicht erreichbar.

Vier Stolpersteine

1. Der Agent darf nie neuer sein als der Manager. Ein normales apt upgrade hebt den Agent sonst auf eine Version, die der Manager nicht kennt, und die Verbindung bricht ab. Deshalb pinnen wir die Version und setzen das Paket auf „hold“. Updates laufen bewusst: erst der Manager, dann die Agents.

2. Die Umgebungsvariablen wirken nur bei der Erstinstallation. Das Paket schreibt Manager-Adresse und Gruppen einmalig in seine Konfiguration. Wer später die Adresse ändert, etwa weil ein Server aus dem internen Netz zu einem Hoster umzieht, muss die Konfiguration des Agents anpassen; ein erneuter Rolloutlauf ändert daran nichts.

3. Inventarname ist nicht Hostname. Manche Hosts stehen in unserem Ansible-Inventar nur mit IP-Adresse. Ohne Anpassung hätten sie sich unter dieser IP registriert. Wir setzen den Agent-Namen deshalb ausdrücklich auf den echten Hostnamen.

4. Nach Regeländerungen neu an der API anmelden. Ändert man Regeln oder Gruppen über die API, werden bestehende Tokens ungültig. Automatisierungen, die danach weiterarbeiten, müssen sich neu anmelden, sonst laufen sie in Fehler.

Was Wazuh nicht ist

Wazuh ist ein Werkzeug, kein Sicherheitsteam. Die Schwachstellenerkennung sieht nur, was im Inventar steht, und ersetzt keinen Penetrationstest. Ein bestandener Härtungscheck ist noch kein Compliance-Nachweis. Und die Dateiintegritätsprüfung ist nur so gut wie die Auswahl der überwachten Pfade: Wer zu viel überwacht, bekommt vor allem Fehlalarme.

Entscheidend ist, was mit einem Befund passiert. Bei uns landen Alarme bei den Technikern, die die Systeme betreuen. Windows- und macOS-Agents binden wir als Nächstes an.

Wenn Sie Wazuh bei sich einsetzen wollen oder einen Überblick über den Sicherheitszustand Ihrer Server brauchen: Mehr dazu unter Wazuh Security Monitoring. Wie solche Befunde als Nachweis für ein Audit dienen, beschreiben wir unter TISAX-Vorbereitung.