Guardd

Detección de anomalías de comportamiento para Linux, impulsada por eBPF y aprendizaje automático.

Guardd aprende cómo se comporta normalmente un host Linux y marca la actividad que difiere de esa línea base. Los sensores del kernel recopilan ejecuciones de procesos e intentos de conexión TCP saliente; un Isolation Forest puntúa las ventanas de actividad resultantes de un minuto. Las alertas incluyen la puntuación, el contexto de comportamiento y explicaciones para ayudarte a investigar.

Un demonio en segundo plano se encarga de la recopilación, el entrenamiento y la detección. La GUI de escritorio y la interfaz de terminal te permiten inspeccionar las alertas y el uso de recursos mientras el demonio sigue ejecutándose.

Estado: experimental y en desarrollo activo. La calidad de la detección depende de la carga de trabajo, la línea base y la configuración de sensibilidad.

Instalación · Uso · Configuración · Cómo funciona · Actualización · Solución de problemas

Características

• Telemetría del kernel: nombres de procesos, rutas de ejecutables, usuarios, IDs de procesos padre y destinos y puertos TCP IPv4 salientes.
• Detección de comportamiento: recuentos de actividad, diversidad y novedad puntuados contra una línea base de referencia fija.
• Ciclo de vida automático: recopilación inicial, entrenamiento del modelo, detección, reentrenamiento semanal y recargas del modelo en un único servicio systemd.
• Alertas persistentes: almacenamiento SQLite con puntuaciones, severidad, explicaciones, resúmenes de características y contexto; las alertas también se emiten como JSON delimitado por saltos de línea.
• GUI de escritorio: páginas de Resumen y Alertas, búsqueda, filtros de severidad y tiempo, inspección detallada de alertas y actualización automática.
• Visibilidad del sistema: estado del servicio, uso de CPU y memoria, PID, tiempo de actividad, información del host y del kernel, tamaño de la ventana de agregación y frescura de la telemetría.
• Integración con el escritorio: un lanzador del menú de aplicaciones de Guardd y un icono de pingüino.
• Acceso por terminal: una TUI de curses y comandos para recopilar, entrenar, puntuar e inspeccionar la telemetría directamente.

Capturas de pantalla

Resumen de escritorio

Investigación de alertas

Las capturas de pantalla del escritorio utilizan alertas de ejemplo y un estado de servicio simulado.

Interfaz de terminal

Instalación

Requisitos

El instalador proporcionado utiliza apt-get y systemd. Ubuntu 24.04 LTS es un punto de partida práctico; los sistemas Debian necesitan paquetes equivalentes. Otras distribuciones requieren la instalación manual de dependencias.

• Python 3.11 o superior disponible como python3. El Python 3.10 predeterminado de Ubuntu 22.04 no cumple el requisito del paquete.
• Un kernel Linux con eBPF, BTF en /sys/kernel/btf/vmlinux y los tracepoints de proceso y socket necesarios.
• Clang/LLVM, cabeceras de desarrollo de libbpf, libelf, una cadena de herramientas de compilación de C y bpftool para generar cabeceras del kernel y esqueletos BPF.
• Privilegios de root para instalar el servicio y ejecutar los sensores.
• Una sesión de escritorio gráfica para la GUI opcional de PySide6.

En Ubuntu, instala Git y las herramientas del kernel antes de ejecutar el 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"

El paquete kernel-tools debe coincidir con tu kernel en ejecución. En Debian, `bpftool` está
disponible como un paquete separado. El instalador proporciona las demás dependencias de compilación y
de Python, pero no instala explícitamente `bpftool`.

### Instalar el daemon y la GUI de escritorio```bash
git clone https://github.com/benny-e/guardd.git
cd guardd
sudo bash install.sh --gui

Para una instalación sin interfaz gráfica, ejecute sudo bash install.sh en su lugar.

El instalador copia la aplicación a /opt/guardd, crea su entorno virtual, compila el colector eBPF, instala /usr/local/bin/guardd y habilita guardd.service al arrancar. No inicia el servicio. Con --gui, también instala las dependencias de tiempo de ejecución de Qt, el lanzador de escritorio y el icono.

Establecer las rutas instaladas

Antes del primer inicio, abra la configuración instalada:```bash sudoedit /opt/guardd/config.toml

Establece su sección `[paths]` con rutas absolutas:```toml
[paths]
sensor_path = "/opt/guardd/ebpf/guardd"
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"

La configuración del repositorio utiliza rutas relativas. Estas funcionan desde el directorio de trabajo /opt/guardd del servicio, pero un lanzador de escritorio puede iniciarse en otro lugar. Las rutas absolutas permiten que el daemon, la GUI y la CLI utilicen los mismos datos.

Revise la configuración de entrenamiento en Configuration y, a continuación, inicie:```bash sudo systemctl start guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -f

La primera ejecución recopila datos antes de que haya un modelo disponible. Un servicio activo aún puede estar en esta fase de recopilación; revisa sus registros para el entrenamiento y la detección.

## Uso

### Interfaz gráfica de escritorio

Abre **Guardd** desde el menú de aplicaciones, o ejecuta:```bash
guardd gui

Ejecuta la GUI como tu usuario habitual de escritorio. Lee la base de datos existente y se actualiza cada cinco segundos. Cerrarla deja el daemon en ejecución.

Página	Qué puedes hacer
Overview	Consultar el servicio, las alertas de hoy, la disponibilidad del archivo de modelo, el uso de CPU/memoria, el PID, el tiempo de actividad, los detalles del host/kernel, el tamaño de la ventana de 60 segundos y la telemetría reciente. Selecciona una alerta reciente para inspeccionarla.
Alerts	Buscar nombres de procesos, rutas, destinos y motivos; filtrar por severidad y por las últimas 24 horas, 7 días, 30 días o todo el tiempo; seleccionar una alerta para ver su puntuación, umbral, explicaciones, actividad y contexto.

Usa Refresh para una actualización inmediata. Las horas usan tu zona horaria local, y los totales diarios de Overview cubren el día natural local independientemente de los filtros.