suricatavel-agent

suricatavel-agent es un agente que lee los archivos eve.json generado por Suricata y publica los eventos a través de Kafka o HTTP de forma fiable.

Características clave

Lectura continua de eve.json.
Batching de tamaño adaptativo de eventos para eficiencia y control de latencia.
Buffer local y reintentos: cuando el transporte no está disponible, los eventos se guardan en storage/app/suricatavel-agent.sqlite y se reenvían con backoff exponencial.
Dead Letter Queue (DLQ) persistente para mensajes que exceden los intentos máximos.
Mensajes periódicos para indicar estado (running, starting, error, shutdown).
Soporte de SASL/SSL (Kafka) con certificados y credenciales configurables.

Requisitos

Acceso a los ficheros eve.json de Suricata.
PHP 8.4 con extensión rdkafka, si usamos Kafka.

Instalación

1. Configurar repositorio

Ejecuta los siguientes comandos para añadir la clave GPG y la fuente del repositorio.

# 1. Instalar prerrequisitos
 apt-get update
 apt-get install -y ca-certificates curl gpg

# 2. Añadir clave GPG
curl -fsSL https://suricatavel.org/suricatavel.gpg | \
 gpg --dearmor -o /usr/share/keyrings/suricatavel.gpg

# 3. Añadir fuente del repositorio
echo "deb [signed-by=/usr/share/keyrings/suricatavel.gpg] https://repository.suricatavel.org/ stable main" | \
 tee /etc/apt/sources.list.d/suricatavel.sources

# 4. Actualizar índice
 apt-get update

Para sistemas basados en RPM (usando dnf o yum), añade la configuración del repositorio.

# 1. Instalar prerrequisitos
 dnf install -y ca-certificates curl

# 2. Añadir archivo de repositorio
 tee /etc/yum.repos.d/suricatavel.repo <<EOF
[suricatavel]
name=Suricatavel Repository
baseurl=https://repository.suricatavel.org/rpm/stable/
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://suricatavel.org/suricatavel.gpg
EOF

# 3. Reconstruir caché
 dnf makecache

Para sistemas basados en FreeBSD, configura el repositorio pkg.

# 1. Configurar firmas (fingerprints)
mkdir -p /usr/local/etc/pkg/fingerprints/suricatavel/trusted
fetch -o /usr/local/etc/pkg/fingerprints/suricatavel/trusted/suricatavel \
  https://repository.suricatavel.org/freebsd/fingerprints/trusted/suricatavel

# 2. Añadir configuración del repositorio
cat <<EOF > /usr/local/etc/pkg/repos/suricatavel.conf
suricatavel: {
  url: "pkg+https://repository.suricatavel.org/freebsd",
  signature_type: "fingerprints",
  fingerprints: "/usr/local/etc/pkg/fingerprints/suricatavel",
  enabled: yes
}
EOF

# 3. Actualizar índice
pkg update

Para Unifi u otros appliances sin PHP/Composer:

Descarga el último binario desde la página de Releases.
Sube al appliance: scp suricatavel-agent root@<ip>:/data/
Hazlo ejecutable: chmod +x /data/suricatavel-agent
Extraer archivo de servicio: Extrae suricatavel-agent.service del release o builder y cópialo a /data/.

2. Instalar el paquete

 apt-get install -y suricatavel-agent

 dnf install -y suricatavel-agent

pkg install suricatavel-agent

Registro del agente y transporte

Si estás usando HTTP, debes registrar el agente para obtener un token de autenticación.

Obtener Token: Obtén tu Token de registro desde el dashboard de Suricatavel.

Ejecutar el comando de registro:

# Ejemplo para instalación estándar
php artisan agent:register --token=TU_TOKEN --url=https://tu-suricatavel.com

# Ejemplo para binario estático (Unifi)
cd /data
./suricatavel-agent php-cli artisan agent:register --token=TU_TOKEN --url=https://tu-suricatavel.com

Verificar: Este comando guardará automáticamente el HTTP_AUTH_TOKEN en tu archivo .env.

Configuración

Variables de entorno típicas (o claves en config/*.php):

SURICATA_EVE_JSON_PATHS: Ruta única o lista separada por comas de rutas al fichero eve.json (por defecto: /var/log/suricata/eve.json).
AGENT_TRANSPORT_DRIVER: http (por defecto) o kafka.
AGENT_CONTROLLER_URL: URL base del controlador de Suricatavel (por defecto: https://suricatavel.example.com/).
HTTP_AUTH_TOKEN: Token de autenticación para transporte HTTP.
KAFKA_BROKERS: Lista de brokers, ej. kafka1:9092,kafka2:9092 (si se usa Kafka).
KAFKA_TOPIC: Nombre del tópico de eventos (por defecto: suricatavel-events).
KAFKA_HEARTBEAT_TOPIC: Nombre del tópico de heartbeats (por defecto: suricatavel-heartbeats).
Seguridad (si se usa Kafka): KAFKA_SSL_ENABLED, KAFKA_SSL_CA_LOCATION, KAFKA_SSL_CERTIFICATE_LOCATION, KAFKA_SSL_KEY_LOCATION, KAFKA_SASL_ENABLED, KAFKA_SASL_MECHANISM, KAFKA_SASL_USERNAME, KAFKA_SASL_PASSWORD, etc.
Buffer y reintentos: AGENT_BUFFER_MAX_RETRY_ATTEMPTS, AGENT_BUFFER_RETRY_WAIT_TIME (en segundos).
Heartbeats: AGENT_HEARTBEAT_ENABLED, AGENT_HEARTBEAT_INTERVAL (en segundos).

Uso

El paquete instala automáticamente una configuración de Supervisor. Para iniciar el agente y habilitarlo en el arranque:

 systemctl enable supervisor
 systemctl start supervisor
 supervisorctl start suricatavel-agent

Habilita e inicia el servicio usando sysrc y service:

sysrc suricatavel_agent_enable=YES
service suricatavel_agent start

En Unifi UDM (UbiOS), usa el archivo de servicio systemd proporcionado para persistencia en /data.

# 1. Enlazar el archivo de servicio (desde /data)
ln -s /data/suricatavel-agent.service /etc/systemd/system/suricatavel-agent.service

# 2. Habilitar e Iniciar
systemctl daemon-reload
systemctl enable suricatavel-agent
systemctl start suricatavel-agent

Ejecución manual (para depuración):

php artisan agent:start

Integración con Suricatavel

Suricatavel puede consumir los eventos enviados por el agente desde Kafka (kafka.topics.events) o vía HTTP. Verifica en Suricatavel que la configuración coincida con el transporte del agente.

Solución de problemas

Ajusta el tamaño de lote y los intervalos de reintento si observas latencias altas o picos.

Kafka

Verifica los logs en storage/logs/. Puedes ajustar el nivel de debug de Kafka en el fichero de configuración config/kafka.php.
Si Kafka no está disponible, los eventos quedarán en el buffer SQLite; tras recuperar conectividad se reintentarán automáticamente.