Guardd

Rilevamento comportamentale delle anomalie per Linux, basato su eBPF e machine learning.

Guardd apprende come si comporta normalmente un host Linux e segnala le attività che si discostano da quella baseline. I sensori del kernel raccolgono le esecuzioni dei processi e i tentativi di connessione TCP in uscita; un Isolation Forest assegna un punteggio alle finestre di attività risultanti di un minuto. Gli avvisi includono il punteggio, il contesto comportamentale e le spiegazioni per aiutarti nelle indagini.

Un daemon in background gestisce la raccolta, l'addestramento e il rilevamento. L'interfaccia grafica desktop e l'interfaccia da terminale ti permettono di esaminare gli avvisi e l'utilizzo delle risorse mentre il daemon continua a funzionare.

Stato: sperimentale e in fase di sviluppo attivo. La qualità del rilevamento dipende dal carico di lavoro, dalla baseline e dalle impostazioni di sensibilità.

Installazione · Utilizzo · Configurazione · Come funziona · Aggiornamento · Risoluzione dei problemi

Funzionalità

• Telemetria del kernel: nomi dei processi, percorsi degli eseguibili, utenti, ID dei processi padre e destinazioni e porte TCP IPv4 in uscita.
• Rilevamento comportamentale: conteggi delle attività, diversità e novità valutati rispetto a una baseline di riferimento fissa.
• Ciclo di vita automatico: raccolta iniziale, addestramento del modello, rilevamento, riaddestramento settimanale e ricaricamento del modello in un unico servizio systemd.
• Avvisi persistenti: archiviazione SQLite con punteggi, gravità, spiegazioni, riepiloghi delle caratteristiche e contesto; gli avvisi vengono anche emessi come JSON delimitato da newline.
• GUI desktop: pagine Panoramica e Avvisi, ricerca, filtri per gravità e tempo, ispezione dettagliata degli avvisi e aggiornamento automatico.
• Visibilità del sistema: stato del servizio, utilizzo di CPU e memoria, PID, uptime, informazioni su host e kernel, dimensione della finestra di aggregazione e freschezza della telemetria.
• Integrazione desktop: un launcher nel menu applicazioni di Guardd e l'icona del pinguino.
• Accesso da terminale: una TUI curses e comandi per raccogliere, addestrare, assegnare punteggi e ispezionare la telemetria direttamente.

Screenshot

Panoramica desktop

Indagine sugli avvisi

Gli screenshot del desktop utilizzano avvisi di esempio e uno stato del servizio simulato.

Interfaccia da terminale

Installazione

Requisiti

L'installer fornito utilizza apt-get e systemd. Ubuntu 24.04 LTS è un punto di partenza pratico; i sistemi Debian necessitano di pacchetti equivalenti. Altre distribuzioni richiedono l'installazione manuale delle dipendenze.

• Python 3.11 o successivo disponibile come python3. Il Python 3.10 predefinito di Ubuntu 22.04 non soddisfa il requisito del pacchetto.
• Un kernel Linux con eBPF, BTF in /sys/kernel/btf/vmlinux e i tracepoint richiesti per processi e socket.
• Clang/LLVM, header di sviluppo libbpf, libelf, una toolchain di compilazione C e bpftool per generare header del kernel e skeleton BPF.
• Privilegi di root per installare il servizio ed eseguire i sensori.
• Una sessione desktop grafica per la GUI PySide6 opzionale.

Su Ubuntu, installa Git e gli strumenti del kernel prima di eseguire l'installer:```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"

Il pacchetto kernel-tools deve corrispondere al kernel in esecuzione. Su Debian, `bpftool` è
disponibile come pacchetto separato. L'installer fornisce le altre dipendenze di build e
Python, ma non installa esplicitamente `bpftool`.

### Installare il daemon e la GUI desktop```bash
git clone https://github.com/benny-e/guardd.git
cd guardd
sudo bash install.sh --gui

Per un'installazione headless, esegui invece sudo bash install.sh.

L'installer copia l'applicazione in /opt/guardd, crea il suo ambiente virtuale, compila il collector eBPF, installa /usr/local/bin/guardd e abilita guardd.service all'avvio. Non avvia il servizio. Con --gui, installa anche le dipendenze runtime di Qt, il launcher desktop e l'icona.

Impostare i percorsi installati

Prima del primo avvio, apri la configurazione installata:```bash sudoedit /opt/guardd/config.toml

Imposta la sua sezione `[paths]` su percorsi assoluti:```toml
[paths]
sensor_path = "/opt/guardd/ebpf/guardd"
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"

La configurazione del repository utilizza percorsi relativi. Questi funzionano dalla directory di lavoro del servizio /opt/guardd, ma un launcher desktop può avviarsi altrove. I percorsi assoluti consentono al daemon, alla GUI e alla CLI di utilizzare gli stessi dati.

Esamina le impostazioni di addestramento in Configuration, quindi avvia:```bash sudo systemctl start guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -f

La prima esecuzione raccoglie dati prima che sia disponibile un modello. Un servizio attivo può
trovarsi ancora in questa fase di raccolta; controlla i suoi log per l'addestramento e il rilevamento.

## Utilizzo

### GUI Desktop

Apri **Guardd** dal menu delle applicazioni, oppure esegui:```bash
guardd gui

Esegui la GUI come utente desktop normale. Legge il database esistente e si aggiorna ogni cinque secondi. Chiudendola, il daemon continua a funzionare.

Pagina	Cosa puoi fare
Panoramica	Controlla il servizio, gli avvisi di oggi, la disponibilità del file del modello, l'utilizzo di CPU/memoria, il PID, l'uptime, i dettagli su host/kernel, la dimensione della finestra di 60 secondi e la telemetria recente. Seleziona un avviso recente per esaminarlo.
Avvisi	Cerca nomi di processi, percorsi, destinazioni e motivazioni; filtra per gravità e per le ultime 24 ore, 7 giorni, 30 giorni o tutto il periodo; seleziona un avviso per visualizzarne punteggio, soglia, spiegazioni, attività e contesto.

Usa Aggiorna per un aggiornamento immediato. Gli orari utilizzano il tuo fuso orario locale, e i totali giornalieri della Panoramica coprono il giorno di calendario locale indipendentemente dai filtri.