Wazuh Agent Enrollment begrenzen: Maximale Agent-Anzahl mit einem Registration Broker durchsetzen

Einleitung

In größeren Wazuh-Umgebungen ist die zentrale Registrierung und Verwaltung von Agents ein wesentlicher Bestandteil der Sicherheitsarchitektur. Doch nicht jede Installation soll eine unbegrenzte Anzahl an Endpunkten aufnehmen können.

Gerade in Multi-Tenant-Umgebungen, Managed-Security-Services (MSSP), Testinstallationen oder streng kontrollierten Infrastrukturen kann es erforderlich sein, die Anzahl registrierter Wazuh Agents gezielt zu begrenzen.

Eine typische Anforderung lautet:

Ein Wazuh Manager darf maximal fünf Agents registrieren. Versucht sich ein sechster Agent anzumelden, muss dessen Registrierung automatisch abgelehnt werden.

Wazuh bietet dafür keine native Einstellung, mit der sich eine feste Obergrenze für registrierte Agents konfigurieren lässt.

Über einen vorgeschalteten Registration Broker lässt sich eine solche Einschränkung jedoch implementieren. Dieser kontrolliert den Registrierungsprozess, prüft die aktuelle Agent-Anzahl und entscheidet, ob weitere Endpunkte aufgenommen werden dürfen.

Der folgende Artikel erläutert die technischen Hintergründe, die notwendigen Konfigurationsänderungen und die sicherheitsrelevanten Aspekte einer solchen Architektur.

Ausgangslage / Problemstellung

In einer regulären Wazuh-Installation können Agents auf unterschiedlichen Wegen beim Wazuh Manager registriert werden.

Zu den üblichen Registrierungsverfahren gehören:

Automatisches Enrollment über den Wazuh Authentication Daemon (wazuh-authd).
Registrierung über das Werkzeug agent-auth.
Automatisierte Registrierung durch entsprechende Installationsparameter.
Administrative Agent-Erstellung über die Wazuh Server API.

Diese Verfahren ermöglichen eine flexible Bereitstellung von Endpunkten. Eine feste Begrenzung der maximal registrierbaren Agents ist dabei jedoch nicht vorgesehen.

Beispiel: Maximale Anzahl von fünf Agents

Ein Administrator betreibt einen Wazuh Manager, auf dem höchstens fünf Agents registriert sein dürfen.

Registrierung	Gewünschtes Ergebnis
Agent 1	Zulassen
Agent 2	Zulassen
Agent 3	Zulassen
Agent 4	Zulassen
Agent 5	Zulassen
Agent 6	Ablehnen
Weitere Agents	Ablehnen, solange das Limit erreicht ist

Die Herausforderung besteht darin, diese Einschränkung zuverlässig durchzusetzen, ohne dass Agents alternative Registrierungswege nutzen können.

Eine reine Prüfung der Agent-Anzahl durch ein externes Skript reicht dafür nicht aus, wenn weiterhin eine direkte Registrierung beim Manager möglich ist.

Erforderlich ist eine Architektur, in der sämtliche zulässigen Registrierungsanforderungen durch eine zentrale Kontrollinstanz verarbeitet werden.

Technische Analyse

1. Warum Wazuh keine native Agent-Obergrenze erzwingt

Der Wazuh Manager verwaltet registrierte Agents über seine internen Komponenten und stellt administrative Funktionen über die Wazuh Server API bereit.

Die Registrierung und die spätere Kommunikation eines Agents sind dabei voneinander zu unterscheiden.

Vereinfachte Wazuh-Architektur

Wazuh Agent

Registrierungsanforderung

Enrollment: TCP 1515

Wazuh Manager – authd

Registrierung und Schlüsselaustausch

Registrierter Agent

Reguläre Kommunikation über TCP 1514

Die Darstellung zeigt den üblichen Enrollment-Weg. API-basierte Registrierungen bilden einen zusätzlichen administrativen Zugang.

Der Authentication Daemon verarbeitet Registrierungsanforderungen. Er besitzt jedoch keinen integrierten Mechanismus, der beispielsweise nach fünf registrierten Agents automatisch jede weitere Anmeldung verhindert.

Auch die reguläre Agent-Kommunikation ist nicht dafür vorgesehen, eine solche Registrierungsobergrenze durchzusetzen.

2. Der Registration Broker als Kontrollinstanz

Eine mögliche Lösung besteht darin, einen eigenen Registration Broker zwischen Agents und Wazuh Manager einzusetzen.

Dieser Broker übernimmt die folgenden Aufgaben:

Entgegennahme einer Registrierungsanforderung.
Authentifizierung und Autorisierung des anfragenden Endpunkts.
Abfrage der bereits registrierten Agents.
Vergleich mit dem konfigurierten Grenzwert.
Ablehnung oder Freigabe der Registrierung.
Erstellung des Agents über die Wazuh API.
Sichere Bereitstellung des Agent-Schlüssels.

Architektur mit Registration Broker

Neue Wazuh Agents

Registrierungsanfrage per HTTPS

Registration Broker

Authentifizierung → Agent-Anzahl prüfen → Entscheidung

Unter Limit

Registrierung per API

Limit erreicht

Anfrage ablehnen

Wazuh Manager API

TCP 55000 · POST /agents

Der Broker fungiert damit als zentraler Entscheidungspunkt für neue Registrierungen.

Wichtig ist, dass diese Architektur nicht allein durch einen vorgeschalteten Dienst sicher wird. Der direkte Zugriff auf alternative Enrollment-Schnittstellen muss ebenfalls eingeschränkt werden.

3. Relevante Wazuh-Komponenten

Komponente	Aufgabe
`wazuh-authd`	Verarbeitung des regulären Agent-Enrollment
Wazuh Server API	Administrative Verwaltung und Erstellung von Agents
`POST /agents`	Anlegen eines neuen Agents
`GET /agents`	Abfragen registrierter Agents
Registration Broker	Prüfung und Durchsetzung des Limits
Agent-Schlüssel	Authentifizierung des Agents gegenüber dem Manager

Für die Umsetzung ist besonders wichtig, dass die Wazuh API nicht direkt von unberechtigten Clients erreichbar ist.

Andernfalls könnte ein Client den Broker umgehen und selbst eine Registrierung durchführen, sofern er über entsprechende API-Berechtigungen verfügt.

Lösung / Best Practices

Schritt 1: Direktes Remote Enrollment deaktivieren

Zunächst wird der Wazuh Manager so konfiguriert, dass Agents sich nicht mehr über den regulären Remote-Enrollment-Weg registrieren können.

Dazu wird auf dem Manager die Konfigurationsdatei geöffnet:

sudo nano /var/ossec/etc/ossec.conf

Innerhalb des bestehenden <auth>-Abschnitts werden die folgenden Parameter gesetzt:

<auth>
  <disabled>no</disabled>
  <remote_enrollment>no</remote_enrollment>
</auth>

Die beiden Parameter erfüllen unterschiedliche Aufgaben.

<disabled>no</disabled>

Der Authentication Daemon bleibt aktiviert.

<remote_enrollment>no</remote_enrollment>

Remote Enrollment über den Authentication Daemon wird deaktiviert. Neue Agents können diesen direkten Registrierungsweg damit nicht mehr verwenden.

Die übrigen bereits vorhandenen Einstellungen im <auth>-Abschnitt sollten beibehalten werden.

Anschließend wird der Wazuh Manager neu gestartet:

sudo systemctl restart wazuh-manager

Diese Änderung sollte zunächst in einer Testumgebung geprüft werden, da bestehende automatische Enrollment-Prozesse dadurch nicht mehr funktionieren.

Zusätzlich empfiehlt sich eine Firewall-Regel, die den direkten Zugriff von Endpunkten auf den Enrollment-Port TCP 1515 unterbindet.

Die reguläre Kommunikation bereits registrierter Agents über TCP 1514 bleibt davon grundsätzlich getrennt.

Schritt 2: Zugriff auf die Wazuh API absichern

Die Wazuh Server API ist standardmäßig über TCP 55000 erreichbar.

Der Registration Broker benötigt API-Zugriff, um Agents abzufragen und neue Einträge anzulegen.

Für diesen Zugriff sollte ein dediziertes API-Konto verwendet werden.

Empfohlene Sicherheitsmaßnahmen:

API-Zugriff auf vertrauenswürdige Hosts oder Netzsegmente beschränken.
Einen dedizierten Service-Account mit minimal erforderlichen Berechtigungen einsetzen.
Administrative API-Zugänge nicht an Endpunkte verteilen.
HTTPS mit gültiger Zertifikatsprüfung verwenden.
API-Zugangsdaten ausschließlich serverseitig speichern.
Administrative Änderungen und Registrierungen protokollieren.

Insbesondere die Berechtigung zum Erstellen neuer Agents darf nicht unkontrolliert an andere Konten vergeben werden.

Entscheidend: Der Broker kann das Limit nur dann zuverlässig erzwingen, wenn kein anderer Registrierungsweg seine Kontrolle umgeht.

Schritt 3: Anzahl registrierter Agents ermitteln

Der Broker muss zunächst feststellen, wie viele Agents bereits beim Manager registriert sind.

Dafür kann die Wazuh API verwendet werden.

Ein typischer API-Aufruf lautet:

GET /agents

Für eine reine Zählung kann die API mit einer passenden Auswahl und der Gesamtanzahl der Ergebnisse verwendet werden:

GET /agents?select=id&limit=1

Die API-Antwort enthält in unterstützten Wazuh-Versionen die Gesamtanzahl der passenden Einträge, beispielsweise unter:

{
  "data": {
    "affected_items": [
      {
        "id": "001"
      }
    ],
    "total_affected_items": 5
  }
}

Der Broker wertet total_affected_items aus.

Für eine Obergrenze von fünf Agents lautet die Entscheidungslogik:

MAX_AGENTS = 5if registered_agents >= MAX_AGENTS:    reject_registration()else:    register_agent()

Diese Darstellung beschreibt lediglich die grundlegende Logik. Für einen produktiven Broker sind zusätzliche Prüfungen und eine sichere Behandlung paralleler Registrierungen erforderlich.

Außerdem muss festgelegt werden, was unter einem registrierten Agent verstanden wird.

Für eine feste Gesamtobergrenze sollten alle registrierten Agents berücksichtigt werden, unabhängig davon, ob sie gerade aktiv, getrennt oder noch nie verbunden waren. Der Manager selbst darf nicht als Agent mitgezählt werden.

Schritt 4: Neue Agents über die API registrieren

Liegt die aktuelle Anzahl unter dem festgelegten Limit, kann der Broker einen neuen Agent über die Wazuh API anlegen.

Dazu wird folgender Endpunkt verwendet:

POST /agents

Ein vereinfachter Request kann folgendermaßen aussehen:

POST /agents
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

{
  "name": "endpoint-005"
}

Bei erfolgreicher Registrierung liefert die API die Informationen des angelegten Agents einschließlich des für die Registrierung benötigten Schlüssels.

Der Broker muss diesen Schlüssel sicher an den anfragenden Endpunkt übertragen.

Auf dem Agent kann der bereitgestellte Schlüssel anschließend mit dem vorgesehenen Importverfahren eingebunden werden, beispielsweise über das Werkzeug manage_agents und dessen Importfunktion.

Der genaue Ablauf hängt vom Betriebssystem, der Wazuh-Version und dem gewählten Bereitstellungsverfahren ab.

Ein entscheidender Unterschied zur Standardinstallation besteht darin, dass der Agent zunächst ohne automatische Registrierung installiert wird.

Erst nach Freigabe durch den Broker erhält der Endpunkt die notwendigen Registrierungsinformationen.

Schritt 5: Parallele Registrierungen sicher behandeln

Eine besonders wichtige Herausforderung entsteht, wenn mehrere Agents gleichzeitig eine Registrierung anfordern.

Angenommen, auf dem Manager sind bereits vier Agents registriert.

Zwei weitere Endpunkte senden nahezu gleichzeitig eine Anfrage an den Broker.

Ohne zusätzliche Synchronisierung könnte folgender Ablauf entstehen:

Zeitpunkt	Anfrage A	Anfrage B
T1	Zählt vier Agents	–
T2	–	Zählt vier Agents
T3	Registrierung freigegeben	–
T4	–	Registrierung freigegeben
T5	Agent 5 wird erstellt	–
T6	–	Agent 6 wird erstellt

Das konfigurierte Limit wäre überschritten.

Dieses Problem wird als Race Condition bezeichnet.

Um es zu verhindern, müssen die Zählung und die anschließende Registrierung als zusammenhängender, exklusiv geschützter Vorgang ausgeführt werden.

Eine vereinfachte Umsetzung mit einem Lock:

MAX_AGENTS = 5with registration_lock:    current_count = get_registered_agent_count()    if current_count >= MAX_AGENTS:        raise RegistrationLimitReached()    new_agent = create_agent_via_api()    return new_agent

Der Lock stellt sicher, dass nicht mehrere Registrierungsprozesse gleichzeitig die Entscheidung auf Grundlage eines veralteten Agent-Zählstands treffen.

Dabei ist zu beachten, dass ein einfacher Prozess-Lock nur innerhalb eines einzelnen Prozesses schützt.

Wird der Broker mit mehreren Worker-Prozessen oder auf mehreren Servern betrieben, ist ein gemeinsamer Synchronisierungsmechanismus erforderlich, beispielsweise eine geeignete Datenbanktransaktion oder ein verteilter Lock.

Auch dieser Schutz reicht nur aus, wenn sämtliche relevanten Registrierungen tatsächlich über den Broker erfolgen.

Schritt 6: Fehlerbehandlung und Sicherheitskontrollen implementieren

Ein produktiver Registration Broker sollte nicht nur den Grenzwert prüfen.

Weitere notwendige Kontrollen umfassen:

Authentifizierung der Endpunkte

Jeder anfragende Client muss seine Berechtigung zur Registrierung nachweisen. Ohne eine solche Prüfung könnte ein Angreifer den Broker nutzen, um unberechtigt Agent-Slots zu belegen.

Schutz vor doppelten Registrierungen

Der Broker sollte prüfen, ob bereits ein Agent mit derselben vorgesehenen Identität existiert.

Doppelte Anfragen dürfen nicht unbeabsichtigt mehrere Registrierungen erzeugen.

Sichere Schlüsselübertragung

Registrierungsschlüssel dürfen weder unverschlüsselt übertragen noch in regulären Anwendungslogs gespeichert werden.

Fail-Closed-Verhalten

Ist die Wazuh API nicht erreichbar oder kann die Agent-Anzahl nicht zuverlässig ermittelt werden, sollte der Broker keine neue Registrierung zulassen.

Kontrollierte Fehlerbehandlung

Schlägt eine Registrierung nach dem Anlegen des Agents fehl, muss der Broker den Zustand nachvollziehen und gegebenenfalls eine sichere Wiederholung oder administrative Bereinigung ermöglichen.

Ein fehlgeschlagener Schlüsseldownload bedeutet nicht automatisch, dass der Agent-Eintrag auf dem Manager ebenfalls fehlgeschlagen ist.

Protokollierung

Mindestens folgende Ereignisse sollten erfasst werden:

Erfolgreiche Registrierungen.
Wegen des Limits abgelehnte Anfragen.
Fehlgeschlagene Authentifizierungen.
Fehler bei API-Aufrufen.
Änderungen an der konfigurierten Obergrenze.
Administrative Eingriffe in den Agent-Bestand.

Schritt 7: Registrierungslimit testen

Vor dem produktiven Einsatz sollte die Implementierung gezielt getestet werden.

Abnahmetests für einen Registration Broker

Testfortschritt

0 von 7Die ersten fünf Agents können registriert werden.Die Registrierung des sechsten Agents wird abgelehnt.Direktes Remote Enrollment ist nicht möglich.Unberechtigte API-Zugriffe werden verweigert.Zwei parallele Registrierungen überschreiten das Limit nicht.Ein API-Ausfall führt zur Ablehnung neuer Registrierungen.Ein freigegebener Agent-Slot kann erneut verwendet werden.

Insbesondere die parallele Registrierung sollte wiederholt unter Last getestet werden.

Lessons Learned / Best Practices

1. Ein Agent-Limit ist eine Zugriffskontrolle, keine Ressourcenbegrenzung

Die Begrenzung registrierter Agents verhindert zunächst nur die Aufnahme zusätzlicher Endpunkte.

Sie begrenzt nicht automatisch CPU-Auslastung, Arbeitsspeicher, Event-Volumen oder Speicherverbrauch.

Ein einzelner Agent kann je nach Konfiguration eine erhebliche Datenmenge erzeugen.

Wer die Wazuh-Infrastruktur vor Überlastung schützen möchte, benötigt deshalb zusätzlich geeignete Maßnahmen für Monitoring, Kapazitätsplanung und Datenverarbeitung.

2. Registrierung und Agent-Kommunikation getrennt betrachten

Ein Registration Broker wird ausschließlich für die Aufnahme neuer Agents benötigt.

Nach erfolgreicher Registrierung kommunizieren Agents weiterhin regulär mit dem Wazuh Manager.

Der Broker sollte deshalb nicht unnötig in den laufenden Event-Datenverkehr eingebunden werden.

Das reduziert Komplexität, Fehlerquellen und zusätzliche Abhängigkeiten.

3. Agent-Status beeinflusst die Zählstrategie

Wazuh unterscheidet verschiedene Agent-Zustände, darunter aktive, getrennte und noch nie verbundene Agents.

Eine Obergrenze für registrierte Agents sollte diese Zustände nicht mit einer Obergrenze gleichzeitig aktiver Agents verwechseln.

Andernfalls könnten getrennte Endpunkte unbeabsichtigt freie Registrierungskapazitäten erzeugen.

Für eine feste Registrierungskapazität ist daher die Anzahl tatsächlich vorhandener Agent-Einträge maßgeblich.

4. Agent-Löschung und Wiederregistrierung berücksichtigen

Wird ein Agent administrativ entfernt, entsteht grundsätzlich wieder ein freier Registrierungsplatz.

Dabei sollte klar definiert werden, welche Instanz Agents löschen darf.

Für streng kontrollierte Umgebungen kann es sinnvoll sein, auch Löschvorgänge über den Broker oder einen separaten administrativen Freigabeprozess abzuwickeln.

Wiederregistrierungen bestehender Endpunkte sollten ebenfalls eindeutig behandelt werden, um unbeabsichtigte Duplikate zu vermeiden.

5. Zusätzliche Agent-Kontrollen zentralisieren

Ein Registration Broker kann perspektivisch mehr Aufgaben übernehmen als die reine Begrenzung der Agent-Anzahl.

Denkbare Erweiterungen sind:

Freigabe ausschließlich bestimmter Hostnamen oder Geräteidentitäten.
Zuweisung erlaubter Agent-Gruppen.
Einschränkung nicht autorisierter Gruppenwechsel.
Registrierung anhand definierter Mandanten.
Zeitlich begrenzte Enrollment-Berechtigungen.
Zentrale Auditierung administrativer Agent-Aktionen.

Dabei muss allerdings zwischen einer kontrollierten Erstregistrierung und der Durchsetzung späterer administrativer Änderungen unterschieden werden.

Beispielsweise verhindert ein Broker nicht automatisch, dass ein berechtigter Administrator Agent-Gruppen nachträglich über einen anderen Verwaltungsweg verändert.

Auch dafür müssen die entsprechenden API-Berechtigungen und administrativen Zugänge kontrolliert werden.

6. Aufwand und Nutzen abwägen

Die Entwicklung eines eigenen Registration Brokers bedeutet zusätzlichen Betriebsaufwand.

Neben der eigentlichen Registrierung müssen Authentifizierung, API-Kommunikation, Synchronisierung, Fehlerbehandlung, Schlüsselverwaltung und Wartung berücksichtigt werden.

Für kleine Umgebungen, in denen lediglich gelegentlich Agents aufgenommen werden, kann ein manueller Freigabeprozess wirtschaftlicher und technisch einfacher sein.

Für Multi-Tenant-Architekturen oder automatisierte Managed-Security-Umgebungen kann ein zentraler Broker dagegen einen erheblichen Mehrwert bieten.

Fazit

Wazuh stellt keine native Konfigurationsoption bereit, mit der sich die maximale Anzahl registrierter Agents unmittelbar auf einen festen Wert wie fünf begrenzen lässt.

Eine solche Einschränkung lässt sich jedoch über einen eigenen Registration Broker realisieren.

Die zentrale Lösung besteht darin, das direkte Remote Enrollment zu deaktivieren, den administrativen API-Zugriff einzuschränken und neue Agents ausschließlich über einen kontrollierten Registrierungsdienst anzulegen.

Besonders wichtig sind dabei die sichere Abfrage des Agent-Bestands, die Vermeidung paralleler Registrierungsfehler und der Schutz vor alternativen Registrierungswegen.

Für einfache Installationen kann dieser Ansatz überdimensioniert sein. In kontrollierten Unternehmensumgebungen oder Multi-Tenant-Szenarien bietet er jedoch die Möglichkeit, den gesamten Agent-Lebenszyklus deutlich granularer zu steuern.

Die wichtigste Erkenntnis: Eine verlässliche Agent-Obergrenze entsteht nicht durch das bloße Zählen von Agents, sondern durch die konsequente Kontrolle sämtlicher Registrierungswege.

Weiterführende Informationen

Die folgenden Ressourcen dienen als Einstieg in die technische Dokumentation und die Weiterentwicklung eines eigenen Registration Brokers.

Die genannten Konfigurationsparameter und API-Beispiele sollten vor der produktiven Umsetzung mit der Dokumentation der tatsächlich eingesetzten Wazuh-Version abgeglichen werden. Der weiterführende Artikel-Link verweist auf eine Autorenseite; ein konkreter veröffentlichter Broker-Beitrag ist damit nicht bestätigt.

Mehr zu Wazuh …

Mehr zum Wazuh Ambassador Program …

https://wazuh.slack.com/archives/C0A933R8E/p1791814049658919