guardd

Rilevamento anomalie comportamentali basato su machine learning per Linux tramite eBPF + Isolation Forest

Guardd raccoglie eventi di sistema a basso livello (esecuzione di processi, attività di rete), li aggrega in vettori di caratteristiche basati su finestre temporali e rileva comportamenti anomali utilizzando un modello di machine learning.

Guardd è focalizzato sul rilevamento di minacce sconosciute

[!WARNING] Questo progetto è ancora in fase di sviluppo
Le funzionalità e l'accuratezza del rilevamento sono in continuo miglioramento
Feedback, suggerimenti e contributi sono benvenuti

Come funziona

guardd viene eseguito come un singolo servizio systemd che gestisce l'intero ciclo di raccolta dati, addestramento e rilevamento.

All'avvio:

Se non esiste un modello, guardd inizia a raccogliere dati comportamentali di base
Raccoglie 1 giorno (predefinito) di dati per l'addestramento iniziale
Una volta completato l'addestramento, passa automaticamente alla modalità di rilevamento

Durante il funzionamento:

L'attività di sistema viene continuamente aggregata in finestre temporali e convertita in vettori di caratteristiche
Ogni finestra viene valutata dal modello Isolation Forest addestrato
Le anomalie vengono emesse in formato NDJSON

Continuamente:

Il modello viene riaddestrato automaticamente una volta a settimana
Il rilevamento riprende immediatamente dopo il riaddestramento con il modello aggiornato

Installazione

1. Clona il repository

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

2. Esegui lo script di installazione

sudo bash install.sh

Questo provvederà a:

Installare le dipendenze di sistema
Copiare il progetto in /opt/guardd
Creare un ambiente virtuale Python
Installare il pacchetto
Compilare i componenti eBPF
Installare il servizio systemd

Utilizzo

Avvia il servizio

sudo systemctl start guardd.service

Verifica lo stato

systemctl status guardd.service

Visualizza i log

journalctl -u guardd.service -f

TUI terminale

guardd include un'interfaccia utente testuale per esplorare gli avvisi recenti e cercare anomalie

Per avviarla: (dopo aver avviato guardd.service)

guardd tui

Esecuzione senza systemd

Puoi eseguire guardd direttamente dalla riga di comando senza installare il servizio systemd. Questo può essere configurato per funzionare con altri sistemi di init

Esegui il demone completo

sudo guardd daemon

Esegui componenti singoli

Raccogli dati:

sudo guardd collect

Addestra il modello:

sudo guardd train

Esegui il rilevamento:

sudo guardd detect

Configurazione

guardd supporta la configurazione tramite un file config.toml.

Di default, il demone cerca in:

/opt/guardd/config.toml

Esempio

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

Controlla il ciclo di vita di guardd.

mode
-- "auto" → pipeline completa (raccolta → addestramento → rilevamento)
-- "collect" → solo raccolta dati
-- "detect" → solo rilevamento (richiede un modello)

bootstrap_retry_seconds
-- Ogni quanto guardd tenta l'addestramento iniziale quando non esiste un modello
-- Durante questa fase, guardd raccoglie dati e periodicamente si ferma per provare ad addestrare

retrain_interval_seconds
-- Ogni quanto il modello viene riaddestrato dopo il bootstrap iniziale
-- Default: 7 giorni

[train]

Controlla il comportamento e i requisiti del modello.

min_training_rows
-- Numero minimo di finestre di caratteristiche necessarie per l'addestramento
-- Se non viene raggiunto, l'addestramento fallisce e riprova più tardi

contamination
-- Proporzione attesa di anomalie nei dati
-- Passato direttamente a Isolation Forest
-- Valori tipici: 0.01–0.05

n_estimators
-- Numero di alberi nell'Isolation Forest
-- Più alto = più accurato, addestramento più lento

threshold_percentile
-- Determina il punteggio di cutoff per le anomalie
-- Più basso = rilevamento più aggressivo

[paths]

Controlla dove guardd legge/scrive i dati.

db_path
-- Database SQLite che memorizza vettori di caratteristiche e anomalie

model_path
-- Bundle del modello serializzato usato per il rilevamento

guardd_path
-- Percorso del binario di raccolta eBPF

Note

I valori di configurazione sovrascrivono i valori predefiniti della CLI
I parametri CLI possono comunque sovrascrivere la configurazione se forniti esplicitamente
L'accuratezza del modello dipende fortemente da dati di addestramento di buona qualità. Tempi di addestramento più lunghi porteranno a un rilevatore più accurato

Dipendenze

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