StarletteDeprecationWarning in Wazuh 4.14.7: Ursache und sicherer Umgang mit agent_upgrade

von

Einleitung

Nach einem Upgrade des Wazuh Managers auf Version 4.14.7 kann beim Aufruf des Kommandozeilenwerkzeugs agent_upgrade eine Python-Warnung erscheinen:

/var/ossec/framework/python/lib/python3.10/site-packages/connexion/apps/abstract.py:9:
StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated;
install `httpx2` instead.
  from starlette.testclient import TestClient

Die Meldung wirkt auf den ersten Blick wie ein Fehler im Agent-Upgrade-Prozess. Tatsächlich handelt es sich jedoch um eine Deprecation-Warnung aus der mit Wazuh ausgelieferten Python-Laufzeitumgebung. Das eigentliche CLI-Werkzeug und der Upgrade-Mechanismus können weiterhin ordnungsgemäß funktionieren.

Für Administratoren ist eine korrekte Einordnung dennoch wichtig: Warnungen auf stderr können Monitoring, Automatisierung und Skripte beeinflussen, selbst wenn der eigentliche Befehl erfolgreich ausgeführt wird.

Ausgangslage / Problemstellung

Das Verhalten tritt nach dem Upgrade eines paketbasiert installierten Wazuh Managers auf Version 4.14.7 auf. Bestätigt wurde es unter anderem für Ubuntu 22.04 mit der in Wazuh eingebetteten Python-3.10-Umgebung.

Bereits ein Aufruf von agent_upgrade zeigt die Warnung vor der normalen Ausgabe des Programms:

/var/ossec/bin/agent_upgrade

Danach erscheint erwartungsgemäß die Hilfe zur Befehlssyntax:

usage: agent_upgrade.py [-h] [-a AGENTS [AGENTS ...]]
                        [-r REPOSITORY]
                        [-v VERSION]
                        [-F]
                        [-s]
                        [-l]
                        [-f FILE]
                        [-d]
                        [-x EXECUTE]
                        [--http]
                        [--package_type PACKAGE_TYPE]

Die Usage-Ausgabe entsteht, weil weder eine Aktion noch eine Agent-ID angegeben wurde. Sie ist unabhängig von der davor ausgegebenen StarletteDeprecationWarning.

Auch bei gültigen Befehlen kann die Warnung erscheinen, beispielsweise beim Auflisten aktualisierbarer Agents:

/var/ossec/bin/agent_upgrade -l

Oder beim Upgrade eines konkreten Agents:

/var/ossec/bin/agent_upgrade -a 001

Der Fehlerbericht zu Wazuh 4.14.7 bestätigt, dass das Agent-Upgrade trotz der Warnung erfolgreich abgeschlossen werden kann und der Prozess mit Exit-Code 0 endet.

Technische Analyse

Die Warnung stammt nicht vom Agent-Upgrade-Modul

agent_upgrade ist ein Python-basiertes Werkzeug des Wazuh Frameworks. Beim Start lädt das Skript verschiedene Module aus der mit dem Wazuh Manager ausgelieferten Python-Umgebung unter:

/var/ossec/framework/python/

Während dieser Importkette wird das Python-Paket connexion geladen. connexion importiert seinerseits starlette.testclient.TestClient. Die verwendete Starlette-Version erkennt dabei eine veraltete Kombination mit dem installierten httpx-Paket und erzeugt die folgende Warnung:

StarletteDeprecationWarning:
Using `httpx` with `starlette.testclient` is deprecated;
install `httpx2` instead.

Für Wazuh 4.14.7 wurden in den offiziellen Fehlerberichten folgende Paketstände dokumentiert:

connexion==3.1.0
starlette==1.3.1
httpx==0.26.0

Der relevante Code wird beim Start importiert, obwohl agent_upgrade den Starlette-Testclient für den eigentlichen Remote-Upgrade-Prozess nicht benötigt. Die Warnung ist daher ein Seiteneffekt der Python-Abhängigkeiten und kein Hinweis darauf, dass die Kommunikation mit dem Agent, das WPK-Paket oder die Upgrade-Task fehlgeschlagen ist.

Warum die Meldung nach dem Upgrade auf 4.14.7 erscheint

Das Verhalten wurde durch eine Änderung der eingebetteten Python-Abhängigkeiten sichtbar. Der dokumentierte Fehlerbericht führt die Warnung auf eine Aktualisierung von Starlette zurück, während weiterhin die bisherige httpx-Abhängigkeit verwendet wurde.

Vor Wazuh 4.14.7 trat die Meldung in diesem Ausführungspfad nicht auf. Nach der Aktualisierung erzeugt Starlette die Warnung bereits beim Import von connexion.

Keine unmittelbare Sicherheitslücke

Die Warnung beschreibt eine künftig nicht mehr unterstützte beziehungsweise zu ersetzende Bibliotheksverwendung. Sie weist nicht auf eine fehlgeschlagene Integritätsprüfung, eine unsichere Agent-Verbindung oder ein kompromittiertes Upgrade-Paket hin.

Der Wazuh-Agent-Upgrade-Prozess arbeitet weiterhin über das Agent-Upgrade-Modul des Managers. Dieses koordiniert die Auswahl beziehungsweise Bereitstellung des Upgrade-Pakets, die Übertragung an den Agent, die Installation und die Rückmeldung des Ergebnisses. Die grundsätzliche Funktionsweise des Moduls wird durch die Python-Warnung nicht verändert.

Trotzdem ist die Meldung betrieblich relevant. Sie wird über den Fehlerausgabekanal stderr ausgegeben und kann dadurch:

  • Logdateien mit wiederkehrenden Warnungen füllen,
  • Monitoring-Regeln auslösen,
  • Wrapper-Skripte zu Fehlinterpretationen verleiten,
  • maschinell verarbeitete Ausgaben verunreinigen,
  • oder bei ungeeigneter Fehlerbehandlung einen scheinbaren Fehlschlag erzeugen.

Unterschied zwischen Warnung, Usage-Ausgabe und echtem Fehler

Bei der Analyse sollten drei Ausgaben getrennt betrachtet werden:

  1. Deprecation-WarnungStarletteDeprecationWarning Sie stammt aus den Python-Abhängigkeiten.
  2. Usage-Ausgabeusage: agent_upgrade.py ... Sie erscheint, wenn der Befehl ohne erforderliche Aktionsparameter ausgeführt wird.
  3. Ergebnis des Agent-UpgradesDieses zeigt, ob das Auflisten oder Aktualisieren der Agents tatsächlich erfolgreich war.

Die alleinige Präsenz der Starlette-Warnung reicht deshalb nicht aus, um einen Fehler des Agent-Upgrades anzunehmen.

Warum PYTHONWARNINGS=ignore::DeprecationWarning nicht greift

Eine naheliegende Umgehung wäre:

PYTHONWARNINGS="ignore::DeprecationWarning" \
  /var/ossec/bin/agent_upgrade -l

Diese Variante unterdrückt die Meldung jedoch nicht zuverlässig. Starlette definiert StarletteDeprecationWarning als Unterklasse von UserWarning und nicht als normale DeprecationWarning.

Ein Filter ausschließlich für DeprecationWarning erfasst die Meldung daher nicht.

Abgrenzung zu Wazuh 5.0

Ein vergleichbares Verhalten wurde zunächst für die Wazuh-5.0-Entwicklungslinie beim Werkzeug cluster_control dokumentiert. Dort erschien dieselbe Warnung ebenfalls vor der eigentlichen CLI-Ausgabe.

Die Korrektur für Wazuh 5.0 wurde über Pull Request #37509 umgesetzt. Dabei wird die spezifische Upstream-Warnung gezielt gefiltert und die Importreihenfolge von agent_upgrade.py angepasst. Ein einfaches Upgrade der Connexion-Abhängigkeit war laut Fehleranalyse nicht ausreichend, weil das Verhalten auch in neueren Connexion-Versionen vorhanden war.

Für die 4.x-Linie wurde das Verhalten separat als Fehler von Wazuh 4.14.7 erfasst. Der entsprechende Vorgang wurde dem Release-Projekt für Wazuh 4.14.8 zugeordnet und als erledigt markiert. Administratoren sollten dennoch anhand der tatsächlich installierten Version prüfen, ob die Korrektur bereits in ihrem verwendeten Paket enthalten ist.

Lösung / Best Practices

1. Zuerst die Funktion des Werkzeugs prüfen

Zum Auflisten möglicher Agent-Upgrades sollte der dokumentierte Befehl verwendet werden:

sudo /var/ossec/bin/agent_upgrade -l

Die Ausgabe sollte eine Liste der Agents enthalten, für die ein Upgrade verfügbar ist:

ID    Name                       Version
001   linux-server-01            4.14.6
002   windows-client-01          4.14.5

Ein bestimmter Agent kann anschließend über seine ID aktualisiert werden:

sudo /var/ossec/bin/agent_upgrade -a 001

Mehrere Agents lassen sich gemeinsam angeben:

sudo /var/ossec/bin/agent_upgrade -a 001 002

Die vollständige Syntax und weitere Optionen wie Repository, Zielversion, Paketdatei oder Pakettyp sind in der offiziellen Referenz beschrieben.

2. Exit-Code kontrollieren

Der zuverlässigste erste Indikator für den Erfolg eines CLI-Aufrufs ist der Exit-Code:

sudo /var/ossec/bin/agent_upgrade -l
echo $?

Bei einem erfolgreichen Aufruf sollte typischerweise Folgendes erscheinen:

0

Bei einem Agent-Upgrade sollten zusätzlich die Ergebniszeilen des Werkzeugs geprüft werden:

sudo /var/ossec/bin/agent_upgrade -a 001
result=$?

echo "Exit-Code: ${result}"

Eine Warnung auf stderr darf nicht automatisch mit einem fehlgeschlagenen Upgrade gleichgesetzt werden.

3. Agent-Version nach dem Upgrade verifizieren

Nach einem Remote-Upgrade sollte kontrolliert werden, ob der Agent wieder verbunden ist und die erwartete Version meldet.

Dazu kann beispielsweise agent_control verwendet werden:

sudo /var/ossec/bin/agent_control -i 001

Alternativ lässt sich die Agent-Liste anzeigen:

sudo /var/ossec/bin/agent_control -lc

Relevante Prüfpunkte sind:

  • Status des Agents,
  • gemeldete Wazuh-Version,
  • Zeitpunkt der letzten Verbindung,
  • erfolgreiche Wiederaufnahme der Ereignisübertragung,
  • keine wiederkehrenden Upgrade-Fehler im Manager- oder Agent-Log.

Auf dem Manager sollten insbesondere folgende Logs berücksichtigt werden:

/var/ossec/logs/ossec.log
/var/ossec/logs/api.log

Auf Linux-Agents befindet sich das zentrale Wazuh-Log üblicherweise unter:

/var/ossec/logs/ossec.log

4. Warnung nur gezielt ausblenden

Für interaktive Einzelaufrufe kann die Fehlerausgabe verworfen werden:

sudo /var/ossec/bin/agent_upgrade -l 2>/dev/null

Das entfernt die Warnung, blendet jedoch auch echte Fehlermeldungen aus. Diese Methode ist deshalb für produktive Automatisierung ungeeignet.

Eine bessere Übergangslösung ist das getrennte Erfassen von Standard- und Fehlerausgabe:

stdout_file=$(mktemp)
stderr_file=$(mktemp)

sudo /var/ossec/bin/agent_upgrade -l \
  >"${stdout_file}" \
  2>"${stderr_file}"

rc=$?

cat "${stdout_file}"

if grep -v "StarletteDeprecationWarning" "${stderr_file}" |
   grep -v "starlette.testclient" |
   grep -v "from starlette.testclient import TestClient" |
   grep -q .; then
    echo "Zusätzliche Fehlermeldungen wurden erkannt:" >&2
    cat "${stderr_file}" >&2
fi

rm -f "${stdout_file}" "${stderr_file}"
exit "${rc}"

Bei langfristig betriebenen Skripten sollte der Filter möglichst eng auf die bekannte Warnung begrenzt bleiben. Ein pauschales Verwerfen von stderr kann relevante Fehler verbergen.

5. Keine manuellen Paketänderungen in der Wazuh-Python-Umgebung

Die Warnung fordert scheinbar dazu auf, httpx2 zu installieren. Administratoren sollten diese Empfehlung nicht direkt mit pip innerhalb der von Wazuh verwalteten Python-Umgebung umsetzen.

Von Befehlen wie dem folgenden ist abzuraten:

/var/ossec/framework/python/bin/pip install httpx2

Auch ein manuelles Ersetzen von starlette, connexion oder httpx ist nicht empfehlenswert.

Die Python-Abhängigkeiten unter /var/ossec/framework/python/ gehören zur getesteten Wazuh-Paketinstallation. Eigenständige Änderungen können:

  • die Wazuh API beeinträchtigen,
  • CLI-Werkzeuge inkompatibel machen,
  • Paketprüfungen und spätere Updates erschweren,
  • zu nicht reproduzierbaren Fehlerzuständen führen,
  • oder beim nächsten Paketupgrade überschrieben werden.

Die nachhaltige Lösung besteht in einem offiziellen Wazuh-Update, das die Importreihenfolge beziehungsweise den Warnungsfilter korrigiert.

6. Auf eine korrigierte Wazuh-Version aktualisieren

Der Fehler wurde für Wazuh 4.14.7 offiziell erfasst. Der 4.x-Vorgang ist im Release-Projekt für Version 4.14.8 als erledigt gekennzeichnet. Vor einem Update sollten die Release Notes und die tatsächlich verfügbaren Pakete geprüft werden.

Nach einem Manager-Update sollte das Verhalten erneut getestet werden:

sudo /var/ossec/bin/agent_upgrade -l

Die Ausgabe sollte anschließend ohne die Starlette-Warnung erscheinen.

7. Upgrade-Automatisierungen robust gestalten

Automatisierungen sollten nicht allein anhand einer leeren stderr-Ausgabe über Erfolg oder Misserfolg entscheiden. Sinnvoll ist eine kombinierte Prüfung aus:

  • Exit-Code,
  • erwarteter Standardausgabe,
  • Upgrade-Ergebnis pro Agent,
  • anschließend gemeldeter Agent-Version,
  • und erneutem Verbindungsstatus.

Ein einfaches Grundmuster kann wie folgt aussehen:

#!/usr/bin/env bash

set -u
set -o pipefail

agent_id="001"
output_file=$(mktemp)
error_file=$(mktemp)

cleanup() {
    rm -f "${output_file}" "${error_file}"
}
trap cleanup EXIT

sudo /var/ossec/bin/agent_upgrade -a "${agent_id}" \
    >"${output_file}" \
    2>"${error_file}"

rc=$?

cat "${output_file}"

if [[ ${rc} -ne 0 ]]; then
    echo "Agent-Upgrade fehlgeschlagen, Exit-Code: ${rc}" >&2
    cat "${error_file}" >&2
    exit "${rc}"
fi

filtered_errors=$(
    grep -v "StarletteDeprecationWarning" "${error_file}" |
    grep -v "Using .*httpx.*starlette.testclient" |
    grep -v "from starlette.testclient import TestClient" ||
    true
)

if [[ -n "${filtered_errors}" ]]; then
    echo "Unerwartete Meldungen auf stderr:" >&2
    printf '%s\n' "${filtered_errors}" >&2
    exit 1
fi

echo "CLI-Aufruf erfolgreich. Agent-Status und Version müssen noch verifiziert werden."

Dieses Beispiel ist bewusst konservativ: Die bekannte Warnung wird toleriert, andere Fehlerausgaben führen weiterhin zu einer Prüfung beziehungsweise einem Abbruch.

Lessons Learned / Best Practices

CLI-Warnungen nicht isoliert bewerten

Eine Warnung aus einer Bibliothek ist nicht automatisch ein Funktionsfehler der darüberliegenden Wazuh-Komponente. Für eine belastbare Diagnose müssen stets Exit-Code, Nutzdaten der Ausgabe und der tatsächliche Zustand des Agents gemeinsam betrachtet werden.

Eingebettete Abhängigkeiten nicht manuell reparieren

Wazuh liefert eine eigene Python-Laufzeitumgebung mit aufeinander abgestimmten Paketen aus. Direkte Änderungen mit pip können kurzfristig eine Warnung beseitigen, gleichzeitig aber wesentlich kritischere Probleme in API, Framework oder Upgrade-Werkzeugen verursachen.

stderr in Automatisierungen differenziert behandeln

Ein erfolgreicher Prozess darf Meldungen auf stderr erzeugen. Skripte sollten deshalb nicht pauschal jede Fehlerausgabe als Fehlschlag interpretieren. Umgekehrt darf stderr auch nicht vollständig verworfen werden.

Bewährt hat sich:

Exit-Code prüfen
+
stdout validieren
+
bekannte Warnung gezielt filtern
+
unbekannte stderr-Ausgaben eskalieren
+
Zielzustand verifizieren

Upgrades zunächst mit wenigen Agents testen

Remote-Upgrades sollten zunächst mit einem nicht kritischen Test-Agent durchgeführt werden:

sudo /var/ossec/bin/agent_upgrade -a 001

Erst nach erfolgreicher Prüfung von Agent-Version, Verbindung und Ereignisfluss sollte das Upgrade auf weitere Systeme ausgerollt werden.

Paketversionen zwischen Manager und Agents planen

Der Wazuh Manager muss eine Agent-Version unterstützen, bevor Agents auf diese Version aktualisiert werden. Außerdem sollten große Agent-Gruppen gestaffelt aktualisiert werden, damit Fehler, Lastspitzen oder plattformspezifische Probleme früh erkannt werden.

Bekannte Warnungen dokumentieren

Während des Übergangs zu einer korrigierten Version sollte die Warnung in internen Betriebsdokumentationen und Runbooks erfasst werden. Dazu gehören:

  • betroffene Wazuh-Version,
  • exakter Warnungstext,
  • bekannte Ursache,
  • erwarteter Exit-Code,
  • Verifikationsschritte,
  • und geplante Zielversion für die Fehlerbehebung.

So wird verhindert, dass dieselbe Meldung bei jedem Auftreten erneut als unbekannter Incident behandelt wird.

Fazit

Die StarletteDeprecationWarning beim Aufruf von agent_upgrade unter Wazuh 4.14.7 ist ein bestätigter Seiteneffekt der eingebetteten Python-Abhängigkeiten. Die Warnung entsteht beim Import von connexion und starlette.testclient; sie weist nicht automatisch auf einen fehlgeschlagenen Agent-Upgrade-Prozess hin.

Administratoren sollten die Funktion über einen gültigen agent_upgrade-Aufruf, den Exit-Code, das Upgrade-Ergebnis und die anschließend gemeldete Agent-Version prüfen. Manuelle Änderungen an der Wazuh-Python-Umgebung sind zu vermeiden. Für Skripte empfiehlt sich ein gezielter Filter der bekannten Warnung, ohne andere Meldungen auf stderr zu unterdrücken.

Die nachhaltige Behebung erfolgt über ein offizielles Wazuh-Update. Bis dieses auf dem jeweiligen System installiert ist, lässt sich das Verhalten sicher handhaben, sofern Warnung und tatsächliches Upgrade-Ergebnis konsequent voneinander getrennt werden.

Quellenverweise

Wazuh-Dokumentation: agent_upgrade
https://documentation.wazuh.com/current/user-manual/reference/tools/agent-upgrade.html

Wazuh-Dokumentation: Remote-Upgrades von Agents
https://documentation.wazuh.com/current/user-manual/agent/agent-management/remote-upgrading/upgrading-agent.html

Wazuh-Dokumentation: Funktionsweise des Agent-Upgrade-Moduls
https://documentation.wazuh.com/current/user-manual/agent/agent-management/remote-upgrading/agent-upgrade-module.html

GitHub Issue #37501: Deprecation warning shown when running cluster_control -a
https://github.com/wazuh/wazuh/issues/37501

GitHub Pull Request #37509: Remove startup deprecation warning from cluster_control and agent_upgrade
https://github.com/wazuh/wazuh/pull/37509

GitHub Issue #38084: Deprecation warning shown when running agent_upgrade
https://github.com/wazuh/wazuh/issues/38084

GitHub Issue #38116: Backport der Korrektur für Wazuh 4.14.7
https://github.com/wazuh/wazuh/issues/38116

Mehr zu Wazuh …

Mehr zum Wazuh Ambassador Program …

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