guardd se ejecuta como un único servicio systemd que gestiona el ciclo completo de recolección de datos, entrenamiento y detección.

Al iniciar:

Si no existe un modelo, guardd comienza a recopilar datos de referencia del comportamiento
Recopila 1 día (por defecto) de datos para entrenar inicialmente
Una vez que el entrenamiento tiene éxito, cambia automáticamente al modo de detección

Durante la operación:

La actividad del sistema se agrega continuamente en ventanas de tiempo y se convierte en vectores de características
Cada ventana es evaluada por el modelo Isolation Forest entrenado
Las anomalías se emiten como NDJSON

En curso:

El modelo se reentrena automáticamente una vez por semana
La detección se reanuda inmediatamente después del reentrenamiento con el modelo actualizado

Instalación

1. Clonar el repositorio

2. Ejecutar el script de instalación

Esto hará lo siguiente:

Instalar las dependencias del sistema
Copiar el proyecto a /opt/guardd
Crear un entorno virtual de Python
Instalar el paquete
Compilar los componentes eBPF
Instalar el servicio systemd

Uso

Iniciar el servicio

Verificar el estado

Ver los registros

TUI de terminal

guardd incluye una interfaz de terminal para navegar por las alertas recientes y buscar anomalías

Para iniciar: (después de iniciar guardd.service)

Ejecutar sin systemd

Puedes ejecutar guardd directamente desde la línea de comandos sin instalar el servicio systemd. Esto se puede configurar para funcionar con otros sistemas de inicio

Ejecutar el demonio completo

Ejecutar componentes individuales

Recolectar datos:

Entrenar modelo:

Ejecutar detección:

Configuración

guardd admite configuración a través de un archivo config.toml.

Por defecto, el demonio busca en:

Ejemplo

[daemon]

Controla el ciclo de vida de guardd.

mode
-- "auto" → pipeline completo (collect → train → detect)
-- "collect" → solo recopilar datos
-- "detect" → solo ejecutar detección (requiere modelo)

bootstrap_retry_seconds
-- Con qué frecuencia guardd intenta el entrenamiento inicial cuando no existe un modelo
-- Durante esta fase, guardd recopila datos y periódicamente se detiene para intentar entrenar

retrain_interval_seconds
-- Con qué frecuencia se reentrena el modelo después del bootstrap inicial
-- Por defecto: 7 días

[train]

Controla el comportamiento y los requisitos del modelo.

min_training_rows
-- Número mínimo de ventanas de características necesarias para entrenar
-- Si no se cumple, el entrenamiento falla y se reintentará más tarde

contamination
-- Proporción esperada de anomalías en los datos
-- Se pasa directamente a Isolation Forest
-- Valores típicos: 0.01–0.05

n_estimators
-- Número de árboles en el Isolation Forest
-- Mayor = más preciso, entrenamiento más lento

threshold_percentile
-- Determina el puntaje de corte de anomalías
-- Menor = detección más agresiva

[paths]

Controla dónde guardd lee/escribe datos.

db_path
-- Base de datos SQLite que almacena vectores de características y anomalías

model_path
-- Paquete de modelo serializado utilizado para la detección

guardd_path
-- Ruta al binario recolector eBPF

Notas

Los valores de configuración anulan los valores predeterminados de CLI
Los argumentos CLI aún pueden anular la configuración si se proporcionan explícitamente
La precisión del modelo depende en gran medida de buenos datos de entrenamiento. Tiempos de entrenamiento más largos resultarán en un detector más preciso

Dependencias

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