Maltrail

Maltrail est un système de détection du trafic réseau qui identifie les communications avec une infrastructure malveillante connue et signale certaines anomalies de trafic. Il compare les domaines, les URL, les adresses IP, les paires IP:port et les valeurs User-Agent observées sur le réseau à un ensemble d'indicateurs appelés trails.

Une détection est enregistrée comme un événement unique contenant la source, la destination, le protocole, le trail correspondant, la classification et la source du 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 conçu pour la surveillance réseau basée sur des indicateurs. Ses détections heuristiques complètent
la correspondance de trails, mais il ne remplace pas la télémétrie des points de terminaison ni un système
de prévention d'intrusion à usage général.

## Fonctionnalités

- Une construction complète de trails combinant plus de 3 000 fichiers statiques inclus, 42 intégrations de flux publics,
  et des trails facultatifs fournis par l'opérateur.
- Un capteur Rust multithread utilisant libpcap, avec des workers de capture Linux `PACKET_FANOUT` facultatifs.
- Un serveur Python fournissant l'interface de rapport, la réception des événements et l'API HTTP.
- Des trails et listes blanches personnalisés en texte clair, pouvant être relus et versionnés.
- Des heuristiques pour le scan, l'épuisement DNS, les requêtes de type DGA, les téléchargements suspects, les sondes de proxy,
  les valeurs User-Agent suspectes et les activités réseau associées.
- Journalisation locale des événements, journalisation Maltrail à distance, CEF via syslog, et sortie JSON Logstash.
- Validation du déploiement avec `maltrail-sensor -T` et métriques Prometheus facultatives.

## Sommaire

- [Architecture](#architecture)
- [Performance](#performance)
- [Installation](#installation)
  - [Installateur](#installer)
  - [Compilation depuis les sources](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Configuration](#configuration)
- [Trails](#trails)
- [Événements et API](#events-and-api)
- [Opérations](#operations)
  - [Supervision](#monitoring)
  - [Rétention des événements](#event-retention)
- [Documentation](#documentation)
- [Contribution](#contributing)
- [Projet](#project)
  - [Licence](#license)
  - [Mainteneurs](#maintainers)
  - [Sponsors](#sponsors)
  - [Présentations et publications](#presentations-and-publications)
  - [Liste noire dérivée](#derived-blacklist)
  - [Intégrations tierces](#third-party-integrations)
  - [Remerciements](#acknowledgements)

## Architecture

Maltrail se compose de deux processus indépendants qui peuvent s'exécuter sur le même hôte ou sur des hôtes séparés :```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

Le capteur capture le trafic, effectue la correspondance de trails et l'analyse heuristique, et produit des événements. Il peut écrire les événements localement (LOG_DIR), les envoyer à un serveur Maltrail distant (LOG_SERVER), ou faire les deux. Il peut également émettre du CEF via syslog (SYSLOG_SERVER) et du JSON vers Logstash (LOGSTASH_SERVER).

Le serveur reçoit et stocke les événements distants, sert les journaux d'événements disponibles localement, et fournit l'interface web et l'API.

Performances

Les performances dépendent du processeur, de la composition du trafic, de la taille du jeu de trails, du pilote de capture et de l'interface réseau. Les chiffres ci-dessous mesurent le chemin de traitement des paquets du capteur de manière isolée ; il ne s'agit pas de mesures de capture en direct de bout en bout.

Mesures représentatives sur un AMD Ryzen 7 PRO 4750U avec heuristiques activées et un jeu de trails de 1,5 million de lignes :

Les exécutions de comparaison hors ligne, utilisant la même capture générée, la même configuration et le même jeu de trails, ont mesuré un coût par paquet en régime permanent 14 à 37 fois inférieur à celui du capteur Python retiré sur les systèmes testés. L'outil de comparaison indique séparément le temps de processus complet, car le chargement des trails domine les rejeux courts. Il imprime également les compteurs d'événements ; la parité fonctionnelle est testée indépendamment par le corpus de parité.

Exécutez la comparaison sur le système cible avec :```bash python3 sensor/tools/bench_compare.py --packets 300000
--trails ~/.maltrail/trails.csv --repeat 3

Un worker de capture est utilisé par défaut. Des workers supplémentaires peuvent augmenter la capacité de capture, mais le hachage de flux de Linux répartit l'état par source entre les workers et réduit donc la sensibilité de certaines heuristiques de scan. Dans le test documenté, 91 % des alertes heuristiques à worker unique subsistaient avec deux workers, 86 % avec quatre et 65 % avec huit. La correspondance exacte des traces était inchangée. N'augmentez `CAPTURE_FANOUT` que lorsque les métriques de perte de capture montrent que c'est nécessaire.

La méthodologie de benchmark, les résultats matériels, la sortie du profileur, les mesures de mémoire et les vérifications de fanout en direct sont documentés dans [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/REPORT.md).

## Installation

### Installateur

L'installateur prend en charge Debian, Ubuntu, Raspberry Pi OS, RHEL, Fedora et openSUSE :```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

Il installe les dépendances, crée une copie de travail gérée sous /opt/maltrail, vérifie la somme de contrôle de la sonde précompilée, crée un compte non privilégié maltrail, installe les unités systemd, prépare les répertoires de logs et d'état, puis démarre la sonde et le serveur. Réexécuter l'installeur met à jour la copie de travail gérée.

Examinez le script avant de l'exécuter avec des privilèges élevés. Depuis une copie de travail existante, l'essai à blanc affiche les commandes sans modifier le système :```bash sh install.sh --dry-run

Options d'installation courantes :```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

Le tableau de bord est disponible à http://127.0.0.1:8338 après l'installation. Notez que la variable HTTP_ADDRESS fournie est 0.0.0.0, elle est donc accessible sur toutes les interfaces, pas seulement loopback — et les identifiants par défaut sont admin / changeme!. Modifiez USERS, et définissez HTTP_ADDRESS sur 127.0.0.1 (ou placez le serveur derrière un proxy inverse avec TLS), avant que l'hôte ne se trouve sur un réseau non fiable.

La construction initiale des trails peut prendre plusieurs minutes. Le capteur ne détecte les correspondances de trails que lorsqu'un jeu de trails valide est disponible. L'unité systemd exécute la validation -T du capteur avant le démarrage afin que des privilèges manquants, un répertoire de journalisation non inscriptible ou un jeu de trails invalide provoquent un échec de démarrage visible.

Le banc de test de l'installeur couvre les conteneurs Ubuntu, Debian, Fedora, openSUSE et Alpine. Alpine utilise musl et n'utilise pas le binaire de capteur glibc préconstruit ; compilez le capteur à partir des sources dans ce cas.

Compilation à partir des sources

Le capteur nécessite Rust 1.74 ou plus récent, les en-têtes de développement libpcap et les outils de capacité du système. Le serveur et l'outil de mise à jour des trails nécessitent Python 3.6 ou plus récent.

Installez les paquets de distribution :```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

Ensuite, construisez et validez le capteur:```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

Démarrez le serveur dans un autre terminal ou sur un autre hôte:```bash python3 server.py

Les binaires de capteur précompilés `x86_64` et `aarch64` sont joints aux versions actuelles avec des sommes de contrôle SHA-256.
Ils ciblent glibc 2.28 et nécessitent libpcap à l'exécution. Sur les systèmes basés sur musl, comme
Alpine Linux, compilez à partir des sources.

L'ancien capteur Python n'est utilisé que par les outils de comparaison et de parité. Ces outils
nécessitent en outre `pcapy-ng` et les en-têtes de développement Python décrits dans
[`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md).

### Systemd

Les unités `maltrail-server.service` et `maltrail-sensor.service` fournies exécutent les deux processus sous l'utilisateur
non privilégié `maltrail`. Systemd crée `/var/log/maltrail` et `/var/lib/maltrail`, restreint
l'accès au système de fichiers et accorde au capteur `CAP_NET_RAW` et `CAP_NET_ADMIN`.

L'installateur configure ces unités automatiquement. Pour une installation existante à partir des sources, suivez
la procédure de service manuelle dans [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md).

Vérifiez l'état du service et les journaux avec :```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

Docker

Démarrez le déploiement Compose fourni avec :```bash docker compose -f docker/docker-compose.yml up -d

La configuration du conteneur, le stockage, les privilèges et les contrôles de santé sont documentés dans
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/HEAD/docker/README.md).

## Configuration

Maltrail lit `maltrail.conf`, qui contient des paramètres distincts `[Sensor]` et `[Server]`.
L'installateur place la configuration gérée dans `/etc/maltrail.conf`.

Les options de capteur fréquemment utilisées incluent :

| Option | Objectif |
| --- | --- |
| `MONITOR_INTERFACE` | Interface ou interfaces de capture ; `any` sélectionne toutes les interfaces prises en charge |
| `CAPTURE_FILTER` | Filtre de capture BPF |
| `CAPTURE_FANOUT` | Nombre de sockets de capture Linux ; défini par défaut sur un |
| `LOG_DIR` | Répertoire local des journaux d'événements |
| `TRAILS_FILE` | Base de données de traces générée |
| `LOG_SERVER` | Serveur d'événements Maltrail distant |
| `SYSLOG_SERVER` | Destination ou destinations syslog CEF |
| `LOGSTASH_SERVER` | Destination ou destinations JSON Logstash |
| `STATS_ADDRESS` | Écouteur de métriques Prometheus ; désactivé sauf si configuré |
| `UPDATE_PERIOD` | Intervalle d'actualisation des traces |
| `USER_WHITELIST` | Indicateurs gérés par l'opérateur qui ne doivent pas déclencher d'alerte |
| `CUSTOM_TRAILS_DIR` | Répertoire de traces géré par l'opérateur |

`PROCESS_COUNT` s'applique à l'ancien capteur Python. Configurez les workers de capture du capteur Rust
avec `CAPTURE_FANOUT` à la place.

Exécutez la vérification de déploiement après avoir modifié la configuration :```bash
sensor/target/release/maltrail-sensor -T

La vérification valide la configuration, les trails, les entrées de la liste blanche, le filtre de capture, les privilèges, le stockage des journaux, la prise en charge des mises à jour et les paramètres des workers. Une vérification réussie inclut des compteurs positifs de trails et de listes blanches plutôt que de simplement confirmer que les fichiers existent.

Trails

Les trails sont stockés sous forme d'indicateurs en texte brut :```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

Ajoutez des indicateurs locaux dans `CUSTOM_TRAILS_DIR`. Ajoutez les indicateurs qui ne doivent jamais générer d'alertes
dans `USER_WHITELIST`. Conserver des données personnalisées en dehors du dépôt géré empêche les mises à jour de
l'écraser.

Le programme de mise à jour reconstruit `TRAILS_FILE` à partir des flux activés, des pistes statiques groupées et des pistes personnalisées. Un
nouveau fichier est publié de manière atomique uniquement après une construction réussie. Les flux vides ou en échec sont signalés
afin qu'un déploiement en cours ne dépende pas silencieusement de sources obsolètes ou retirées.

Les contributions de pistes doivent inclure l'indicateur, la classification et une source vérifiable. Voir
[Contributing](#contributing) avant de soumettre une demande de tirage (pull request).

## Events and API

Maltrail enregistre un événement séparé par des espaces par détection, en utilisant le guillemet CSV lorsqu'une valeur
contient des espaces :```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

Le champ type identifie ce qui a correspondance, notamment DNS, IP, IPORT, URL, PATH, HTTP, UA, PORT, et CERT. Le champ info contient la classification de la piste, et reference identifie la liste statique, le flux, la source personnalisée, ou l'heuristique qui l'a produit.

Recherche d'indicateur

Utilisez /check pour interroger un domaine, une adresse IP ou une URL :```bash curl 'http://127.0.0.1:8338/check?q=www.sub.evil.example'

I didn't receive any input content to translate. The "INPUT:" section is empty. Please provide the chunk text you'd like translated.```json
{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)"
}

Une recherche de sous-domaine peut correspondre à son parent listé. Les recherches d'URL vérifient host/path avant de vérifier l'hôte seul. Le serveur lit la base de données de trails mappée en mémoire et observe les mises à jour des trails sans redémarrage.

Les trails statiques publics et les trails de flux sont disponibles sans authentification, conformément à l'endpoint /trails utilisé par les capteurs distants. Les trails personnalisés nécessitent une session autorisée ; une recherche personnalisée non autorisée est signalée comme un échec. Les données d'événements restent authentifiées.

Opérations

Surveillance

Utilisez maltrail-sensor -T comme contrôle de déploiement et de configuration. L'unité systemd fournie l'exécute en tant que ExecStartPre.

Lorsque STATS_ADDRESS est configuré, surveillez au moins ces métriques Prometheus :

La saturation d'état affecte l'heuristique correspondante ; la correspondance exacte des trails reste active.

Envoyez SIGHUP ou utilisez systemctl reload maltrail-sensor pour demander un rechargement des trails. Les fichiers de trails mis à jour par un autre processus sont détectés automatiquement et publiés vers les workers sans redémarrer le capteur.

Le stockage condensé d'observables (USE_CONDENSED_STORAGE, meta.sqlite) prend en charge les vues de nouveauté et de retro-hunt du serveur. La compatibilité avec l'ancien capteur retiré est documentée dans sensor/docs/COMPATIBILITY.md.

Rétention des événements

Maltrail ne procède ni à la rotation ni à la suppression des journaux d'événements. Les opérateurs sont responsables de la définition de la rétention, de l'archivage et de la suppression en fonction des exigences de stockage et de la politique de l'organisation.

Pratiques recommandées :

• Envoyez la copie durable des événements à un serveur Maltrail distant ou à un SIEM avec LOG_SERVER, SYSLOG_SERVER ou LOGSTASH_SERVER.
• Alertez sur maltrail_log_dir_free_bytes avec une marge suffisante pour le débit d'événements attendu.
• Effectuez la rotation, l'archivage ou la suppression des journaux quotidiens locaux à l'aide d'outils externes.
• Conservez non compressés dans LOG_DIR les fichiers nécessaires à l'interface de reporting ; archivez les fichiers compressés ailleurs.

Lorsque le système de fichiers de journaux est plein, le capteur ne peut pas ajouter d'événements. Les journaux d'événements peuvent également contenir des adresses IP et des domaines qui sont réglementés comme des données personnelles dans certaines juridictions ; la politique de rétention doit tenir compte des exigences applicables.

Documentation

Contribution

Les ajouts de trails, la maintenance des flux, les rapports de bogues, la documentation et les améliorations du capteur sont les bienvenus. Les soumissions de trails doivent inclure une source fiable et utiliser la classification appropriée la plus spécifique.

Exécutez les vérifications pertinentes avant de soumettre du code. Le contrôle complet du capteur est :```bash bash sensor/tools/check.sh

Il exécute le formatage, Clippy avec les avertissements interdits, les tests de debug et de release, et le rejeu de parité par rapport au capteur Python retiré. Exécutez la suite du serveur Python avec :```bash
bash tests/run.sh python3

Projet

Licence

Maltrail est distribué sous la licence MIT. Voir LICENSE.

Mainteneurs

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

Sponsors

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

Présentations et publications

• 47e réunion TF-CSIRT, Prague, 2016 (diapositives)
• Détectez les attaques sur votre réseau avec Maltrail, Linux Magazine, 2022 (article)
• Meilleurs flux de renseignement sur les cybermenaces, Silent Push, 2022 (analyse)
• Recherche sur un système de détection du trafic réseau malveillant basé sur Maltrail, Nanotechnology Perceptions, 2024 (publication)

Liste noire dérivée

Une liste de domaines uniquement, dérivée de trails/static/malware, est publiée à l'adresse maltrail-malware-domains.txt. Elle peut être utilisée comme entrée pour les systèmes de filtrage DNS, mais les opérateurs doivent l'examiner et la tester avant d'activer le blocage. Les listes de renseignement sur les menaces peuvent contenir des faux positifs ou des indicateurs qui ne sont pas appropriés pour tous les environnements.

Intégrations tierces

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

Remerciements

• 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)