Maltrail

Maltrail es un sistema de detección de tráfico de red que identifica comunicaciones con infraestructura maliciosa conocida y reporta anomalías de tráfico seleccionadas. Compara dominios, URLs, direcciones IP, pares IP:puerto y valores de User-Agent observados en la red contra un conjunto de indicadores llamados trails.

Una detección se registra como un único evento que contiene el origen, el destino, el protocolo, el trail coincidente, la clasificación y la fuente del trail:```text "2026-08-07 09:14:22.117034" gw 10.13.13.2 57809 1.1.1.1 53 UDP DNS malware.bakewithdavid.com "asyncrat (malware)" (static)

Maltrail está diseñado para la monitorización de red basada en indicadores. Sus detecciones heurísticas complementan
la coincidencia de trails, pero no sustituye a la telemetría de endpoints ni a un sistema de prevención de intrusiones
de propósito general.

## Características

- Una construcción completa de trails que combina más de 3.000 archivos estáticos incluidos, 42 integraciones de fuentes públicas
  y trails opcionales proporcionados por el operador.
- Un sensor Rust multihilo que utiliza libpcap, con workers de captura opcionales de `PACKET_FANOUT` de Linux.
- Un servidor Python que proporciona la interfaz de informes, la ingesta de eventos y la API HTTP.
- Trails personalizados y listas blancas en texto plano que pueden revisarse y controlarse mediante versiones.
- Heurísticas para escaneo, agotamiento de DNS, búsquedas similares a DGA, descargas sospechosas, sondas de proxy,
  valores de User-Agent sospechosos y actividad de red relacionada.
- Registro de eventos local, registro remoto de Maltrail, CEF a través de syslog y salida JSON de Logstash.
- Validación del despliegue con `maltrail-sensor -T` y métricas opcionales de Prometheus.

## Contenido

- [Arquitectura](#arquitectura)
- [Rendimiento](#rendimiento)
- [Instalación](#instalación)
  - [Instalador](#instalador)
  - [Compilación desde el código fuente](#compilación-desde-el-código-fuente)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Configuración](#configuración)
- [Trails](#trails)
- [Eventos y API](#eventos-y-api)
- [Operaciones](#operaciones)
  - [Monitorización](#monitorización)
  - [Retención de eventos](#retención-de-eventos)
- [Documentación](#documentación)
- [Contribución](#contribución)
- [Proyecto](#proyecto)
  - [Licencia](#licencia)
  - [Mantenedores](#mantenedores)
  - [Patrocinadores](#patrocinadores)
  - [Presentaciones y publicaciones](#presentaciones-y-publicaciones)
  - [Lista negra derivada](#lista-negra-derivada)
  - [Integraciones de terceros](#integraciones-de-terceros)
  - [Agradecimientos](#agradecimientos)

## Arquitectura

Maltrail consta de dos procesos independientes que pueden ejecutarse en el mismo host o en hosts separados:```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

El sensor captura el tráfico, realiza coincidencia de rastros y análisis heurístico, y genera eventos. Puede escribir eventos localmente (LOG_DIR), enviarlos a un servidor Maltrail remoto (LOG_SERVER), o ambos. También puede emitir CEF a través de syslog (SYSLOG_SERVER) y JSON a Logstash (LOGSTASH_SERVER).

El servidor recibe y almacena eventos remotos, sirve registros de eventos disponibles localmente y proporciona la interfaz web y la API.

Rendimiento

El rendimiento depende del procesador, la composición del tráfico, el tamaño del conjunto de rastros, el controlador de captura y la interfaz de red. Las cifras a continuación miden la ruta de procesamiento de paquetes del sensor de forma aislada; no son mediciones de captura en vivo de extremo a extremo.

Mediciones representativas en un AMD Ryzen 7 PRO 4750U con heurísticas habilitadas y un conjunto de rastros de 1,5 millones de filas:

Las ejecuciones de comparación fuera de línea que utilizan la misma captura generada, configuración y conjunto de rastros midieron un costo por paquete en estado estable 14–37× menor que el sensor Python retirado en los sistemas probados. La herramienta de comparación informa el tiempo de todo el proceso por separado porque la carga de rastros domina las repeticiones cortas. También imprime recuentos de eventos; la paridad funcional se prueba de forma independiente mediante el corpus de paridad.

Ejecute la comparación en el sistema de destino con:```bash python3 sensor/tools/bench_compare.py --packets 300000
--trails ~/.maltrail/trails.csv --repeat 3

Se utiliza un worker de captura por defecto. Los workers adicionales pueden aumentar la capacidad de captura, pero el
hash de flujo de Linux divide el estado por fuente entre los workers y, por tanto, reduce la sensibilidad de algunas
heurísticas de escaneo. En la prueba documentada, el 91% de las alertas heurísticas de un solo worker se mantuvieron con dos
workers, el 86% con cuatro y el 65% con ocho. La coincidencia exacta de rastros no cambió. Aumenta
`CAPTURE_FANOUT` solo cuando las métricas de pérdida de captura muestren que es necesario.

La metodología de referencia, los resultados de hardware, la salida del perfilador, las mediciones de memoria y las comprobaciones
de fanout en vivo están documentados en [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md).

## Instalación

### Instalador

El instalador es compatible con Debian, Ubuntu, Raspberry Pi OS, RHEL, Fedora y openSUSE:```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

Instala las dependencias, crea un checkout gestionado en /opt/maltrail, verifica la suma de verificación del sensor precompilado, crea una cuenta maltrail sin privilegios, instala unidades systemd, prepara los directorios de registro y estado, e inicia el sensor y el servidor. Volver a ejecutar el instalador actualiza el checkout gestionado.

Revisa el script antes de ejecutarlo con privilegios elevados. Desde un checkout existente, la ejecución en seco muestra los comandos sin modificar el sistema:```bash sh install.sh --dry-run

Opciones comunes del instalador:```bash
sh install.sh --role sensor      # Install only the sensor
sh install.sh --ref 3.1.1        # Install a release tag instead of master
sh install.sh --no-service       # Install without changing systemd
sh install.sh --dry-run          # Print commands without applying them
sh install.sh --uninstall        # Remove the managed installation; keep logs and state

El panel está disponible en http://127.0.0.1:8338 después de la instalación. Ten en cuenta que el HTTP_ADDRESS incluido es 0.0.0.0, por lo que es accesible desde todas las interfaces, no solo desde loopback — y las credenciales predeterminadas son admin / changeme!. Cambia USERS y establece HTTP_ADDRESS en 127.0.0.1 (o coloca el servidor detrás de un proxy inverso con TLS) antes de que el host esté en una red no confiable.

La construcción inicial del trail puede tardar varios minutos. El sensor no detecta coincidencias de trail hasta que haya un conjunto de trails válido disponible. La unidad systemd ejecuta la validación -T del sensor antes del inicio para que los privilegios faltantes, un directorio de registro no escribible o un conjunto de trails inválido provoquen que el inicio falle de forma visible.

El entorno de pruebas del instalador cubre contenedores Ubuntu, Debian, Fedora, openSUSE y Alpine. Alpine usa musl y no utiliza el binario del sensor glibc precompilado; compila el sensor desde el código fuente allí.

Compilación desde el código fuente

El sensor requiere Rust 1.74 o superior, los encabezados de desarrollo de libpcap y las herramientas de capacidades del sistema. El servidor y el actualizador de trails requieren Python 3.6 o superior.

Instala los paquetes de la distribución:```bash

Debian / Ubuntu / Raspberry Pi OS

sudo apt-get install cargo libpcap-dev libcap2-bin python3

RHEL / Fedora

sudo dnf install cargo libpcap-devel libcap python3

openSUSE / SLES

sudo zypper install cargo rust libpcap-devel libcap-progs python311

Entonces compila y valida el sensor:```bash
git clone --depth 1 https://github.com/stamparm/maltrail.git
cd maltrail

cargo build --release --manifest-path sensor/Cargo.toml

sudo setcap cap_net_raw,cap_net_admin=eip \
  sensor/target/release/maltrail-sensor

sudo install -d -o "$USER" -g "$(id -gn)" -m 750 /var/log/maltrail

sensor/target/release/maltrail-sensor -T
sensor/target/release/maltrail-sensor

Inicia el servidor en otra terminal o en otro host:```bash python3 server.py

Los binarios de sensor `x86_64` y `aarch64` precompilados se adjuntan a las versiones actuales con sumas de verificación SHA-256.
Están dirigidos a glibc 2.28 y requieren libpcap en tiempo de ejecución. En sistemas basados en musl, como
Alpine Linux, compílelos desde el código fuente.

El sensor Python retirado se utiliza únicamente en las herramientas de comparación y paridad. Esas herramientas además
requieren `pcapy-ng` y los encabezados de desarrollo de Python descritos en
[`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md).

### Systemd

Las unidades `maltrail-server.service` y `maltrail-sensor.service` suministradas ejecutan ambos procesos como el
usuario no privilegiado `maltrail`. Systemd crea `/var/log/maltrail` y `/var/lib/maltrail`, restringe
el acceso al sistema de archivos y otorga al sensor `CAP_NET_RAW` y `CAP_NET_ADMIN`.

El instalador configura estas unidades automáticamente. Para una instalación existente desde el código fuente, siga
el procedimiento de servicio manual en [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md).

Compruebe el estado del servicio y los registros con:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

Docker

Inicia el despliegue de Compose proporcionado con:```bash docker compose -f docker/docker-compose.yml up -d

La configuración del contenedor, el almacenamiento, los privilegios y las comprobaciones de salud están documentados en
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/master/docker/README.md).

## Configuración

Maltrail lee `maltrail.conf`, que contiene ajustes separados de `[Sensor]` y `[Server]`. El
instalador coloca la configuración gestionada en `/etc/maltrail.conf`.

Las opciones de sensor de uso frecuente incluyen:

| Opción | Propósito |
| --- | --- |
| `MONITOR_INTERFACE` | Interfaz o interfaces de captura; `any` selecciona todas las interfaces compatibles |
| `CAPTURE_FILTER` | Filtro de captura BPF |
| `CAPTURE_FANOUT` | Número de sockets de captura de Linux; el valor predeterminado es uno |
| `LOG_DIR` | Directorio local de registros de eventos |
| `TRAILS_FILE` | Base de datos de rastros generada |
| `LOG_SERVER` | Servidor de eventos Maltrail remoto |
| `SYSLOG_SERVER` | Destino o destinos CEF syslog |
| `LOGSTASH_SERVER` | Destino o destinos JSON de Logstash |
| `STATS_ADDRESS` | Listener de métricas Prometheus; deshabilitado a menos que se configure |
| `UPDATE_PERIOD` | Intervalo de actualización de rastros |
| `USER_WHITELIST` | Indicadores gestionados por el operador que no deben alertar |
| `CUSTOM_TRAILS_DIR` | Directorio de rastros gestionado por el operador |

`PROCESS_COUNT` se aplica al sensor Python retirado. Configure los workers de captura del sensor Rust
con `CAPTURE_FANOUT` en su lugar.

Ejecute la comprobación de despliegue después de cambiar la configuración:```bash
sensor/target/release/maltrail-sensor -T

La verificación valida la configuración, los trails, las entradas de la lista blanca, el filtro de captura, los privilegios, el almacenamiento de registros, el soporte de actualización y la configuración de los workers. Una verificación exitosa incluye recuentos positivos de trails y de la lista blanca, en lugar de solo confirmar que los archivos existen.

Trails

Los trails se almacenan como indicadores de texto plano:```text trails/static/malware/ malware-related static trails trails/static/malicious/ malicious infrastructure trails/static/suspicious/ suspicious infrastructure and behavior trails/feeds/*.py public feed integrations

Añade indicadores locales bajo `CUSTOM_TRAILS_DIR`. Añade indicadores que nunca deberían generar alertas
a `USER_WHITELIST`. Mantener los datos personalizados fuera del checkout gestionado evita que las actualizaciones
los sobrescriban.

El actualizador reconstruye `TRAILS_FILE` a partir de las fuentes habilitadas, las trails estáticas incluidas y las trails personalizadas. Un
nuevo archivo se publica atómicamente solo después de una compilación exitosa. Las fuentes vacías o fallidas se notifican
para que una implementación en ejecución no dependa silenciosamente de fuentes obsoletas o retiradas.

Las contribuciones de trails deben incluir el indicador, la clasificación y una fuente verificable. Consulta
[Contributing](#contributing) antes de enviar una solicitud de extracción.

## Events and API

Maltrail registra un evento separado por espacios en blanco por detección, usando comillas CSV cuando un valor
contiene espacios:```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

El campo type identifica qué coincidió, incluyendo DNS, IP, IPORT, URL, PATH, HTTP, UA, PORT y CERT. El campo info contiene la clasificación del rastro, y reference identifica la lista estática, el feed, la fuente personalizada o la heurística que lo produjo.

Búsqueda de indicadores

Usa /check para consultar un dominio, dirección IP o URL:```bash curl 'http://127.0.0.1:8338/check?q=www.sub.evil.example'

I need the actual content of chunk 31 to translate it. Please provide the Markdown text you'd like me to translate from English to Spanish.```json
{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)"
}

Una búsqueda de subdominios puede coincidir con su dominio principal listado. Las búsquedas de URL comprueban host/path antes de comprobar el host por sí solo. El servidor lee la base de datos de trails mapeada en memoria y observa las actualizaciones de trails sin necesidad de reiniciar.

Los trails públicos estáticos y de alimentación están disponibles sin autenticación, de acuerdo con el endpoint /trails utilizado por los sensores remotos. Los trails personalizados requieren una sesión autorizada; una búsqueda no autorizada solo de trails personalizados se reporta como un fallo. Los datos de eventos permanecen autenticados.

Operaciones

Monitoreo

Use maltrail-sensor -T como una compuerta de implementación y configuración. La unidad systemd suministrada lo ejecuta como ExecStartPre.

Cuando STATS_ADDRESS está configurado, monitoree al menos estas métricas de Prometheus:

La saturación de estado afecta a la heurística correspondiente; la coincidencia exacta de trails permanece activa.

Envíe SIGHUP o use systemctl reload maltrail-sensor para solicitar una recarga de trails. Los archivos de trails actualizados por otro proceso se detectan automáticamente y se publican a los workers sin reiniciar el sensor.

El almacén de observables condensado (USE_CONDENSED_STORAGE, meta.sqlite) admite las vistas de novedad y retro-búsqueda del servidor. La compatibilidad con el sensor retirado está documentada en sensor/docs/COMPATIBILITY.md.

Retención de eventos

Maltrail no rota ni elimina registros de eventos. Los operadores son responsables de definir la retención, el archivado y la eliminación según los requisitos de almacenamiento y la política organizacional.

Prácticas recomendadas:

• Envíe la copia duradera de eventos a un servidor Maltrail remoto o SIEM con LOG_SERVER, SYSLOG_SERVER o LOGSTASH_SERVER.
• Alerte sobre maltrail_log_dir_free_bytes con suficiente margen para la tasa de eventos esperada.
• Rote, archive o elimine los registros diarios locales usando herramientas externas.
• Mantenga los archivos necesarios para la interfaz de informes sin comprimir en LOG_DIR; archive los archivos comprimidos en otro lugar.

Cuando el sistema de archivos de registros está lleno, el sensor no puede agregar eventos. Los registros de eventos también pueden contener direcciones IP y dominios que están regulados como datos personales en algunas jurisdicciones; la política de retención debe tener en cuenta los requisitos aplicables.

Documentación

Contribuciones

Se agradecen las adiciones de trails, el mantenimiento de feeds, los informes de errores, la documentación y las mejoras del sensor. Los envíos de trails deben incluir una fuente confiable y deben usar la clasificación más estrecha apropiada.

Ejecute las comprobaciones relevantes antes de enviar código. La compuerta completa del sensor es:```bash bash sensor/tools/check.sh

Ejecuta el formateo, Clippy con advertencias denegadas, pruebas de depuración y release, y la reproducción de paridad contra
el sensor Python retirado. Ejecuta la suite del servidor Python con:```bash
bash tests/run.sh python3

Proyecto

Licencia

Maltrail se distribuye bajo la Licencia MIT. Consulte LICENSE.

Mantenedores

• Miroslav Stampar (@stamparm)
• Mikhail Kasimov (@MikhailKasimov)

Patrocinadores

• Sansec (2024–2025)
• Sansec (2020–2021)

Presentaciones y publicaciones

• 47.ª Reunión TF-CSIRT, Praga, 2016 (diapositivas)
• Detect attacks on your network with Maltrail, Linux Magazine, 2022 (artículo)
• Best Cyber Threat Intelligence Feeds, Silent Push, 2022 (reseña)
• Research on Network Malicious Traffic Detection System Based on Maltrail, Nanotechnology Perceptions, 2024 (documento)

Lista negra derivada

Una lista solo de dominios derivada de trails/static/malware se publica en maltrail-malware-domains.txt. Puede utilizarse como entrada para sistemas de filtrado DNS, pero los operadores deben revisarla y probarla antes de habilitar el bloqueo. Las listas de inteligencia de amenazas pueden contener falsos positivos o indicadores que no son apropiados para todos los entornos.

Integraciones de terceros

• FreeBSD Port
• OPNsense Gateway Plugin
• D4 Project
• BlackArch Linux
• Validin
• Maltrail Add-on for Splunk
• Maltrail decoder and rules for Wazuh
• GScan (solo trails)
• MalwareWorld (solo trails)
• oisd domain blocklist (solo trails)
• NextDNS (solo trails)
• NoTracking (solo trails)
• OWASP Mobile Audit (solo trails)
• Mobile Security Framework MobSF (solo trails)
• pfBlockerNG-devel (solo trails)
• Sansec eComscan (solo trails)
• Palo Alto Networks Cortex XSOAR (conector de trails)

Agradecimientos

• Thomas Kristner
• Eduardo Arcusa Les
• James Lay
• Ladislav Baco (@laciKE)
• John Kristoff (@jtkdpu)
• Michael Münz (@mimugmail)
• David Brush
• @Godwottery
• Chris Wild (@briskets)
• Keith Irwin (@ki9us)
• Simon Szustkowski (@simonszu)