Python Wazuh Alert Reporter

Projektbeschreibung

Dieses Projekt ist ein kleines Python-Lernprojekt im Bereich Cybersecurity.

Das Skript verbindet sich mit der Wazuh API, liest die registrierten Wazuh Agents aus und erstellt daraus einen einfachen Markdown-Report.

Das Projekt baut auf meinem lokalen Wazuh SIEM Lab auf. Ziel war es, erste praktische Erfahrungen mit Python, API-Zugriffen, JSON-Daten und einfacher Security-Monitoring-Automatisierung zu sammeln.

---

Ziel des Projekts

Ziel war es, ein Python-Skript zu entwickeln, das Daten aus einer Wazuh-Umgebung abrufen und strukturiert ausgeben kann.

Umgesetzt wurden:

• Verbindung zur Wazuh API
• Authentifizierung über API-Zugangsdaten
• Abruf der registrierten Wazuh Agents
• Anzeige aktiver und getrennter Agents
• Ausgabe der Agent-Daten in der Konsole
• Erstellung eines Markdown-Reports
• Nutzung einer lokalen .env-Datei für sensible Zugangsdaten
• Zugriff auf die Wazuh API über einen SSH-Tunnel

---

Verwendete Technologien

Komponente	Technologie
Programmiersprache	Python 3.12
API-Zugriff	requests
Umgebungsvariablen	python-dotenv
HTTPS-Warnungen	urllib3
SIEM-System	Wazuh
Betriebssystem	Windows 11
Testumgebung	Lokales Wazuh SIEM Lab
Verbindung	SSH-Tunnel zur Wazuh API

---

Projektstruktur

python-wazuh-alert-reporter/
├── src/
│   └── main.py
├── docs/
│   └── example-wazuh-agent-report.md
├── screenshots/
│   └── python-wazuh-agent-report-output.png
├── .env.example
├── .gitignore
├── README.md
└── requirements.txt

---

Sicherheit

Die echten Zugangsdaten werden lokal in einer .env-Datei gespeichert.

Diese Datei wird nicht auf GitHub hochgeladen.

Die Datei .env.example dient nur als Vorlage:

WAZUH_URL=https://127.0.0.1:55000
WAZUH_USER=your_api_user
WAZUH_PASSWORD=your_api_password
VERIFY_SSL=false

Die echte .env bleibt lokal und ist in der .gitignore ausgeschlossen.

---

Funktionsweise

Das Skript führt folgende Schritte aus:

1. .env-Datei laden
2. Verbindung zur Wazuh API herstellen
3. Authentifizierung durchführen
4. API-Token erhalten
5. Agent-Daten über den Endpoint /agents abrufen
6. Agent-Daten in der Konsole anzeigen
7. Markdown-Report im Ordner reports erzeugen

---

Beispielausgabe

Connecting to Wazuh API...
Authentication successful.

Wazuh Agent Report
==================
Total agents:        2
Active agents:       2
Disconnected agents: 0

Agents
------
- ID: 000 | Name: wazuh-server | IP: 127.0.0.1 | Status: active | OS: Ubuntu 24.04.4 LTS
- ID: 001 | Name: wazuh-client | IP: 192.168.56.102 | Status: active | OS: Ubuntu 24.04.4 LTS

Markdown report created: reports\wazuh-agent-report.md

---

Screenshot

---

Beispiel-Report

Ein Beispiel des erzeugten Reports befindet sich hier:

docs/example-wazuh-agent-report.md

Der Report enthält:

• Erstellungszeitpunkt
• Anzahl aller Agents
• Anzahl aktiver Agents
• Anzahl getrennter Agents
• Agent-ID
• Agent-Name
• IP-Adresse
• Status
• Betriebssystem

---

Installation

Repository klonen:

git clone https://github.com/n-somas/python-wazuh-alert-reporter.git

In den Projektordner wechseln:

cd python-wazuh-alert-reporter

Virtuelle Umgebung erstellen:

python -m venv .venv

Virtuelle Umgebung aktivieren:

.\.venv\Scripts\Activate.ps1

Abhängigkeiten installieren:

pip install -r requirements.txt

---

Konfiguration

Vor der Ausführung muss lokal eine .env-Datei angelegt werden.

Dafür kann die Beispiel-Datei als Vorlage genutzt werden:

copy .env.example .env

Danach müssen die Werte in der .env angepasst werden:

WAZUH_URL=https://127.0.0.1:55000
WAZUH_USER=your_api_user
WAZUH_PASSWORD=your_api_password
VERIFY_SSL=false

---

SSH-Tunnel zur Wazuh API

In meiner lokalen Testumgebung war die Wazuh API nicht direkt vom Windows-Host erreichbar. Deshalb wurde ein SSH-Tunnel verwendet.

Beispiel:

ssh -L 55000:localhost:55000 nilo@192.168.56.101

Danach kann das Python-Skript über folgende lokale Adresse auf die Wazuh API zugreifen:

https://127.0.0.1:55000

---

Ausführung

Das Skript wird mit folgendem Befehl gestartet:

python src\main.py

---

Ergebnis

Das Skript konnte erfolgreich eine Verbindung zur Wazuh API herstellen und die vorhandenen Agents auslesen.

Erkannte Agents:

ID	Name	IP	Status	Betriebssystem
000	wazuh-server	127.0.0.1	active	Ubuntu 24.04.4 LTS
001	wazuh-client	192.168.56.102	active	Ubuntu 24.04.4 LTS

Zusätzlich wurde ein Markdown-Report erzeugt:

reports/wazuh-agent-report.md

Für GitHub wurde ein Beispiel-Report unter docs/ abgelegt.

---

Gelernte Inhalte

Durch dieses Projekt wurden folgende Grundlagen praktisch geübt:

• Python-Projektstruktur
• Virtuelle Python-Umgebung
• Arbeiten mit externen Bibliotheken
• API-Zugriff mit requests
• Authentifizierung gegen eine REST-API
• Umgang mit .env-Dateien
• JSON-Verarbeitung
• Fehleranalyse bei API-Verbindungen
• Markdown-Report-Erstellung
• Erste Automatisierung im Security-Monitoring-Umfeld

---

Hinweis

Dieses Projekt ist ein lokales Lernprojekt.

Es enthält keine produktiven Zugangsdaten, keine Unternehmensdaten und keine sensiblen Informationen.