Guardd

Détection comportementale des anomalies pour Linux, propulsée par eBPF et l'apprentissage automatique.

Guardd apprend le comportement normal d'un hôte Linux et signale les activités qui s'écartent de cette référence. Les capteurs du noyau collectent les exécutions de processus et les tentatives de connexion TCP sortantes ; un Isolation Forest note les fenêtres d'activité d'une minute qui en résultent. Les alertes incluent le score, le contexte comportemental et des explications pour vous aider à enquêter.

Un démon en arrière-plan gère la collecte, l'entraînement et la détection. L'interface graphique de bureau et l'interface en terminal vous permettent d'inspecter les alertes et l'utilisation des ressources pendant que le démon continue de fonctionner.

Statut : expérimental et en cours de développement actif. La qualité de détection dépend de la charge de travail, de la référence et des paramètres de sensibilité.

Installation · Utilisation · Configuration · Fonctionnement · Mise à jour · Dépannage

Fonctionnalités

• Télémétrie du noyau : noms de processus, chemins d'exécutables, utilisateurs, identifiants de processus parents, et destinations et ports TCP IPv4 sortants.
• Détection comportementale : comptages d'activité, diversité et nouveauté notés par rapport à une référence fixe.
• Cycle de vie automatique : collecte initiale, entraînement du modèle, détection, réentraînement hebdomadaire et rechargements du modèle dans un seul service systemd.
• Alertes persistantes : stockage SQLite avec scores, sévérité, explications, résumés de caractéristiques et contexte ; les alertes sont également émises en JSON délimité par des retours à la ligne.
• Interface graphique de bureau : pages Vue d'ensemble et Alertes, recherche, filtres par sévérité et par temps, inspection détaillée des alertes et actualisation automatique.
• Visibilité système : état du service, utilisation du CPU et de la mémoire, PID, temps de fonctionnement, informations sur l'hôte et le noyau, taille de la fenêtre d'agrégation et fraîcheur de la télémétrie.
• Intégration au bureau : un lanceur de menu d'application Guardd et une icône de pingouin.
• Accès en terminal : une TUI curses et des commandes pour collecter, entraîner, noter et inspecter la télémétrie directement.

Captures d'écran

Vue d'ensemble du bureau

Investigation des alertes

Les captures d'écran du bureau utilisent des alertes d'exemple et un état de service simulé.

Interface en terminal

Installation

Prérequis

L'installateur fourni utilise apt-get et systemd. Ubuntu 24.04 LTS est un point de départ pratique ; les systèmes Debian nécessitent des paquets équivalents. Les autres distributions nécessitent une installation manuelle des dépendances.

• Python 3.11 ou plus récent disponible en tant que python3. Le Python 3.10 par défaut d'Ubuntu 22.04 ne satisfait pas aux exigences du paquet.
• Un noyau Linux avec eBPF, BTF à /sys/kernel/btf/vmlinux, et les tracepoints de processus et de socket requis.
• Clang/LLVM, les en-têtes de développement libbpf, libelf, une chaîne d'outils de compilation C, et bpftool pour générer les en-têtes du noyau et les squelettes BPF.
• Des privilèges root pour installer le service et exécuter les capteurs.
• Une session de bureau graphique pour l'interface PySide6 optionnelle.

Sur Ubuntu, installez Git et les outils du noyau avant d'exécuter l'installateur :```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"

Le paquet kernel-tools doit correspondre à votre noyau en cours d'exécution. Sur Debian, `bpftool` est
disponible en tant que paquet séparé. L'installateur fournit les autres dépendances de compilation et
Python, mais n'installe pas explicitement `bpftool`.

### Installer le démon et l'interface graphique de bureau```bash
git clone https://github.com/benny-e/guardd.git
cd guardd
sudo bash install.sh --gui

Pour une installation sans interface graphique, exécutez plutôt sudo bash install.sh.

L'installateur copie l'application dans /opt/guardd, crée son environnement virtuel, compile le collecteur eBPF, installe /usr/local/bin/guardd et active guardd.service au démarrage. Il ne démarre pas le service. Avec --gui, il installe également les dépendances d'exécution Qt, le lanceur de bureau et l'icône.

Définir les chemins installés

Avant le premier démarrage, ouvrez la configuration installée :```bash sudoedit /opt/guardd/config.toml

Définissez sa section `[paths]` sur des chemins absolus :```toml
[paths]
sensor_path = "/opt/guardd/ebpf/guardd"
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"

Le dépôt de configuration utilise des chemins relatifs. Ceux-ci fonctionnent depuis le répertoire de travail /opt/guardd du service, mais un lanceur de bureau peut démarrer ailleurs. Les chemins absolus permettent au démon, à l'interface graphique et à l'interface en ligne de commande d'utiliser les mêmes données.

Consultez les paramètres d'entraînement dans Configuration, puis démarrez :```bash sudo systemctl start guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -f

Le premier lancement collecte des données avant qu'un modèle ne soit disponible. Un service actif peut encore être dans cette phase de collecte ; consultez ses journaux pour l'entraînement et la détection.

## Utilisation

### Interface graphique de bureau

Ouvrez **Guardd** depuis votre menu d'applications, ou exécutez :```bash
guardd gui

Exécutez l'interface graphique en tant qu'utilisateur normal de votre bureau. Elle lit la base de données existante et s'actualise toutes les cinq secondes. La fermer laisse le démon en cours d'exécution.

Page	Ce que vous pouvez faire
Overview	Vérifier le service, les alertes du jour, la disponibilité du fichier de modèle, l'utilisation du CPU/de la mémoire, le PID, la durée de fonctionnement, les détails de l'hôte/du noyau, la taille de la fenêtre de 60 secondes et la télémétrie récente. Sélectionnez une alerte récente pour l'inspecter.
Alerts	Rechercher les noms de processus, les chemins, les destinations et les raisons ; filtrer par sévérité et par les dernières 24 heures, 7 jours, 30 jours ou tout l'historique ; sélectionner une alerte pour afficher son score, son seuil, ses explications, son activité et son contexte.

Utilisez Refresh pour une mise à jour immédiate. Les heures utilisent votre fuseau horaire local, et les totaux quotidiens d'Overview couvrent le jour calendaire local indépendamment des filtres.