Mandantenfähige Korrelation in Wazuh: Agent-Labels, Frequency-Regeln und CDB-Listen richtig einsetzen

von

Einleitung

Eine gemeinsam genutzte Wazuh-Infrastruktur kann für Managed-Security-Provider und Betreiber mehrerer kleiner Umgebungen wirtschaftlich attraktiv sein. Zentrale Komponenten, ein gemeinsames Regelwerk und eine konsolidierte Indexer-Infrastruktur reduzieren Betriebsaufwand und Ressourcenverbrauch.

Technisch muss dabei jedoch zwischen zwei grundsätzlich verschiedenen Ebenen unterschieden werden: der Ereignisanalyse auf dem Wazuh-Manager und der späteren Speicherung im Wazuh-Indexer. Eine saubere Trennung von Alerts durch eigene Indizes, Index Patterns und Document Level Security verhindert nicht automatisch, dass Ereignisse verschiedener Mandanten zuvor im selben Analysekontext verarbeitet werden.

Besonders relevant wird diese Unterscheidung bei Frequency-Regeln, Brute-Force-Erkennung, Active Response und mandantenspezifischen Allow- oder Deny-Listen. Eine fehlerhafte Annahme über den Gültigkeitsbereich einer Regel kann zu falsch zusammengeführten Ereignissen, unklarer Mandantenzuordnung oder sogar mandantenübergreifenden Reaktionen führen.

Ausgangslage / Problemstellung

Betrachtet wird eine zentrale Wazuh-Infrastruktur, die mehrere Kunden bedient. Die Alerts werden auf Indexer-Ebene getrennt, sodass jeder Kunde ausschließlich seine eigenen Security Events einsehen kann. Dazu erhalten die Agents beispielsweise ein zentral verwaltetes Mandanten-Label, das im fertigen Alert für die Index-Routing-Logik verwendet wird.

Die zentrale Frage betrifft jedoch die Regelverarbeitung auf dem Wazuh-Manager:

  • Werden Frequency-Zähler mandantenübergreifend geführt?
  • Können Agent-Labels wie agent.labels.customer mit <same_field> verwendet werden?
  • Wie lassen sich direkt an den Manager gesendete Syslog-Ereignisse voneinander trennen?
  • Wie kann eine Liste erlaubter Login-Länder pro Kunde gepflegt werden?
  • Ist eine Filterung über agent.name innerhalb eines <field>-Elements zuverlässig?

Als Beispiel dienen zwei Kunden mit jeweils einem System namens srv-web01. Mehrere fehlgeschlagene Anmeldungen von derselben Quell-IP sollen pro Kunde beziehungsweise pro Agent bewertet werden. Gleichzeitig soll ein erfolgreicher Cloud-Login einen Alert auslösen, wenn das erkannte Herkunftsland nicht zur kundenspezifischen Allowlist gehört.

Die Herausforderung besteht darin, dass Wazuh Agent-Metadaten, Decoder-Felder und den fertigen Alert in unterschiedlichen Verarbeitungsschritten erzeugt.

Technische Analyse

Frequency-Regeln sind standardmäßig agentbezogen

Frequency-Regeln werden in Wazuh standardmäßig nicht über alle Agents hinweg gezählt. Ohne zusätzliche Option berücksichtigt der Manager nur Ereignisse desselben Agents für den Frequency-Zähler. Erst <global_frequency /> hebt diese Einschränkung auf und bezieht Ereignisse aller Agents ein. Die Option wirkt dabei auf Manager-Ebene und nicht automatisch clusterweit.

Eine typische Regel sieht beispielsweise so aus:

<rule id="110010" level="10" frequency="5" timeframe="120">
  <if_matched_sid>110000</if_matched_sid>
  <same_srcip />
  <description>Multiple authentication failures from the same source IP</description>
</rule>

Diese Regel zählt standardmäßig nur Ereignisse, die demselben registrierten Agent-Kontext zugeordnet sind. Zwei Agents mit identischem Hostnamen besitzen weiterhin unterschiedliche Agent-Identitäten und damit getrennte Frequency-Zähler.

Der ältere Ausdruck <same_source_ip /> wird weiterhin als Alias akzeptiert, ist jedoch als veraltet dokumentiert. Für neue Regeln sollte <same_srcip /> verwendet werden.

Das bedeutet für eine Architektur mit genau einem Collector-Agent pro Kunde: Solange alle Ereignisse eines Kunden über seinen eigenen Agent eintreffen und <global_frequency /> nicht verwendet wird, entspricht die agentbezogene Korrelation faktisch einer mandantenbezogenen Korrelation.

Agent-Labels stehen der Regel-Engine nicht als Decoder-Felder zur Verfügung

Agent-Labels können lokal oder über die zentrale agent.conf gesetzt werden. Sie ergänzen den später erzeugten Alert um zusätzliche Metadaten, beispielsweise:

<agent_config>
  <labels>
    <label key="tenant_name">acme</label>
  </labels>
</agent_config>

Im fertigen JSON-Alert erscheint der Wert anschließend unter:

agent.labels.tenant_name

Diese Labels sind für Suche, Visualisierung, Document Level Security und Index-Routing geeignet. Die Wazuh-Dokumentation beschreibt sie ausdrücklich als zusätzliche Informationen, die in Alerts aufgenommen werden.

Sie sind jedoch keine vom Decoder extrahierten dynamischen Felder. Die klassische Wazuh-Regel-Engine kann deshalb während der Analyse weder mit

<field name="agent.labels.tenant_name">acme</field>

noch mit

<same_field>agent.labels.tenant_name</same_field>

arbeiten. Das Verhalten ist seit Langem dokumentiert: Agent-Metadaten wie Labels, Agent-ID oder Agent-Gruppe sind nicht automatisch als Rule-Matching-Felder verfügbar.

<same_field> funktioniert ausschließlich mit dynamischen Feldern, die bereits während der Decoder-Phase aus dem eingehenden Ereignis extrahiert wurden.

Ein mandantenspezifisches Feld muss daher bereits vor oder während der Decodierung Bestandteil des Events werden, beispielsweise:

tenant: acme

Erst dann kann es in einer Frequency-Regel verwendet werden.

Tenant-weite Korrelation über mehrere Agents

Besitzt ein Kunde mehrere Agents und soll eine Detection über alle seine Agents hinweg korrelieren, reicht <same_field>tenant</same_field> allein nicht aus. Ohne <global_frequency /> bleibt der Frequency-Zähler weiterhin auf den einzelnen Agent beschränkt.

Für eine tenantweite, aber nicht mandantenübergreifende Korrelation wäre folgende Kombination erforderlich:

<rule id="110011" level="10" frequency="5" timeframe="120">
  <if_matched_sid>110000</if_matched_sid>

  <global_frequency />
  <same_field>tenant</same_field>
  <same_srcip />

  <description>
    Multiple authentication failures for tenant $(tenant)
    from source IP $(srcip)
  </description>
</rule>

Voraussetzung ist, dass tenant ein echtes Decoder-Feld ist. <global_frequency /> öffnet den Zähler über die Agent-Grenze hinweg, während <same_field>tenant</same_field> ihn anschließend wieder auf denselben Mandantenwert begrenzt.

Diese Konstruktion muss besonders gründlich getestet werden. Fehlt das Tenant-Feld in einzelnen Events, ist es falsch normalisiert oder wird es von bestimmten Datenquellen nicht geliefert, kann die gewünschte Abgrenzung verloren gehen.

Direkt am Manager eingehende Syslog-Daten sind ein Sonderfall

Die standardmäßige Agent-Abgrenzung hilft nur, wenn das Event tatsächlich über einen registrierten Wazuh-Agent übertragen wird.

Wird ein Firewall-, Router- oder Switch-Syslog direkt an den Wazuh-Manager gesendet, existiert keine kundenspezifische Agent-Identität. Solche managerlokalen oder agentlosen Events können daher nicht allein über die normale Per-Agent-Korrelation voneinander getrennt werden. Wazuh unterstützt den direkten Syslog-Empfang zwar, empfiehlt für zentralisierte Logquellen aber ebenfalls den Einsatz eines Systems mit Wazuh-Agent als vorgeschaltetem Collector.

Für Multi-Tenant-Umgebungen ist deshalb folgende Architektur robuster:

Kundengeräte
    |
    v
Kundenspezifischer Syslog-Collector
mit registriertem Wazuh-Agent
    |
    v
Gemeinsamer Wazuh-Manager

Damit erhalten alle Ereignisse eines Kunden eine eindeutige Agent-Zuordnung. Gleichzeitig lassen sich Labels, Gruppen und zentrale Agent-Konfigurationen nutzen.

Ist ein eigener Collector-Agent nicht möglich, muss der Mandant im Event selbst enthalten sein. Ein vorgelagertes Syslog-Relay, Logstash, Fluent Bit oder eine andere Ingestion-Komponente kann beispielsweise ein Feld wie tenant oder tenant_geo ergänzen, das anschließend durch einen Decoder extrahiert wird.

agent.name ist kein zuverlässiges <field>-Kriterium

Das <field>-Element einer Wazuh-Regel prüft Felder, die vom Decoder aus dem Event extrahiert wurden. agent.name gehört dagegen zu den Alert-Metadaten und ist nicht automatisch ein Decoder-Feld.

Eine Regel wie diese sollte deshalb nicht als versionsstabile Lösung betrachtet werden:

<field name="agent.name" type="osregex">_acme$</field>

Der dokumentierte Mechanismus zur Filterung nach der Herkunft eines Agent-Events ist <location>. Bei klassischen, über einen Agent eingelesenen Logdateien enthält location unter anderem den Agent-Namen und die registrierte Adresse.

Ein präziser Filter auf Agents, deren Name mit _acme endet, kann beispielsweise so aussehen:

<location type="pcre2">^\([^)]*_acme\)\s</location>

Dabei ist zu beachten, dass einige Wazuh-Komponenten und Integrationen statische Location-Werte verwenden. Dazu gehören unter anderem FIM, Syscollector, SCA, Azure-Logs und weitere Module. Bei solchen Datenquellen muss vor dem produktiven Einsatz geprüft werden, ob location tatsächlich den Agent-Namen enthält. Ist das nicht der Fall, bleibt nur ein echtes Decoder-Feld oder eine getrennte Manager-Architektur.

Warum der vorgeschlagene CDB-Key-Value-Vergleich nicht funktioniert

Eine naheliegende Idee ist eine CDB-Liste mit dem Kunden als Schlüssel und den erlaubten Ländern als Wert:

acme:^US$|^PL$
globex:^DE$|^BE$

Dazu könnte folgende Regel formuliert werden:

<list
  field="client_name"
  lookup="match_key_value"
  check_value="country_code">
  etc/lists/client_locations
</list>

Diese Konstruktion vergleicht jedoch nicht zwei Decoder-Felder miteinander.

check_value enthält einen statischen regulären Ausdruck, der gegen den aus der CDB-Liste gelesenen Wert geprüft wird. Der Text country_code wird daher als regulärer Ausdruck interpretiert und nicht durch den Inhalt eines gleichnamigen Decoder-Feldes ersetzt.

Zusätzlich löst match_key_value gerade dann aus, wenn der Wert passt. Damit würde die Regel erlaubte Länder erkennen und nicht unerwartete Länder.

Eine einzelne CDB-Liste kann den Vergleich zwischen client_name und country_code nur abbilden, wenn beide Werte zuvor zu einem Decoder-Feld zusammengeführt wurden:

tenant_geo: acme|US

Die Liste enthält dann die erlaubten Kombinationen als Schlüssel:

acme|US:
acme|PL:
globex|DE:
globex|BE:

Die Regel kann alle nicht vorhandenen Kombinationen erkennen:

<rule id="110102" level="8">
  <if_sid>110100</if_sid>

  <list field="tenant_geo"
        lookup="not_match_key">
    etc/lists/allowed-tenant-countries
  </list>

  <description>
    Login from a country not approved for this tenant:
    $(tenant_geo)
  </description>
</rule>

Der Nachteil bleibt: tenant_geo muss bereits vor der Rule-Evaluation als Decoder-Feld vorhanden sein.

Lösung / Best Practices

Variante 1: Ein Agent pro Mandant und keine globale Frequency

Wenn jeder Kunde genau einen eigenen Collector-Agent besitzt, ist dies die einfachste belastbare Lösung:

  1. Alle kundenspezifischen Quellen werden über diesen Agent eingesammelt.
  2. Frequency-Regeln verwenden kein <global_frequency />.
  3. Für IP-bezogene Korrelation wird <same_srcip /> verwendet.
  4. Agent-Labels dienen ausschließlich der späteren Speicherung und Zugriffskontrolle.
  5. Direkt an den Manager gesendete, nicht zuordenbare Syslog-Daten werden vermieden.

In diesem Modell entspricht die standardmäßige Agent-Grenze der gewünschten Tenant-Grenze.

Variante 2: Länder-Allowlist inline in einer mandantenspezifischen Regel

Bei einer überschaubaren Anzahl von Kunden kann pro Mandant eine eigene Child-Rule angelegt werden:

<rule id="110101" level="8">
  <if_sid>110100</if_sid>

  <location type="pcre2">
    ^\([^)]*_acme\)\s
  </location>

  <field name="srcip_country"
         negate="yes"
         type="pcre2">
    ^(?:US|PL)$
  </field>

  <description>
    ACME: Successful login from non-approved country
    $(srcip_country)
  </description>

  <group>
    authentication_success,geo_policy_violation,
  </group>
</rule>

Die Anker ^ und $ sind notwendig, damit beispielsweise US nicht als Teil eines längeren Wertes interpretiert wird. Durch pcre2 und eine nicht speichernde Gruppe (?:...) bleibt die Bedeutung eindeutig.

Diese Variante eignet sich, wenn:

  • nur wenige Mandanten verwaltet werden,
  • sich die Länderlisten selten ändern,
  • keine zusätzliche Ingestion-Logik eingeführt werden soll,
  • die betroffene Datenquelle einen nutzbaren location-Wert besitzt.

Variante 3: Eine CDB-Allowlist pro Mandant

Für ungefähr 20 oder mehr Kunden ist eine Trennung von Regel-Logik und Policy-Daten meist besser wartbar. Dabei erhält jeder Mandant eine eigene CDB-Liste.

Datei:

/var/ossec/etc/lists/allowed-countries-acme

Inhalt:

US:
PL:

Die Schlüssel müssen eindeutig sein. Ein Wert hinter dem Doppelpunkt ist für diese Allowlist nicht erforderlich. Wazuh unterstützt sowohl reine Schlüssel als auch Schlüssel-Wert-Paare.

Die Liste wird in /var/ossec/etc/ossec.conf registriert:

<ruleset>
  <list>etc/lists/allowed-countries-acme</list>
</ruleset>

Die kundenspezifische Regel verbindet die Herkunftsprüfung mit der jeweiligen Liste:

<rule id="110101" level="8">
  <if_sid>110100</if_sid>

  <location type="pcre2">
    ^\([^)]*_acme\)\s
  </location>

  <list field="srcip_country"
        lookup="not_match_key">
    etc/lists/allowed-countries-acme
  </list>

  <description>
    ACME: Successful login from non-approved country
    $(srcip_country)
  </description>

  <group>
    authentication_success,geo_policy_violation,
  </group>
</rule>

Diese Struktur benötigt weiterhin eine kleine Regel pro Mandant, lagert die eigentlichen Länderwerte aber in wartungsfreundliche Dateien aus. Sie vermeidet reguläre Ausdrücke, partielle Treffer und Änderungen am Decoder.

Nach Änderungen an den Listen beziehungsweise an der Manager-Konfiguration muss der Wazuh-Manager neu gestartet und die Regel getestet werden:

systemctl restart wazuh-manager

Für den beschriebenen Anwendungsfall ist dies der beste Kompromiss, wenn keine Änderung an der Ingestion-Pipeline oder an Decodern möglich ist.

Agent-Labels ausschließlich für das Index-Routing verwenden

Für das Routing fertiger Alerts sind Agent-Labels geeignet. Ein zentral gesetztes Label kann beispielsweise lauten:

<agent_config>
  <labels>
    <label key="tenant_name">acme</label>
  </labels>
</agent_config>

In der Filebeat-Ingest-Pipeline kann anschließend vor dem date_index_name-Processor der Index-Prefix gesetzt werden:

{
  "set": {
    "field": "fields.index_prefix",
    "value": "wazuh-alerts-4.x-{{agent.labels.tenant_name}}-",
    "if": "ctx?.agent?.labels?.tenant_name != null",
    "ignore_failure": false
  }
}

Wazuh dokumentiert dieses Verfahren ausdrücklich für dynamisches Index-Routing in Multi-Tenant-Umgebungen. Die Pipeline verarbeitet den bereits erzeugten Alert und kann daher auf agent.labels.tenant_name zugreifen.

Nach der Änderung muss die Pipeline erneut geladen werden:

filebeat setup --pipelines -E setup.pipelines.overwrite=true

Für die produktive Nutzung sind zusätzliche Schutzmaßnahmen erforderlich:

  • Tenant-Werte müssen zentral kontrolliert und für Indexnamen geeignet sein.
  • Events ohne Tenant-Label benötigen einen definierten Fallback-Index.
  • Index Templates, ISM-Richtlinien und Rollen müssen alle dynamisch erzeugten Indexmuster abdecken.
  • Pipeline-Anpassungen gehören in Versionsverwaltung und Deployment-Automatisierung.
  • Nach Wazuh- oder Filebeat-Upgrades muss geprüft werden, ob die angepasste Pipeline weiterhin vorhanden und kompatibel ist.
  • Das Label darf nicht als alleiniger Sicherheitsmechanismus betrachtet werden, wenn der Agent oder Kunde es selbst verändern kann.

Alert-Indizes sind nicht die gesamte Multi-Tenant-Oberfläche

Eine Trennung von wazuh-alerts-* schützt nicht automatisch alle weiteren Wazuh-Daten.

Inventar-, IT-Hygiene- und Vulnerability-Daten werden unter anderem in separaten Indexfamilien wie wazuh-states-inventory-* und wazuh-states-vulnerabilities-* gespeichert.

Für diese Daten muss ein eigenes Berechtigungskonzept entwickelt werden. Mögliche Ansätze sind:

  • Kunden erhalten keinen direkten Zugriff auf State-Indizes.
  • Document Level Security filtert Dokumente anhand von agent.id.
  • Ein externes Synchronisationsverfahren erzeugt aus mandantenspezifischen Agent-Gruppen die jeweils zulässigen Agent-IDs.
  • Wazuh-API-RBAC und Indexer-Rollen werden gemeinsam geprüft.
  • Bei strengen Compliance- oder Isolationsanforderungen werden getrennte Stacks verwendet.

Auch Active Response muss berücksichtigt werden. In einer gemeinsam genutzten Manager-Umgebung können fehlerhafte Regeln nicht nur falsche Alerts erzeugen, sondern Reaktionen in einem falschen Kundenkontext auslösen.

Query-basierte Alerting-Monitore sind kein vollständiger Ersatz

OpenSearch- beziehungsweise Wazuh-Alerting-Monitore eignen sich für nachgelagerte Abfragen, Aggregationen und Benachrichtigungen. Sie speichern ihre Alert-Zustände jedoch in eigenen Alerting-Systemindizes und erzeugen nicht automatisch einen normalen Wazuh-Alert in wazuh-alerts-*.

Wenn jeder Detection-Treffer als reguläres, mandantenspezifisch geroutetes Wazuh-Alert-Dokument benötigt wird, bleibt die Detection innerhalb der Wazuh-Regel-Engine häufig die passendere Lösung.

Getrennte Manager oder Stacks bleiben die stärkste Isolation

Eine gemeinsam genutzte Wazuh-Manager-Instanz bedeutet immer:

  • einen gemeinsamen Analysekontext,
  • ein gemeinsames Ruleset,
  • gemeinsam verwaltete CDB-Listen,
  • gemeinsam konfigurierte Active Responses,
  • gemeinsame Manager-Ressourcen und Queues.

Für eine strikte Mandantentrennung sollte mindestens ein eigener Manager beziehungsweise Manager-Cluster pro Kunde verwendet werden. Die stärkste Isolation bietet ein vollständiger Stack pro Kunde.

Cross-Cluster Search ermöglicht anschließend eine zentrale SOC-Sicht auf mehrere getrennte Wazuh-Cluster, während die eigentlichen Daten und Analyseprozesse in den jeweiligen Kundenumgebungen verbleiben. Wazuh beschreibt diese Architektur ausdrücklich als geeignet für MSSP-Szenarien.

Lessons Learned / Best Practices

Indexer-Trennung und Detection-Trennung sind unterschiedliche Aufgaben.
RBAC, DLS und getrennte Indizes wirken nach der Alert-Erzeugung. Sie verändern nicht den vorangegangenen Analysekontext des Managers.

Frequency-Regeln nicht unnötig globalisieren.
Solange ein Agent einem Mandanten entspricht, liefert die standardmäßige Per-Agent-Korrelation bereits die gewünschte Abgrenzung. <global_frequency /> sollte nur verwendet werden, wenn eine agentübergreifende Detection tatsächlich erforderlich ist.

Labels als Alert-Metadaten behandeln.
Agent-Labels sind sehr gut für Routing, Suche, Visualisierung und Zugriffssteuerung geeignet. Sie sind jedoch kein Ersatz für Decoder-Felder innerhalb der klassischen Regel-Engine.

Unregistrierte Datenquellen vermeiden.
Direkter Syslog-Empfang am Manager erschwert die Mandantenzuordnung. Ein eigener Collector-Agent pro Kunde schafft eine klare technische Grenze.

Agent-Metadaten nicht mit Decoder-Feldern verwechseln.
agent.name, agent.id, agent.group und agent.labels.* erscheinen im fertigen Alert, sind aber nicht automatisch mit <field> oder <same_field> nutzbar.

location nur nach Prüfung der Datenquelle einsetzen.
Bei klassischen Agent-Logs kann location den Agent-Namen enthalten. Module mit statischen Location-Werten benötigen einen anderen Ansatz.

CDB-Listen für Daten, Regeln für Logik verwenden.
Mandantenspezifische Länderlisten, Benutzerlisten oder Allow-/Denylists sollten nicht dauerhaft als lange reguläre Ausdrücke in Rule-Dateien gepflegt werden.

Keine dynamischen Feldvergleiche von check_value erwarten.
check_value ist ein statischer regulärer Ausdruck. Es ist keine Referenz auf ein zweites Decoder-Feld.

Konfigurationen automatisiert testen.
Für jede Datenquelle sollten Positiv-, Negativ- und Cross-Tenant-Tests mit wazuh-logtest und realen Agent-Events durchgeführt werden. Besonders wichtig sind fehlende Tenant-Felder, identische Hostnamen, identische Quell-IPs und nicht gelabelte Events.

Rest-Risiken einer Shared-Manager-Architektur dokumentieren.
Kostenersparnis und vereinfachter Betrieb stehen einem gemeinsamen Ruleset, eingeschränkter kundenspezifischer Anpassbarkeit und einem größeren Fehlerauswirkungsbereich gegenüber.

Fazit

Eine mandantenfähige Wazuh-Umgebung lässt sich nicht allein durch getrennte Alert-Indizes herstellen. Entscheidend ist, an welcher Stelle der Verarbeitung die Mandanteninformation verfügbar ist.

Normale Frequency-Regeln sind standardmäßig bereits auf den einzelnen Agent begrenzt. Bei einem eigenen Collector-Agent pro Kunde kann diese Eigenschaft effektiv als Tenant-Grenze genutzt werden. Agent-Labels eignen sich dagegen nicht für <same_field> oder andere Rule-Matches, wohl aber für das Routing des fertigen Alerts in kundenspezifische Indizes.

Für eine mandantenspezifische Länderprüfung ohne neue Decoder ist eine kleine Regel pro Kunde in Verbindung mit einer eigenen CDB-Allowlist die wartungsfreundlichste Lösung. Sobald Korrelation über mehrere Agents eines Kunden, direkte Syslog-Eingänge oder strikte regulatorische Isolation erforderlich werden, sollte der Mandant als echtes Decoder-Feld bereitgestellt oder die Architektur auf getrennte Manager beziehungsweise vollständige Wazuh-Stacks umgestellt werden.

Quellenverweise

Mehr zu Wazuh …

Mehr zum Wazuh Ambassador Program …

https://wazuh.slack.com/archives/C07BZJY86G3/p1784806135307529