guardd

Maschinell lernbasierte Verhaltensanomalieerkennung für Linux mit eBPF + Isolation Forest

Guardd sammelt systemnahe Ereignisse (Prozessausführung, Netzwerkaktivität), aggregiert sie zu zeitfensterbasierten Merkmalsvektoren und erkennt anomales Verhalten mittels eines maschinellen Lernmodells.

Guardd konzentriert sich auf die Erkennung unbekannter Bedrohungen

[!WARNING] Dieses Projekt befindet sich noch in der Entwicklung Funktionen und Erkennungsgenauigkeit werden aktiv verbessert Feedback, Vorschläge und Beiträge sind willkommen

Funktionsweise

guardd wird als einzelner systemd-Dienst ausgeführt, der den gesamten Lebenszyklus von Datensammlung, Training und Erkennung verwaltet.

Beim Start:

Wenn kein Modell existiert, beginnt guardd mit der Erfassung von Basisverhaltensdaten Es sammelt standardmäßig 1 Tag Daten, um zunächst darauf zu trainieren Sobald das Training erfolgreich ist, wechselt es automatisch in den Erkennungsmodus

Während des Betriebs:

Systemaktivitäten werden kontinuierlich in Zeitfenster aggregiert und in Merkmalsvektoren umgewandelt Jedes Fenster wird vom trainierten Isolation-Forest-Modell bewertet Anomalien werden als NDJSON ausgegeben

Fortlaufend:

Das Modell wird automatisch einmal pro Woche neu trainiert Die Erkennung wird sofort nach dem erneuten Training mit dem aktualisierten Modell fortgesetzt

Installation

1. Repository klonen

git clone https://github.com/benny-e/guardd.git
cd guardd

2. Installationsskript ausführen

sudo bash install.sh

Dies wird:

Systemabhängigkeiten installieren Das Projekt nach /opt/guardd kopieren Eine Python-Virtual-Umgebung erstellen Das Paket installieren eBPF-Komponenten erstellen Den systemd-Dienst installieren

Verwendung

Dienst starten

sudo systemctl start guardd.service

Status prüfen

systemctl status guardd.service

Logs anzeigen

journalctl -u guardd.service -f

Terminal-TUI

guardd enthält eine Terminal-Benutzeroberfläche zum Durchsuchen aktueller Warnungen und Suchen von Anomalien

Zum Starten: (nach dem Start von guardd.service)

guardd tui

Ausführen ohne systemd

Sie können guardd direkt von der Befehlszeile aus ausführen, ohne den systemd-Dienst zu installieren. Dies kann konfiguriert werden, um mit anderen Init-Systemen zu laufen

Vollständigen Daemon ausführen

sudo guardd daemon

Einzelne Komponenten ausführen

Daten sammeln:

sudo guardd collect

Modell trainieren:

sudo guardd train

Erkennung ausführen:

sudo guardd detect

Konfiguration

guardd unterstützt Konfiguration über eine config.toml-Datei.

Standardmäßig sucht der Daemon nach:

/opt/guardd/config.toml

Beispiel

[daemon]
mode = "auto"
bootstrap_retry_seconds = 60
retrain_interval_seconds = 604800

[training]
min_training_rows = 1
contamination = 0.01
n_estimators = 200
threshold_percentile = 10.0

[paths]
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"
guardd_path = "/opt/guardd/ebpf/guardd"

[daemon]

Steuert den Lebenszyklus von guardd.

mode -- "auto" → vollständige Pipeline (collect → train → detect) -- "collect" → nur Daten sammeln -- "detect" → nur Erkennung ausführen (erfordert Modell)

bootstrap_retry_seconds -- Wie oft guardd versucht, das initiale Training durchzuführen, wenn kein Modell vorhanden ist -- Während dieser Phase sammelt guardd Daten und pausiert regelmäßig, um ein Training zu versuchen

retrain_interval_seconds -- Wie oft das Modell nach dem initialen Bootstrap neu trainiert wird -- Standard: 7 Tage

[train]

Steuert Modellverhalten und -anforderungen.

min_training_rows -- Mindestanzahl an Merkmalsfenstern, die zum Training erforderlich sind -- Wenn nicht erreicht, schlägt das Training fehl und wird später wiederholt

contamination -- Erwarteter Anteil von Anomalien in den Daten -- Wird direkt an Isolation Forest übergeben -- Typische Werte: 0.01–0.05

n_estimators -- Anzahl der Bäume im Isolation Forest -- Höher = genauer, langsameres Training

threshold_percentile -- Bestimmt den Grenzwert für Anomalien -- Niedriger = aggressivere Erkennung

[paths]

Steuert, wo guardd Daten liest/schreibt.

db_path -- SQLite-Datenbank, die Merkmalsvektoren und Anomalien speichert

model_path -- Serialisiertes Modellbündel, das für die Erkennung verwendet wird

guardd_path -- Pfad zur eBPF-Collector-Binärdatei

Hinweise

Konfigurationswerte überschreiben CLI-Standardwerte CLI-Argumente können die Konfiguration dennoch überschreiben, wenn sie explizit angegeben werden Die Modellgenauigkeit hängt stark von guten Trainingsdaten ab. Längere Trainingszeiten führen zu einem genaueren Detektor

Abhängigkeiten

python3 python3-venv python3-pip clang llvm libbpf-dev libelf-dev bpftool build-essential pkg-config sqlite3