guardd

Detecção de anomalias comportamentais baseada em aprendizado de máquina para Linux usando eBPF + Isolation Forest

O Guardd coleta eventos de sistema de baixo nível (execução de processos, atividade de rede), os agrega em vetores de características em janelas de tempo e detecta comportamento anômalo usando um modelo de aprendizado de máquina.

O Guardd é focado em detectar ameaças desconhecidas

[!WARNING] Este projeto ainda está em desenvolvimento
Recursos e precisão de detecção estão sendo ativamente aprimorados
Feedback, sugestões e contribuições são bem-vindos

Como funciona

O guardd executa como um único serviço systemd que gerencia todo o ciclo de vida da coleta de dados, treinamento e detecção.

Na inicialização:

Se nenhum modelo existir, o guardd começa a coletar dados comportamentais de linha de base
Ele coleta 1 dia (padrão) de dados para treinar inicialmente
Quando o treinamento é bem-sucedido, ele alterna automaticamente para o modo de detecção

Durante a operação:

A atividade do sistema é continuamente agregada em janelas de tempo e convertida em vetores de características
Cada janela é avaliada pelo modelo Isolation Forest treinado
Anomalias são emitidas como NDJSON

Continuamente:

O modelo é retreinado automaticamente uma vez por semana
A detecção é retomada imediatamente após o retreinamento com o modelo atualizado

Instalação

1. Clone o repositório

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

2. Execute o script de instalação

sudo bash install.sh

Isso irá:

Instalar dependências do sistema
Copiar o projeto para /opt/guardd
Criar um ambiente virtual Python
Instalar o pacote
Construir componentes eBPF
Instalar o serviço systemd

Uso

Iniciar serviço

sudo systemctl start guardd.service

Verificar status

systemctl status guardd.service

Visualizar logs

journalctl -u guardd.service -f

TUI do Terminal

O guardd inclui uma interface de terminal (TUI) para navegar por alertas recentes e pesquisar anomalias

Para iniciar: (após iniciar guardd.service)

guardd tui

Executar sem systemd

Você pode executar guardd diretamente da linha de comando sem instalar o serviço systemd. Isso pode ser configurado para funcionar com outros sistemas init

Executar daemon completo

sudo guardd daemon

Executar componentes individuais

Coletar dados:

sudo guardd collect

Treinar modelo:

sudo guardd train

Executar detecção:

sudo guardd detect

Configuração

O guardd suporta configuração via um arquivo config.toml.

Por padrão, o daemon procura em:

/opt/guardd/config.toml

Exemplo

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

Controla o ciclo de vida do guardd.

mode
-- "auto" → pipeline completo (coletar → treinar → detectar)
-- "collect" → apenas coletar dados
-- "detect" → apenas executar detecção (requer modelo)

bootstrap_retry_seconds
-- Com que frequência o guardd tenta o treinamento inicial quando nenhum modelo existe
-- Durante esta fase, o guardd coleta dados e pausa periodicamente para tentar treinar

retrain_interval_seconds
-- Com que frequência o modelo é retreinado após o bootstrap inicial
-- Padrão: 7 dias

[train]

Controla o comportamento e os requisitos do modelo.

min_training_rows
-- Número mínimo de janelas de características necessárias para treinar
-- Se não for atingido, o treinamento falha e tentará novamente mais tarde

contamination
-- Proporção esperada de anomalias nos dados
-- Passado diretamente para o Isolation Forest
-- Valores típicos: 0.01–0.05

n_estimators
-- Número de árvores no Isolation Forest
-- Maior = mais preciso, treinamento mais lento

threshold_percentile
-- Determina o ponto de corte da pontuação de anomalia
-- Menor = detecção mais agressiva

[paths]

Controla onde o guardd lê/escreve dados.

db_path
-- Banco de dados SQLite armazenando vetores de características e anomalias

model_path
-- Pacote de modelo serializado usado para detecção

guardd_path
-- Caminho para o binário do coletor eBPF

Notas

Os valores de configuração substituem os padrões da CLI
Os argumentos da CLI ainda podem substituir a configuração se fornecidos explicitamente
A precisão do modelo depende fortemente de bons dados de treinamento. Períodos de treinamento mais longos resultarão em um detector mais preciso

Dependências

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