Maltrail est conçu pour la surveillance réseau basée sur des indicateurs. Ses détections heuristiques complètent
la correspondance de traces, 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 traces combinant plus de 3 000 fichiers statiques groupés, 42 intégrations de flux publics,
  et des traces facultatives fournies 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 d'événements et l'API HTTP.
- Des traces personnalisées et des listes blanches en texte brut qui peuvent être examinées et versionnées.
- Des heuristiques pour le balayage, l'épuisement DNS, les recherches de type DGA, les téléchargements suspects, les sondes de proxy,
  les valeurs User-Agent suspectes et l'activité réseau associée.
- 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.

## Contenu

- [Architecture](#architecture)
- [Interface de rapport](#reporting-interface)
- [Performances](#performance)
- [Installation](#installation)
  - [Programme d'installation](#installer)
  - [Compilation à partir des sources](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Configuration](#configuration)
- [Traces](#trails)
- [Événements et API](#events-and-api)
- [Opérations](#operations)
  - [Surveillance](#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 distincts :```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

Un seul worker de capture est utilisé par défaut. Des workers supplémentaires peuvent augmenter la capacité de capture, mais le
hachage de flux 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 sont restées avec deux
workers, 86 % avec quatre, et 65 % avec huit. La correspondance exacte des traces est restée inchangée. Augmentez
`CAPTURE_FANOUT` uniquement lorsque les métriques de perte de capture montrent que cela 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/master/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

Common installer options :```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

Alors, 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

Les binaires de capteur `x86_64` et `aarch64` précompilés sont joints aux versions actuelles avec des sommes de contrôle SHA-256.
Ils lient libpcap de manière statique et ciblent glibc 2.28, donc la bibliothèque C est la seule chose
dont ils ont besoin — rien à installer, sur RHEL 8+, Debian 10+, Ubuntu 18.04+ et Leap 15.x de la même manière. Sur
les systèmes basés sur musl tels qu'Alpine Linux, compilez à partir des sources.

Les binaires de **3.1.1 et antérieurs** ne le faisaient pas : ils liaient libpcap de manière dynamique, et la demandaient sous
le nom utilisé par leur hôte de compilation AlmaLinux. Debian et Ubuntu fournissent la bibliothèque identique sous
l'ancien nom `libpcap.so.0.8`, donc ces binaires s'arrêtent avant même de démarrer —```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file

### Systemd

Les unités fournies dans `packaging/systemd/` 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 les capacités `CAP_NET_RAW` et `CAP_NET_ADMIN`.

L'installateur configure ces unités automatiquement. Pour une installation existante depuis les sources, suivez
la procédure de service manuelle dans [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/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

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/master/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 ; par défaut un |
| `CAPTURE_WORKERS` | Workers de capture, un socket chacun ; par défaut `CAPTURE_FANOUT`, donc un sauf si l'un ou l'autre est défini |
| `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 configuration |
| `UPDATE_PERIOD` | Intervalle d'actualisation des traces |
| `STATIC_TRAILS_URL` | Emplacement où l'ensemble de traces statiques assemblé est récupéré ; épinglez-le à une version datée pour contrôler l'arrivée de nouveau contenu |
| `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 |
| `STATIC_TRAILS_DIR` | Extraction facultative du dépôt de traces ; utilisé uniquement pour afficher la citation de la source d'une trace dans l'interface |

`PROCESS_COUNT` s'applique au capteur Python retiré et au limiteur de débit des journaux d'événements hérité ; il ne définit **pas** le nombre de workers du capteur Rust. Configurez les workers de capture avec `CAPTURE_FANOUT` ou `CAPTURE_WORKERS` à la place.

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

Pointez-le vers une version spécifique `content-YYYYMMDD-HHMM` pour épingler une version, afin qu’une mauvaise publication ne soit pas immédiatement globale. L’ensemble est mis en cache à côté de `TRAILS_FILE`, ce qui permet une reconstruction hors ligne ou en environnement isolé ; le `sha256` publié est vérifié avant le téléchargement, donc un déploiement qui se met à jour plus souvent que le contenu ne change transfère 65 octets plutôt que 11 Mo, et une charge utile qui ne correspond pas à son empreinte est refusée au profit du cache.

`update_trails()` publie un nouveau `TRAILS_FILE` de manière atomique et uniquement après une construction réussie. Les flux qui ne renvoient rien sont signalés par leur nom, afin qu’un déploiement ne dépende pas silencieusement d’une source qui a discrètement cessé son activité.

Ajoutez vos propres indicateurs sous `CUSTOM_TRAILS_DIR`, et tout ce qui ne doit jamais déclencher d’événement dans `USER_WHITELIST`. Conservez les deux en dehors du répertoire d’installation afin qu’une mise à niveau ne puisse pas les écraser.

Les contributions de traces statiques vont à [stamparm/trails](https://github.com/stamparm/trails) ; les nouveaux flux vont ici. Dans les deux cas, un indicateur nécessite une classification et une source que quelqu’un peut vérifier — voir [Contributing](#contributing).

## Événements et API

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

{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)",
  "confidence": 100
}
```
Le champ `confidence` (0-100, ou `null` lorsqu'il est indisponible) indique à quel point les sources appuient la
liste : 40 pour un flux unique, +15 par flux supplémentaire concordant de manière indépendante jusqu'à 100, et
la note maximale pour les entrées personnalisées et statiques propres à l'opérateur. Il est calculé au moment de la mise à jour des trails à partir
de la concordance des flux dans un fichier sidecar `trails.confidence` à côté de `trails.csv` ; un serveur qui tire les trails
d'un `UPDATE_SERVER` n'a aucune provenance à noter et rapporte `null`. Utilisez-le pour prioriser
le triage — une liste issue d'un flux unique à 40 mérite un second regard avant de mériter une règle de pare-feu.

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 de trails sans
redémarrage.

Les trails statiques et de flux publics sont disponibles sans authentification, conformément au point de terminaison `/trails`
utilisé par les capteurs distants. Les trails personnalisés nécessitent une session autorisée ; une recherche
uniquement 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 passerelle de déploiement et de configuration. L'unité systemd fournie l'exécute
comme `ExecStartPre`.

Pour confirmer que la détection elle-même fonctionne — pas seulement que les processus démarrent — exécutez :```bash
python3 server.py --detect-test
```
Il rejoue un pcap conçu de trafic malveillant émulé (les pistes correspondent à une requête DNS, une IP, une
`IP:port`, un chemin d'URL et un en-tête `Host`, plus les heuristiques d'injection SQL, de traversée, d'exécution de code à distance (RCE), de XSS, de sonde proxy,
de sinkhole, de `Host` manquant et de balayage port/web/infection) via le capteur installé
et vérifie que chaque détection attendue se déclenche. Il ne nécessite ni root, ni interface, ni ensemble de pistes
propre. Une installation saine affiche `20/20 détection(s) déclenchée(s)`.

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

| Métrique | Signification opérationnelle |
| --- | --- |
| `maltrail_up == 0` | Aucun processus de capture ne s'exécute |
| Augmentation de `maltrail_capture_dropped_total` | L'anneau de capture abandonne des paquets |
| Augmentation de `maltrail_local_log_errors_total` | Des événements ont été produits mais n'ont pas pu être écrits localement |
| Augmentation de `maltrail_remote_log_errors_total` | Des événements n'ont pas pu être livrés à une destination distante ; avec `DISABLE_LOCAL_LOG_STORAGE`, ils sont perdus |
| `maltrail_trail_generation` qui n'avance pas | L'ensemble de pistes actif n'est pas actualisé |
| `maltrail_log_dir_free_bytes` | Capacité restante pour le stockage local des événements |
| Augmentation de `maltrail_state_saturations_total` | Une limite d'état heuristique a été atteinte |
| Augmentation de `maltrail_throttle_evictions_total` | La table de limitation des événements est à sa capacité maximale, donc les événements sont agrégés plus tôt que configuré |

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

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

Le magasin d'observables condensé (`USE_CONDENSED_STORAGE`, `meta.sqlite`) prend en charge les vues de nouveauté
et de rétro-recherche du serveur. L'index latéral du journal d'événements par jour (`USE_EVENT_INDEX`,
`LOG_DIR/index/*.sqlite`, environ deux fois la taille du journal sur disque) est ce qui rend `/counts` exact et
`/hunt` rapide ; il est maintenu de manière incrémentale à partir des journaux eux-mêmes et peut être reconstruit avec
`server.py --rebuild-index`. La compatibilité avec le capteur retiré est documentée dans
[`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md).

### Rétention des événements

Maltrail ne fait pas pivoter ni ne supprime les journaux d'événements. Les opérateurs sont responsables de définir la rétention,
l'archivage et la suppression en fonction des exigences de stockage et de la politique organisationnelle.

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 taux d'événements attendu.
- Faites pivoter, archivez ou supprimez les journaux quotidiens locaux à l'aide d'outils externes.
- Conservez les fichiers nécessaires à l'interface de rapport non compressés dans `LOG_DIR` ; 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 données personnelles dans certaines juridictions ; la politique de rétention
doit tenir compte des exigences applicables.

## Documentation

| Document | Contenu |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md) | Installation, privilèges, configuration et dépannage |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ARCHITECTURE.md) | Internes du capteur et flux de données |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) | Différences délibérées par rapport au capteur Python retiré |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md) | Mesures, profils et résultats de test |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ROADMAP.md) | Travaux ouverts sur le capteur |
| [`SekuriPy Labs`](https://www.sekuripy.hr/labs/maltrail/) | Notes d'ingénierie, benchmarks et comptes rendus |

## Contribution

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

Exécutez les vérifications pertinentes avant de soumettre du code. La passerelle complète du capteur est :```bash
bash sensor/tools/check.sh
```
Il exécute le formatage, Clippy avec les avertissements refusés, ainsi que les suites de tests debug et release. Exécutez la
suite de serveur Python avec :```bash
bash tests/run.sh python3
```
## Projet

### Licence

Maltrail est distribué sous la licence MIT. Voir [`LICENSE`](https://github.com/stamparm/maltrail/blob/master/LICENSE).

### Mainteneurs

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

### Sponsors

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

### Présentations et publications

- 47e réunion TF-CSIRT, Prague, 2016
  ([diapositives](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
  ([article](https://www.linux-magazine.com/Issues/2022/258/Maltrail))
- _Best Cyber Threat Intelligence Feeds_, Silent Push, 2022
  ([critique](https://www.silentpush.com/blog/best-cyber-threat-intelligence-feeds))
- _Research on Network Malicious Traffic Detection System Based on Maltrail_, Nanotechnology
  Perceptions, 2024
  ([article](https://nano-ntp.com/index.php/nano/article/view/1915/1497))

### Liste noire dérivée

Une liste limitée aux domaines, dérivée des pistes statiques `malware/`, est publiée à l'adresse
[`maltrail-malware-domains.txt`](https://raw.githubusercontent.com/stamparm/aux/master/maltrail-malware-domains.txt).
Elle peut être utilisée comme entrée pour les systèmes de filtrage DNS, mais les opérateurs doivent la vérifier 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

- [Port FreeBSD](https://www.freshports.org/security/maltrail)
- [Plugin passerelle OPNsense](https://github.com/opnsense/plugins/pull/1257)
- [Projet D4](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)
- [Module complémentaire Maltrail pour Splunk](https://splunkbase.splunk.com/app/7211)
- [Décodeur et règles Maltrail pour Wazuh](https://github.com/MikhailKasimov/maltrail-wazuh-decoder-and-rules)
- [GScan](https://github.com/grayddq/GScan) (pistes uniquement)
- [MalwareWorld](https://www.malwareworld.com/) (pistes uniquement)
- [Liste de blocage de domaines oisd](https://oisd.nl/?p=inc) (pistes uniquement)
- [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json) (pistes uniquement)
- [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md) (pistes uniquement)
- [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables) (pistes uniquement)
- [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876) (pistes uniquement)
- [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json) (pistes uniquement)
- [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license) (pistes uniquement)
- [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed) (connecteur de pistes)

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