Guardd

Verhaltensbasierte Anomalieerkennung für Linux, angetrieben von eBPF und maschinellem Lernen.

Guardd lernt, wie sich ein Linux-Host normalerweise verhält, und markiert Aktivitäten, die von dieser Baseline abweichen. Kernel-Sensoren erfassen Prozessausführungen und ausgehende TCP- Verbindungsversuche; ein Isolation Forest bewertet die daraus resultierenden einminütigen Aktivitätsfenster. Warnungen enthalten den Score, den Verhaltenskontext und Erklärungen, die bei der Untersuchung helfen.

Ein Hintergrund-Daemon übernimmt Erfassung, Training und Erkennung. Die Desktop- GUI und die Terminal-Oberfläche ermöglichen die Einsicht in Warnungen und Ressourcennutzung, während der Daemon weiterläuft.

Status: experimentell und in aktiver Entwicklung. Die Erkennungsqualität hängt von der Arbeitslast, der Baseline und den Empfindlichkeitseinstellungen ab.

Installation · Verwendung · Konfiguration · Funktionsweise · Aktualisierung · Fehlerbehebung

Funktionen

• Kernel-Telemetrie: Prozessnamen, ausführbare Pfade, Benutzer, Elternprozess- IDs sowie ausgehende IPv4-TCP-Ziele und -Ports.
• Verhaltensbasierte Erkennung: Aktivitätszählungen, Vielfalt und Neuartigkeit, bewertet gegen eine feste Referenz-Baseline.
• Automatischer Lebenszyklus: anfängliche Erfassung, Modelltraining, Erkennung, wöchentliches Neutraining und Modell-Neuladen in einem systemd-Dienst.
• Persistente Warnungen: SQLite-Speicherung mit Scores, Schweregrad, Erklärungen, Feature-Zusammenfassungen und Kontext; Warnungen werden auch als newline-delimited JSON ausgegeben.
• Desktop-GUI: Übersichts- und Warnungsseiten, Suche, Schweregrad- und Zeitfilter, detaillierte Warnungsinspektion und automatische Aktualisierung.
• Systemübersicht: Dienststatus, CPU- und Speichernutzung, PID, Uptime, Host- und Kernel-Informationen, Größe des Aggregationsfensters und Aktualität der Telemetrie.
• Desktop-Integration: ein Guardd-Anwendungsmenü-Starter und Pinguin-Symbol.
• Terminal-Zugriff: eine curses-TUI und Befehle zum Erfassen, Trainieren, Bewerten und direkten Inspizieren der Telemetrie.

Screenshots

Desktop-Übersicht

Warnungsuntersuchung

Die Desktop-Screenshots verwenden Beispielwarnungen und einen simulierten Dienststatus.

Terminal-Oberfläche

Installation

Voraussetzungen

Der mitgelieferte Installer verwendet apt-get und systemd. Ubuntu 24.04 LTS ist ein praktischer Ausgangspunkt; Debian-Systeme benötigen entsprechende Pakete. Andere Distributionen erfordern eine manuelle Installation der Abhängigkeiten.

• Python 3.11 oder neuer verfügbar als python3. Das Standard-Python 3.10 von Ubuntu 22.04 erfüllt die Paketanforderung nicht.
• Ein Linux-Kernel mit eBPF, BTF unter /sys/kernel/btf/vmlinux und den erforderlichen Prozess- und Socket-Tracepoints.
• Clang/LLVM, libbpf-Entwicklungsheader, libelf, eine C-Build-Toolchain und bpftool zum Generieren von Kernel-Headern und BPF-Skeletons.
• Root-Rechte zum Installieren des Dienstes und Ausführen der Sensoren.
• Eine grafische Desktop-Sitzung für die optionale PySide6-GUI.

Unter Ubuntu installieren Sie Git und die Kernel-Tools, bevor Sie den Installer ausführen:```bash sudo apt-get update sudo apt-get install -y git linux-tools-common "linux-tools-$(uname -r)" python3 --version bpftool version test -r /sys/kernel/btf/vmlinux && echo "Kernel BTF available"

Das Paket kernel-tools muss zu Ihrem laufenden Kernel passen. Unter Debian ist `bpftool` als separates Paket verfügbar. Der Installer stellt die anderen Build- und Python-Abhängigkeiten bereit, installiert `bpftool` jedoch nicht explizit.

### Daemon und Desktop-GUI installieren```bash
git clone https://github.com/benny-e/guardd.git
cd guardd
sudo bash install.sh --gui

Für eine headless-Installation führen Sie stattdessen sudo bash install.sh aus.

Der Installer kopiert die Anwendung nach /opt/guardd, erstellt ihre virtuelle Umgebung, baut den eBPF-Collector, installiert /usr/local/bin/guardd und aktiviert guardd.service beim Booten. Er startet den Dienst nicht. Mit --gui installiert er außerdem die Qt-Laufzeitabhängigkeiten, den Desktop-Launcher und das Icon.

Die installierten Pfade festlegen

Öffnen Sie vor dem ersten Start die installierte Konfiguration:```bash sudoedit /opt/guardd/config.toml

Setzen Sie den Abschnitt `[paths]` auf absolute Pfade:```toml
[paths]
sensor_path = "/opt/guardd/ebpf/guardd"
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"

Das Repository-Konfiguration verwendet relative Pfade. Diese funktionieren aus dem Arbeitsverzeichnis /opt/guardd des Dienstes, aber ein Desktop-Starter kann von einem anderen Ort aus starten. Absolute Pfade ermöglichen es dem Daemon, der GUI und der CLI, dieselben Daten zu verwenden.

Überprüfen Sie die Trainingseinstellungen in Configuration und starten Sie dann:```bash sudo systemctl start guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -f

Der erste Durchlauf sammelt Daten, bevor ein Modell verfügbar ist. Ein aktiver Dienst kann sich noch in dieser Sammelphase befinden; prüfen Sie seine Logs auf Training und Erkennung.

## Verwendung

### Desktop-GUI

Öffnen Sie **Guardd** über Ihr Anwendungsmenü oder führen Sie aus:```bash
guardd gui

Führe die GUI als dein regulärer Desktop-Benutzer aus. Sie liest die vorhandene Datenbank und aktualisiert alle fünf Sekunden. Beim Schließen läuft der Daemon weiter.

Seite	Was du tun kannst
Übersicht	Prüfe den Dienst, heutige Alarme, Verfügbarkeit der Modelldatei, CPU-/Speicherauslastung, PID, Uptime, Host-/Kernel-Details, Fenstergröße von 60 Sekunden und aktuelle Telemetrie. Wähle einen aktuellen Alarm aus, um ihn zu untersuchen.
Alarme	Suche nach Prozessnamen, Pfaden, Zielen und Gründen; filtere nach Schweregrad und den letzten 24 Stunden, 7 Tagen, 30 Tagen oder der gesamten Zeit; wähle einen Alarm aus, um seinen Score, Schwellenwert, Erklärungen, Aktivität und Kontext anzuzeigen.

Verwende Aktualisieren für eine sofortige Aktualisierung. Zeiten verwenden deine lokale Zeitzone, und die Tagessummen der Übersicht decken den lokalen Kalendertag unabhängig von Filtern ab.

Um eine andere Datenbank auszuwählen oder das angezeigte Alarmlimit zu erhöhen:```bash guardd gui --db-path /opt/guardd/data/features.db --model-path /opt/guardd/data/model.bundle --limit 500

Die GUI ist ein schreibgeschützter Viewer: Sammlung, Training und Dienststeuerung erfolgen
über den Daemon und die CLI. Modellverfügbarkeit bedeutet, dass eine Datei existiert, nicht dass ihr
Inhalt gültig ist oder dass die Erkennung gestartet wurde. Die GUI lädt keine gepickelten
Modelle. Ressourcenmetriken decken den gesamten systemd-Dienst ab, einschließlich des Sensors;
100 % CPU entspricht einem logischen Kern. Der erste CPU-Messwert benötigt zwei Samples.