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

## Características

- Una compilación completa de trails que combina más de 3.000 archivos estáticos incluidos, 42 integraciones de feeds públicos
  y trails opcionales proporcionados por el operador.
- Un sensor multihilo en Rust que utiliza libpcap, con workers de captura opcionales de Linux `PACKET_FANOUT`.
- Un servidor en 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 por versiones.
- Heurísticas para escaneos, agotamiento de DNS, búsquedas similares a DGA, descargas sospechosas, sondeos de proxy,
  valores de User-Agent sospechosos y actividad de red relacionada.
- Registro local de eventos, registro remoto de Maltrail, CEF sobre syslog y salida JSON de Logstash.
- Validación del despliegue con `maltrail-sensor -T` y métricas opcionales de Prometheus.

## Contenido

- [Arquitectura](#architecture)
- [Interfaz de informes](#reporting-interface)
- [Rendimiento](#performance)
- [Instalación](#installation)
  - [Instalador](#installer)
  - [Compilación desde el código fuente](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Configuración](#configuration)
- [Trails](#trails)
- [Eventos y API](#events-and-api)
- [Operaciones](#operations)
  - [Monitorización](#monitoring)
  - [Retención de eventos](#event-retention)
- [Documentación](#documentation)
- [Contribuir](#contributing)
- [Proyecto](#project)
  - [Licencia](#license)
  - [Mantenedores](#maintainers)
  - [Patrocinadores](#sponsors)
  - [Presentaciones y publicaciones](#presentations-and-publications)
  - [Lista negra derivada](#derived-blacklist)
  - [Integraciones de terceros](#third-party-integrations)
  - [Agradecimientos](#acknowledgements)

## 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

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

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

## Instalación

### Instalador

El instalador está verificado en doce distribuciones de Linux — Debian, Ubuntu, Fedora, Rocky, AlmaLinux, Arch, openSUSE Leap y Tumbleweed, y Alpine — además de FreeBSD y macOS, en cada versión, con el resultado completo registrado en [`docs/compat`](https://github.com/stamparm/maltrail/blob/master/docs/compat). Raspberry Pi OS y otros sistemas ARM de 64 bits utilizan la compilación `aarch64`; ARM de 32 bits no tiene sensor precompilado y debe compilarlo desde el código fuente.```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

Opciones comunes del instalador:```bash
sh install.sh --role sensor      # Install only the sensor
sh install.sh --ref 3.1.2        # 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

Luego construye 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

Los binarios precompilados del sensor se adjuntan a las versiones actuales con sumas de verificación SHA-256: Linux `x86_64`
y `aarch64` tanto para glibc como para musl, macOS en Apple silicon e Intel, FreeBSD `amd64`, y
Windows `x86_64`.

Las compilaciones para glibc enlazan libpcap de forma estática y tienen como objetivo glibc 2.28, por lo que la biblioteca C es lo único que
necesitan — nada que instalar, tanto en RHEL 8+, Debian 10+, Ubuntu 18.04+ como en Leap 15.x. Las compilaciones
para musl son totalmente estáticas, por lo que Alpine no necesita nada en absoluto. La compilación para Windows es de 64 bits y necesita Windows 10 o posterior además de
[Npcap](https://npcap.com) instalado antes de que pueda iniciarse — `wpcap.dll` es una dependencia de tiempo de carga,
por lo que sin él el cargador rechaza el ejecutable en lugar de fallar en la captura. El archivo también lo dice.

Los binarios de **3.1.1 y anteriores** no lo hacían: enlazaban libpcap de forma dinámica y la solicitaban por
el nombre que usa su host de compilación AlmaLinux. Debian y Ubuntu distribuyen la biblioteca idéntica bajo el
nombre más antiguo `libpcap.so.0.8`, por lo que esos binarios se detienen antes de arrancar —```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file

### Systemd

Las unidades proporcionadas en `packaging/systemd/` ejecutan ambos procesos como el
usuario sin privilegios `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 desde código fuente existente, siga
el procedimiento manual del servicio 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

La configuración del contenedor, el almacenamiento, los privilegios y las comprobaciones de estado se documentan 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; por defecto uno |
| `CAPTURE_WORKERS` | Workers de captura, un socket cada uno; por defecto `CAPTURE_FANOUT`, por lo que uno a menos que se establezca cualquiera de los dos |
| `LOG_DIR` | Directorio local del registro de eventos |
| `TRAILS_FILE` | Base de datos de trails generada |
| `LOG_SERVER` | Servidor remoto de eventos de Maltrail |
| `SYSLOG_SERVER` | Destino o destinos de syslog CEF |
| `LOGSTASH_SERVER` | Destino o destinos de Logstash JSON |
| `STATS_ADDRESS` | Escucha de métricas de Prometheus; deshabilitado a menos que se configure |
| `UPDATE_PERIOD` | Intervalo de actualización de trails |
| `STATIC_TRAILS_URL` | De dónde se obtiene el conjunto de trails estáticos ensamblado; fíjalo a una versión con fecha para controlar cuándo llega contenido nuevo |
| `USER_WHITELIST` | Indicadores gestionados por el operador que no deberían generar alertas |
| `CUSTOM_TRAILS_DIR` | Directorio de trails gestionado por el operador |
| `STATIC_TRAILS_DIR` | Checkout opcional del repositorio de trails; solo se usa para mostrar la cita de origen de un trail en la interfaz |

`PROCESS_COUNT` se aplica al sensor Python retirado y al limitador de registro de eventos heredado; **no**
establece el número de workers del sensor Rust. Configura los workers de captura con `CAPTURE_FANOUT` o
`CAPTURE_WORKERS` en su lugar.

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

Apúntalo a una versión específica `content-YYYYMMDD-HHMM` para fijar una versión, de modo que una publicación defectuosa no sea inmediatamente global. El conjunto se almacena en caché junto a `TRAILS_FILE`, que es lo que hace posible una reconstrucción sin conexión o en un entorno aislado; el `sha256` publicado se verifica antes de la descarga, por lo que un despliegue que se actualiza con más frecuencia de la que cambia el contenido transfiere 65 bytes en lugar de 11 MB, y una carga útil que no coincide con su digest se rechaza en favor de la caché.

`update_trails()` publica un nuevo `TRAILS_FILE` de forma atómica y solo tras una compilación exitosa. Los feeds que no devuelven nada se reportan por nombre, de modo que un despliegue no depende silenciosamente de una fuente que se ha retirado discretamente.

Añade tus propios indicadores en `CUSTOM_TRAILS_DIR`, y cualquier cosa que nunca deba generar un evento en `USER_WHITELIST`. Mantén ambos fuera del directorio de instalación para que una actualización no pueda sobrescribirlos.

Las contribuciones de trails estáticos van a [stamparm/trails](https://github.com/stamparm/trails); los nuevos feeds van aquí. En cualquier caso, un indicador necesita una clasificación y una fuente que alguien pueda verificar — consulta [Contributing](#contributing).

## Events and API

Maltrail registra un evento separado por espacios en blanco por cada 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>

| `-s` | `--server` | Server URL (default: `http://localhost:8080`) |
| `-t` | `--token` | Authentication token |
| `-o` | `--output` | Output file path |
| `-f` | `--format` | Output format: `json`, `yaml`, `table` |
| `-v` | `--verbose` | Enable verbose logging |
| `-q` | `--quiet` | Suppress non-error output |
| `-h` | `--help` | Show help message |
| `-V` | `--version` | Show version information |

### Examples

```bash
# Basic scan
scanner scan --target example.com

# Scan with custom output format
scanner scan --target example.com --format json --output results.json

# Authenticated scan
scanner scan --target example.com --token "your-api-token"

# Verbose mode
scanner scan --target example.com --verbose

server:
  url: "http://localhost:8080"
  timeout: 30

scan:
  threads: 10
  timeout: 60
  user_agent: "Scanner/1.0"

output:
  format: "json"
  verbose: false

Authorization: Bearer <token>

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600
}

{
  "target": "example.com",
  "options": {
    "threads": 10,
    "timeout": 60
  }
}

{
  "scan_id": "abc123",
  "status": "running",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "scan_id": "abc123",
  "status": "completed",
  "results": {
    "vulnerabilities": [],
    "findings": []
  }
}

{
  "message": "Scan deleted successfully"
}

Error: dial tcp 127.0.0.1:8080: connect: connection refused

Error: 401 Unauthorized

Error: context deadline exceeded

scanner scan --target example.com --verbose --debug

# Clone the repository
git clone https://github.com/example/scanner.git
cd scanner

# Install dependencies
go mod download

# Build the project
go build -o scanner ./cmd/scanner

# Run tests
go test ./...

El campo `confidence` (0-100, o `null` cuando no está disponible) indica con qué fuerza respaldan las fuentes el listado: 40 para un único feed, +15 por cada feed adicional que coincida de forma independiente hasta 100, y la puntuación completa para las entradas personalizadas y estáticas del propio operador. Se calcula en el momento de la actualización del trail a partir de la coincidencia de feeds en un sidecar `trails.confidence` junto a `trails.csv`; un servidor que obtiene trails de un `UPDATE_SERVER` no tiene procedencia que puntuar y reporta `null`. Úsalo para priorizar el triaje: un listado de un solo feed con 40 merece una segunda revisión antes de ganarse una regla de firewall.

Una búsqueda de subdominio puede coincidir con su padre listado. Las búsquedas de URL comprueban `host/path` antes de comprobar solo el host. El servidor lee la base de datos de trails mapeada en memoria y observa las actualizaciones de trails sin reiniciarse.

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

## Operaciones

### Monitorización

Usa `maltrail-sensor -T` como puerta de despliegue y configuración. La unidad systemd proporcionada lo ejecuta como `ExecStartPre`.

Para confirmar que la detección en sí funciona — no solo que los procesos arrancan — ejecuta:```bash
python3 server.py --detect-test

`--keep` también reproduce `sensor/tests/corpus/` en el mismo registro e imprime cuáles de las formas que el panel renderiza de manera diferente tienen un evento detrás, de modo que un icono, color o glifo faltante sea visible en lugar de asumido. Las marcas de tiempo se desplazan para que el día más reciente sea hoy. Se requiere un binario del sensor (`cargo build --release --manifest-path sensor/Cargo.toml`).

Los datos de la demo pública se regeneran a partir de una ejecución de este tipo:```bash
python3 sensor/tools/gen_demo_js.py --from DIR/logs   # tops up html/js/demo.js

Ejecuta el formateo, Clippy con advertencias denegadas, y las suites de pruebas de depuración y de lanzamiento. Ejecuta la suite del servidor Python con:```bash
bash tests/run.sh python3

Se compila de forma cruzada el sensor con mingw-w64, se extrae la biblioteca de espacio de usuario de Npcap desde su instalador
(un archivo NSIS, por lo que no se instala nada), y se ejecuta el resultado bajo Wine — toda la suite de pruebas,
`-T` contra la configuración incluida, el corpus de pcap comparado byte a byte contra el binario nativo,
y el servidor respondiendo a `/ping` bajo un Python de Windows. La captura en vivo es lo único que
no puede cubrir; eso requiere el controlador del kernel de Npcap y una máquina Windows real. Los requisitos previos son
`gcc-mingw-w64-x86-64`, `wine` y `p7zip-full`.

## Proyecto

### Licencia

**TL;DR:** Maltrail tiene licencia MIT, pero el conjunto de datos Maltrail Trails tiene términos separados. La consulta/referencia independiente de IOC está bien; el uso sistemático de Trails como fuente de inteligencia en un producto o servicio comercial requiere permiso/licencia.

Maltrail se distribuye bajo la Licencia MIT. Consulte [`LICENSE`](https://github.com/stamparm/maltrail/blob/master/LICENSE).

Ese es el motor. El conjunto de trails estático es un trabajo separado bajo términos separados: gratuito para uso
defensivo interno, investigación y enseñanza, pero un producto comercial, servicio, oferta de MSSP o MDR, o un
feed redistribuido necesita una licencia. Un motor MIT no hace que el contenido sea gratuito para vender — consulte
[`LICENSE.md`](https://github.com/stamparm/trails/blob/main/LICENSE.md) en
[stamparm/trails](https://github.com/stamparm/trails) antes de incluirlo en algo por lo que cobre.

### Mantenedores

- Miroslav Stampar ([@stamparm](https://github.com/stamparm))
- Mikhail Kasimov ([@MikhailKasimov](https://github.com/MikhailKasimov))

### Patrocinadores

- [Sansec](https://sansec.io/) (2024–2025)
- [Sansec](https://sansec.io/) (2020–2021)

### Presentaciones y publicaciones

- 47th TF-CSIRT Meeting, Praga, 2016
  ([diapositivas](https://web.archive.org/web/20161109135211/https://www.terena.org/activities/tf-csirt/meeting47/M.Stampar-Maltrail.pdf))
- _Detect attacks on your network with Maltrail_, Linux Magazine, 2022
  ([artículo](https://www.linux-magazine.com/Issues/2022/258/Maltrail))
- _Best Cyber Threat Intelligence Feeds_, Silent Push, 2022
  ([reseña](https://www.silentpush.com/blog/best-cyber-threat-intelligence-feeds))
- _Research on Network Malicious Traffic Detection System Based on Maltrail_, Nanotechnology
  Perceptions, 2024
  ([artículo](https://nano-ntp.com/index.php/nano/article/view/1915/1497))

### Integraciones de terceros

- [FreeBSD Port](https://www.freshports.org/security/maltrail)
- [OPNsense Gateway Plugin](https://github.com/opnsense/plugins/pull/1257)
- [D4 Project](https://www.d4-project.org/2019/09/25/maltrail-integration.html)
- [BlackArch Linux](https://github.com/BlackArch/blackarch/blob/master/packages/maltrail/PKGBUILD)
- [Validin](https://x.com/ValidinLLC/status/1719666086390517762)
- [Maltrail Add-on for Splunk](https://splunkbase.splunk.com/app/7211)
- [Maltrail decoder and rules for Wazuh](https://github.com/MikhailKasimov/maltrail-wazuh-decoder-and-rules)
- [GScan](https://github.com/grayddq/GScan) (solo trails)
- [MalwareWorld](https://www.malwareworld.com/) (solo trails)
- [oisd domain blocklist](https://oisd.nl/?p=inc) (solo trails)
- [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json) (solo trails)
- [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md) (solo trails)
- [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables) (solo trails)
- [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876) (solo trails)
- [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json) (solo trails)
- [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license) (solo trails)
- [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed) (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)