Guardd

Detecção de anomalias comportamentais para Linux, com tecnologia eBPF e aprendizado de máquina.

O Guardd aprende como um host Linux se comporta normalmente e sinaliza atividades que diferem dessa linha de base. Sensores do kernel coletam execuções de processos e tentativas de conexão TCP de saída; uma Isolation Forest pontua as janelas de atividade resultantes de um minuto. Os alertas incluem a pontuação, o contexto comportamental e explicações para ajudar na investigação.

Um daemon em segundo plano cuida da coleta, do treinamento e da detecção. A interface gráfica de desktop e a interface de terminal permitem inspecionar alertas e uso de recursos enquanto o daemon continua em execução.

Status: experimental e em desenvolvimento ativo. A qualidade da detecção depende da carga de trabalho, da linha de base e das configurações de sensibilidade.

Instalação · Uso · Configuração · Como funciona · Atualização · Solução de problemas

Recursos

• Telemetria do kernel: nomes de processos, caminhos de executáveis, usuários, IDs de processos pais e destinos e portas TCP IPv4 de saída.
• Detecção comportamental: contagens de atividade, diversidade e novidade pontuadas em relação a uma linha de base de referência fixa.
• Ciclo de vida automático: coleta inicial, treinamento do modelo, detecção, retreinamento semanal e recarregamento do modelo em um único serviço systemd.
• Alertas persistentes: armazenamento SQLite com pontuações, severidade, explicações, resumos de recursos e contexto; os alertas também são emitidos como JSON delimitado por novas linhas.
• Interface gráfica de desktop: páginas de Visão Geral e Alertas, busca, filtros de severidade e tempo, inspeção detalhada de alertas e atualização automática.
• Visibilidade do sistema: estado do serviço, uso de CPU e memória, PID, tempo de atividade, informações do host e do kernel, tamanho da janela de agregação e atualidade da telemetria.
• Integração com o desktop: um lançador no menu de aplicativos do Guardd e ícone de pinguim.
• Acesso pelo terminal: uma TUI em curses e comandos para coletar, treinar, pontuar e inspecionar telemetria diretamente.

Capturas de tela

Visão geral do desktop

Investigação de alertas

As capturas de tela do desktop usam alertas de exemplo e um estado de serviço simulado.

Interface de terminal

Instalação

Requisitos

O instalador fornecido usa apt-get e systemd. O Ubuntu 24.04 LTS é um ponto de partida prático; sistemas Debian precisam de pacotes equivalentes. Outras distribuições exigem instalação manual das dependências.

• Python 3.11 ou mais recente disponível como python3. O Python 3.10 padrão do Ubuntu 22.04 não atende ao requisito do pacote.
• Um kernel Linux com eBPF, BTF em /sys/kernel/btf/vmlinux e os tracepoints de processo e socket necessários.
• Clang/LLVM, cabeçalhos de desenvolvimento libbpf, libelf, uma cadeia de ferramentas de compilação C e bpftool para gerar cabeçalhos do kernel e esqueletos BPF.
• Privilégios de root para instalar o serviço e executar os sensores.
• Uma sessão de desktop gráfica para a interface PySide6 opcional.

No Ubuntu, instale o Git e as ferramentas do kernel antes de executar o instalador:```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"

O pacote kernel-tools deve corresponder ao seu kernel em execução. No Debian, o `bpftool` está
disponível como um pacote separado. O instalador fornece as outras dependências de compilação e
do Python, mas não instala explicitamente o `bpftool`.

### Instalar o daemon e a interface gráfica de desktop```bash
git clone https://github.com/benny-e/guardd.git
cd guardd
sudo bash install.sh --gui

Para uma instalação headless, execute sudo bash install.sh em vez disso.

O instalador copia a aplicação para /opt/guardd, cria o seu ambiente virtual, compila o coletor eBPF, instala /usr/local/bin/guardd e ativa guardd.service no arranque. Não inicia o serviço. Com --gui, também instala as dependências de runtime do Qt, o lançador de ambiente de trabalho e o ícone.

Definir os caminhos instalados

Antes do primeiro arranque, abra a configuração instalada:```bash sudoedit /opt/guardd/config.toml

Defina sua seção `[paths]` para caminhos absolutos:```toml
[paths]
sensor_path = "/opt/guardd/ebpf/guardd"
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"

A configuração do repositório usa caminhos relativos. Eles funcionam a partir do diretório de trabalho /opt/guardd do serviço, mas um lançador de desktop pode iniciar em outro local. Caminhos absolutos permitem que o daemon, a GUI e a CLI usem os mesmos dados.

Revise as configurações de treinamento em Configuration e, em seguida, inicie:```bash sudo systemctl start guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -f

A primeira execução recolhe dados antes de um modelo estar disponível. Um serviço ativo pode ainda estar nesta fase de recolha; verifique os seus logs para treino e deteção.

## Utilização

### Interface Gráfica de Ambiente de Trabalho

Abra o **Guardd** a partir do menu de aplicações, ou execute:```bash
guardd gui

Execute a GUI como seu usuário comum de desktop. Ela lê o banco de dados existente e atualiza a cada cinco segundos. Fechá-la deixa o daemon em execução.

Página	O que você pode fazer
Visão geral	Verifique o serviço, alertas de hoje, disponibilidade do arquivo de modelo, uso de CPU/memória, PID, tempo de atividade, detalhes do host/kernel, tamanho da janela de 60 segundos e telemetria recente. Selecione um alerta recente para inspecioná-lo.
Alertas	Pesquise nomes de processos, caminhos, destinos e motivos; filtre por severidade e pelas últimas 24 horas, 7 dias, 30 dias ou todo o período; selecione um alerta para ver sua pontuação, limiar, explicações, atividade e contexto.

Use Refresh para uma atualização imediata. Os horários usam seu fuso horário local, e os totais diários da Visão geral cobrem o dia do calendário local independentemente dos filtros.