Maltrail

Maltrail ist ein System zur Erkennung von Netzwerkverkehr, das Kommunikation mit bekannter schädlicher Infrastruktur identifiziert und ausgewählte Verkehrsanomalien meldet. Es gleicht Domains, URLs, IP-Adressen, IP:port-Paare und User-Agent-Werte, die im Netzwerk beobachtet werden, mit einer Reihe von Indikatoren ab, die als trails bezeichnet werden.

Eine Erkennung wird als einzelnes Ereignis aufgezeichnet, das die Quelle, das Ziel, das Protokoll, den passenden Trail, die Klassifizierung und die Trail-Quelle enthält:```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 ist für indikatorbasiertes Netzwerk-Monitoring konzipiert. Seine heuristischen Erkennungen ergänzen
das Trail-Matching, ersetzen jedoch keine Endpunkt-Telemetrie oder ein allgemeines Intrusion-Prevention-System.

## Funktionen

- Ein vollständiger Trail-Aufbau, der mehr als 3.000 gebündelte statische Dateien, 42 öffentliche Feed-Integrationen
  und optional vom Betreiber bereitgestellte Trails kombiniert.
- Ein multithreaded Rust-Sensor, der libpcap verwendet, mit optionalen Linux-`PACKET_FANOUT`-Capture-Workern.
- Ein Python-Server, der die Berichtsoberfläche, die Ereignisaufnahme und die HTTP-API bereitstellt.
- Klartext-basierte benutzerdefinierte Trails und Whitelists, die überprüft und versioniert werden können.
- Heuristiken für Scans, DNS-Erschöpfung, DGA-artige Lookups, verdächtige Downloads, Proxy-Probes,
  verdächtige User-Agent-Werte und verwandte Netzwerkaktivitäten.
- Lokale Ereignisprotokollierung, Remote-Maltrail-Protokollierung, CEF über Syslog und Logstash-JSON-Ausgabe.
- Bereitstellungsvalidierung mit `maltrail-sensor -T` und optionalen Prometheus-Metriken.

## Inhalt

- [Architektur](#architecture)
- [Leistung](#performance)
- [Installation](#installation)
  - [Installationsprogramm](#installer)
  - [Aus dem Quellcode erstellen](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Konfiguration](#configuration)
- [Trails](#trails)
- [Ereignisse und API](#events-and-api)
- [Betrieb](#operations)
  - [Überwachung](#monitoring)
  - [Ereignisaufbewahrung](#event-retention)
- [Dokumentation](#documentation)
- [Mitwirken](#contributing)
- [Projekt](#project)
  - [Lizenz](#license)
  - [Betreuer](#maintainers)
  - [Sponsoren](#sponsors)
  - [Präsentationen und Veröffentlichungen](#presentations-and-publications)
  - [Abgeleitete Blacklist](#derived-blacklist)
  - [Integrationen von Drittanbietern](#third-party-integrations)
  - [Danksagungen](#acknowledgements)

## Architektur

Maltrail besteht aus zwei unabhängigen Prozessen, die auf demselben Host oder auf separaten Hosts laufen können:```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

Der Sensor erfasst Datenverkehr, führt Trail-Abgleich und heuristische Analyse durch und erzeugt Ereignisse. Er kann Ereignisse lokal speichern (LOG_DIR), an einen entfernten Maltrail-Server (LOG_SERVER) senden oder beides tun. Er kann außerdem CEF über Syslog (SYSLOG_SERVER) und JSON an Logstash (LOGSTASH_SERVER) ausgeben.

Der Server empfängt und speichert entfernte Ereignisse, stellt lokal verfügbare Ereignisprotokolle bereit und bietet die Weboberfläche und API an.

Leistung

Die Leistung hängt vom Prozessor, der Verkehrszusammensetzung, der Größe des Trail-Sets, dem Erfassungstreiber und der Netzwerkschnittstelle ab. Die folgenden Zahlen messen den Paketverarbeitungspfad des Sensors isoliert; es handelt sich nicht um End-to-End-Messungen bei Live-Erfassung.

Repräsentative Messungen auf einem AMD Ryzen 7 PRO 4750U mit aktivierten Heuristiken und einem 1,5 Millionen Zeilen umfassenden Trail-Set:

Offline-Vergleichsläufe mit demselben generierten Capture, derselben Konfiguration und demselben Trail-Set ergaben auf den getesteten Systemen 14–37× geringere Kosten pro Paket im stationären Zustand als der ausgemusterte Python-Sensor. Das Vergleichstool gibt die Gesamtprozesszeit separat an, da das Laden der Trails kurze Replays dominiert. Es gibt außerdem Ereignisanzahlen aus; die Funktionsparität wird unabhängig durch das Paritätskorpus getestet.

Führen Sie den Vergleich auf dem Zielsystem mit:```bash python3 sensor/tools/bench_compare.py --packets 300000
--trails ~/.maltrail/trails.csv --repeat 3

Standardmäßig wird ein Capture-Worker verwendet. Zusätzliche Worker können die Erfassungskapazität erhöhen, aber das Linux-Flow-Hashing verteilt den Pro-Quellen-Status auf die Worker und verringert dadurch die Empfindlichkeit einiger Scan-Heuristiken. Im dokumentierten Test blieben 91 % der Einzel-Worker-Heuristikwarnungen bei zwei Workern erhalten, 86 % bei vier und 65 % bei acht. Das exakte Trail-Matching blieb unverändert. Erhöhen Sie `CAPTURE_FANOUT` nur, wenn die Capture-Drop-Metriken zeigen, dass es notwendig ist.

Benchmark-Methodik, Hardware-Ergebnisse, Profiler-Ausgaben, Speichermessungen und Live-Fanout-Prüfungen sind in [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/REPORT.md) dokumentiert.

## Installation

### Installer

Der Installer unterstützt Debian, Ubuntu, Raspberry Pi OS, RHEL, Fedora und openSUSE:```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

Es installiert Abhängigkeiten, erstellt einen verwalteten Checkout unter /opt/maltrail, überprüft die Prüfsumme des vorgebauten Sensors, erstellt ein unprivilegiertes maltrail-Konto, installiert systemd-Units, bereitet die Log- und Zustandsverzeichnisse vor und startet den Sensor und den Server. Ein erneutes Ausführen des Installationsprogramms aktualisiert den verwalteten Checkout.

Überprüfen Sie das Skript, bevor Sie es mit erweiterten Rechten ausführen. Von einem vorhandenen Checkout aus zeigt der Probelauf die Befehle an, ohne das System zu ändern:```bash sh install.sh --dry-run

Gängige Installer-Optionen:```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

Das Dashboard ist nach der Installation unter http://127.0.0.1:8338 verfügbar. Beachten Sie, dass die mitgelieferte HTTP_ADDRESS 0.0.0.0 ist, sodass es auf jeder Schnittstelle erreichbar ist, nicht nur auf Loopback — und die Standard-Anmeldedaten sind admin / changeme!. Ändern Sie USERS und setzen Sie HTTP_ADDRESS auf 127.0.0.1 (oder setzen Sie den Server hinter einen Reverse-Proxy mit TLS), bevor der Host in einem nicht vertrauenswürdigen Netzwerk betrieben wird.

Der erste Trail-Build kann mehrere Minuten dauern. Der Sensor erkennt keine Trail-Treffer, bis ein gültiger Trail-Satz verfügbar ist. Die systemd-Unit führt vor dem Start die -T-Validierung des Sensors aus, sodass fehlende Berechtigungen, ein nicht beschreibbares Protokollverzeichnis oder ein ungültiger Trail-Satz dazu führen, dass der Start sichtbar fehlschlägt.

Der Installer-Testrahmen deckt Ubuntu-, Debian-, Fedora-, openSUSE- und Alpine-Container ab. Alpine verwendet musl und nutzt nicht das vorgefertigte glibc-Sensorbinary; dort muss der Sensor aus dem Quellcode erstellt werden.

Erstellen aus dem Quellcode

Der Sensor erfordert Rust 1.74 oder neuer, libpcap-Entwicklungsheader und die Capability-Werkzeuge des Systems. Der Server und der Trail-Updater erfordern Python 3.6 oder neuer.

Installieren Sie die Distributionspakete:```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

Dann baue und validiere den 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

Starten Sie den Server in einem anderen Terminal oder auf einem anderen Host:```bash python3 server.py

Vorgefertigte `x86_64`- und `aarch64`-Sensor-Binärdateien sind den aktuellen Releases mit SHA-256
Checksummen beigefügt. Sie zielen auf glibc 2.28 ab und benötigen libpcap zur Laufzeit. Auf musl-basierten Systemen wie
Alpine Linux aus dem Quellcode erstellen.

Der ausgemusterte Python-Sensor wird nur von Vergleichs- und Paritätstools verwendet. Diese Werkzeuge benötigen zusätzlich
`pcapy-ng` und die Python-Entwicklungsheader, wie in
[`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md) beschrieben.

### Systemd

Die mitgelieferten `maltrail-server.service`- und `maltrail-sensor.service`-Units führen beide Prozesse als
unprivilegierter Benutzer `maltrail` aus. Systemd erstellt `/var/log/maltrail` und `/var/lib/maltrail`, schränkt den
Dateisystemzugriff ein und gewährt dem Sensor `CAP_NET_RAW` und `CAP_NET_ADMIN`.

Der Installer konfiguriert diese Units automatisch. Für eine bestehende Quellinstallation folgen Sie
dem manuellen Verfahren für den Dienst in [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md).

Überprüfen Sie den Dienststatus und die Protokolle mit:```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

Docker

Starten Sie die mitgelieferte Compose-Bereitstellung mit:```bash docker compose -f docker/docker-compose.yml up -d

Container-Konfiguration, Speicher, Berechtigungen und Health-Checks sind in
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/HEAD/docker/README.md) dokumentiert.

## Konfiguration

Maltrail liest `maltrail.conf`, das separate Einstellungen für `[Sensor]` und `[Server]` enthält. Das
Installationsprogramm legt die verwaltete Konfiguration unter `/etc/maltrail.conf` ab.

Häufig verwendete Sensoroptionen umfassen:

| Option | Zweck |
| --- | --- |
| `MONITOR_INTERFACE` | Erfassungsschnittstelle bzw. -schnittstellen; `any` wählt alle unterstützten Schnittstellen aus |
| `CAPTURE_FILTER` | BPF-Erfassungsfilter |
| `CAPTURE_FANOUT` | Anzahl der Linux-Erfassungs-Sockets; Standard ist eins |
| `LOG_DIR` | Lokales Verzeichnis für Ereignisprotokolle |
| `TRAILS_FILE` | Generierte Trail-Datenbank |
| `LOG_SERVER` | Remoter Maltrail-Ereignisserver |
| `SYSLOG_SERVER` | CEF-Syslog-Ziel oder -Ziele |
| `LOGSTASH_SERVER` | Logstash-JSON-Ziel oder -Ziele |
| `STATS_ADDRESS` | Prometheus-Metriken-Listener; deaktiviert, sofern nicht konfiguriert |
| `UPDATE_PERIOD` | Trail-Aktualisierungsintervall |
| `USER_WHITELIST` | Vom Betreiber verwaltete Indikatoren, die keinen Alarm auslösen sollen |
| `CUSTOM_TRAILS_DIR` | Vom Betreiber verwaltetes Trail-Verzeichnis |

`PROCESS_COUNT` gilt für den zurückgezogenen Python-Sensor. Konfigurieren Sie die Erfassungs-Worker
des Rust-Sensors stattdessen mit `CAPTURE_FANOUT`.

Führen Sie nach einer Änderung der Konfiguration den Deployment-Check aus:```bash
sensor/target/release/maltrail-sensor -T

Die Prüfung validiert die Konfiguration, Spuren, Whitelist-Einträge, den Erfassungsfilter, Berechtigungen und die Logspeicherung, den Update-Support und die Worker-Einstellungen. Eine erfolgreiche Prüfung enthält positive Spuren- und Whitelist-Zählwerte, anstatt nur zu bestätigen, dass Dateien vorhanden sind.

Spuren

Spuren werden als Klartext-Indikatoren gespeichert:```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

Fügen Sie lokale Indikatoren unter `CUSTOM_TRAILS_DIR` hinzu. Fügen Sie Indikatoren, die niemals Warnungen erzeugen sollen,
zu `USER_WHITELIST` hinzu. Das Aufbewahren von benutzerdefinierten Daten außerhalb des verwalteten Checkouts verhindert, dass Upgrades
sie überschreiben.

Der Updater erstellt `TRAILS_FILE` aus aktivierten Feeds, gebündelten statischen Trails und benutzerdefinierten Trails neu. Eine
neue Datei wird nur nach einem erfolgreichen Build atomar veröffentlicht. Leere oder fehlgeschlagene Feeds werden gemeldet,
sodass eine laufende Bereitstellung nicht stillschweigend von veralteten oder entfernten Quellen abhängt.

Trail-Beiträge sollten den Indikator, die Klassifizierung und eine verifizierbare Quelle enthalten. Siehe
[Mitwirken](#contributing), bevor Sie einen Pull-Request einreichen.

## Ereignisse und API

Maltrail zeichnet ein durch Leerzeichen getrenntes Ereignis pro Erkennung auf, wobei CSV-Zitierung verwendet wird, wenn ein Wert
Leerzeichen enthält:```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

The type-Feld identifiziert, was übereinstimmt, einschließlich DNS, IP, IPORT, URL, PATH, HTTP, UA, PORT und CERT. Das info-Feld enthält die Trail-Klassifizierung, und reference identifiziert die statische Liste, den Feed, die benutzerdefinierte Quelle oder die Heuristik, die sie erzeugt hat.

Indikatorabfrage

Verwende /check, um eine Domain, IP-Adresse oder URL abzufragen:```bash curl 'http://127.0.0.1:8338/check?q=www.sub.evil.example'

Hinweis: Die [UPX](https://upx.github.io/)-gepackten Ausgabebinärdateien werden automatisch von AV-Lösungen entpackt. Stellen Sie sicher, dass dies kein Problem für Ihren Anwendungsfall darstellt.```json
{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)"
}

Eine Subdomain-Abfrage kann mit ihrem gelisteten Elternteil übereinstimmen. URL-Abfragen prüfen host/path, bevor sie den Host allein prüfen. Der Server liest die speicherzugeordnete Trail-Datenbank und beobachtet Trail-Aktualisierungen ohne Neustart.

Öffentliche statische und Feed-Trails sind ohne Authentifizierung verfügbar, konsistent mit dem /trails-Endpunkt, der von Remote-Sensoren verwendet wird. Benutzerdefinierte Trails erfordern eine autorisierte Sitzung; eine nicht autorisierte Abfrage nur benutzerdefinierter Trails wird als nicht gefunden gemeldet. Ereignisdaten bleiben authentifiziert.

Betrieb

Überwachung

Verwenden Sie maltrail-sensor -T als Bereitstellungs- und Konfigurations-Gate. Die mitgelieferte systemd-Unit führt es als ExecStartPre aus.

Wenn STATS_ADDRESS konfiguriert ist, überwachen Sie mindestens diese Prometheus-Metriken:

Die Zustandssättigung wirkt sich auf die entsprechende Heuristik aus; der exakte Trail-Abgleich bleibt aktiv.

Senden Sie SIGHUP oder verwenden Sie systemctl reload maltrail-sensor, um ein Trail-Reload anzufordern. Von einem anderen Prozess aktualisierte Trail-Dateien werden automatisch erkannt und ohne Neustart des Sensors an die Worker veröffentlicht.

Der kondensierte Observable-Speicher (USE_CONDENSED_STORAGE, meta.sqlite) unterstützt die Novelty- und Retro-Hunt-Ansichten des Servers. Die Kompatibilität mit dem eingestellten Sensor ist in sensor/docs/COMPATIBILITY.md dokumentiert.

Ereignisaufbewahrung

Maltrail rotiert oder löscht keine Ereignisprotokolle. Betreiber sind dafür verantwortlich, Aufbewahrung, Archivierung und Löschung gemäß den Speicheranforderungen und der organisatorischen Richtlinie festzulegen.

Empfohlene Vorgehensweisen:

• Senden Sie die dauerhafte Ereigniskopie an einen entfernten Maltrail-Server oder ein SIEM mit LOG_SERVER, SYSLOG_SERVER oder LOGSTASH_SERVER.
• Richten Sie Alarme für maltrail_log_dir_free_bytes mit ausreichend Spielraum für die erwartete Ereignisrate ein.
• Rotieren, archivieren oder entfernen Sie lokale Tagesprotokolle mit externen Werkzeugen.
• Belassen Sie die von der Berichtsoberfläche benötigten Dateien unkomprimiert in LOG_DIR; archivieren Sie komprimierte Dateien an anderer Stelle.

Wenn das Protokoll-Dateisystem voll ist, kann der Sensor keine Ereignisse anhängen. Ereignisprotokolle können außerdem IP-Adressen und Domains enthalten, die in einigen Rechtsräumen als personenbezogene Daten reguliert sind; die Aufbewahrungsrichtlinie sollte die geltenden Anforderungen berücksichtigen.

Dokumentation

Mitwirken

Trail-Erweiterungen, Feed-Pflege, Fehlerberichte, Dokumentation und Sensor-Verbesserungen sind willkommen. Trail-Einreichungen sollten eine zuverlässige Quelle enthalten und die engste angemessene Klassifizierung verwenden.

Führen Sie vor dem Einreichen von Code die relevanten Prüfungen aus. Das vollständige Sensor-Gate ist:```bash bash sensor/tools/check.sh

Es führt Formatierung, Clippy mit Warnungen als Fehler, Debug- und Release-Tests sowie Parity-Replay gegen den ausgemusterten Python-Sensor aus. Führen Sie die Python-Server-Suite aus mit:```bash
bash tests/run.sh python3

Projekt

Lizenz

Maltrail wird unter der MIT-Lizenz vertrieben. Siehe LICENSE.

Betreuer

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

Sponsoren

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

Präsentationen und Veröffentlichungen

• 47. TF-CSIRT-Treffen, Prag, 2016 (Folien)
• Erkennen Sie Angriffe auf Ihr Netzwerk mit Maltrail, Linux Magazine, 2022 (Artikel)
• Beste Cyber-Threat-Intelligence-Feeds, Silent Push, 2022 (Rezension)
• Forschung zu einem System zur Erkennung von bösartigem Netzwerkverkehr auf Basis von Maltrail, Nanotechnology Perceptions, 2024 (Paper)

Abgeleitete Blacklist

Eine reine Domänenliste, die aus trails/static/malware abgeleitet wird, ist unter maltrail-malware-domains.txt veröffentlicht. Sie kann als Eingabe für DNS-Filtersysteme verwendet werden, aber Betreiber sollten sie überprüfen und testen, bevor sie das Blockieren aktivieren. Threat-Intelligence-Listen können Fehlalarme oder Indikatoren enthalten, die nicht für jede Umgebung geeignet sind.

Drittanbieter-Integrationen

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

Danksagungen

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