guardd

Détection d'anomalies comportementales basée sur l'apprentissage automatique pour Linux utilisant eBPF + Isolation Forest

Guardd collecte des événements système de bas niveau (exécution de processus, activité réseau), les agrège en vecteurs de caractéristiques par fenêtre temporelle et détecte les comportements anormaux à l'aide d'un modèle d'apprentissage automatique.

Guardd se concentre sur la détection des menaces inconnues

[!WARNING] Ce projet est encore en développement
Les fonctionnalités et la précision de détection sont activement améliorées
Les retours, suggestions et contributions sont les bienvenus

Comment ça fonctionne

guardd s'exécute en tant que service systemd unique qui gère l'ensemble du cycle de vie de la collecte des données, de l'apprentissage et de la détection.

Au démarrage :

Si aucun modèle n'existe, guardd commence à collecter des données comportementales de base
Il collecte 1 jour (par défaut) de données pour effectuer l'apprentissage initial
Une fois l'apprentissage réussi, il bascule automatiquement en mode détection

Pendant le fonctionnement :

L'activité système est continuellement agrégée en fenêtres temporelles et convertie en vecteurs de caractéristiques
Chaque fenêtre est notée par le modèle Isolation Forest entraîné
Les anomalies sont émises au format NDJSON

En continu :

Le modèle est réentraîné automatiquement une fois par semaine
La détection reprend immédiatement après le réentraînement avec le modèle mis à jour

Installation

1. Cloner le dépôt

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

2. Exécuter le script d'installation

sudo bash install.sh

Ceci va :

Installer les dépendances système
Copier le projet dans /opt/guardd
Créer un environnement virtuel Python
Installer le paquet
Compiler les composants eBPF
Installer le service systemd

Utilisation

Démarrer le service

sudo systemctl start guardd.service

Vérifier le statut

systemctl status guardd.service

Consulter les logs

journalctl -u guardd.service -f

Interface TUI dans le terminal

guardd inclut une interface terminal pour parcourir les alertes récentes et rechercher des anomalies

Pour lancer : (après avoir démarré guardd.service)

guardd tui

Exécution sans systemd

Vous pouvez exécuter guardd directement depuis la ligne de commande sans installer le service systemd. Cela permet de l'utiliser avec d'autres systèmes d'init

Exécuter le démon complet

sudo guardd daemon

Exécuter des composants individuels

Collecter des données :

sudo guardd collect

Entraîner le modèle :

sudo guardd train

Lancer la détection :

sudo guardd detect

Configuration

guardd prend en charge la configuration via un fichier config.toml.

Par défaut, le démon cherche dans :

/opt/guardd/config.toml

Exemple

[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]

Contrôle le cycle de vie de guardd.

mode
-- "auto" → pipeline complet (collecte → apprentissage → détection)
-- "collect" → collecter uniquement les données
-- "detect" → exécuter uniquement la détection (nécessite un modèle)

bootstrap_retry_seconds
-- Fréquence à laquelle guardd tente l'apprentissage initial lorsqu'aucun modèle n'existe
-- Pendant cette phase, guardd collecte des données et s'arrête périodiquement pour tenter l'apprentissage

retrain_interval_seconds
-- Fréquence de réentraînement du modèle après le démarrage initial
-- Par défaut : 7 jours

[train]

Contrôle le comportement et les exigences du modèle.

min_training_rows
-- Nombre minimum de fenêtres de caractéristiques nécessaires pour l'apprentissage
-- Si non atteint, l'apprentissage échoue et sera réessayé plus tard

contamination
-- Proportion attendue d'anomalies dans les données
-- Transmise directement à Isolation Forest
-- Valeurs typiques : 0.01–0.05

n_estimators
-- Nombre d'arbres dans la forêt d'isolement
-- Plus élevé = plus précis, apprentissage plus lent

threshold_percentile
-- Détermine le seuil de score des anomalies
-- Plus bas = détection plus agressive

[paths]

Contrôle où guardd lit/écrit les données.

db_path
-- Base de données SQLite stockant les vecteurs de caractéristiques et les anomalies

model_path
-- Paquet de modèle sérialisé utilisé pour la détection

guardd_path
-- Chemin vers le binaire collecteur eBPF

Remarques

Les valeurs de configuration remplacent les valeurs par défaut de la CLI
Les arguments CLI peuvent toujours remplacer la configuration s'ils sont fournis explicitement
La précision du modèle dépend fortement de la qualité des données d'apprentissage. Une période d'apprentissage plus longue donnera un détecteur plus précis

Dépendances

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