Maltrail ist für indikatorbasiertes Netzwerk-Monitoring konzipiert. Seine heuristischen Erkennungen ergänzen
das Trail-Matching, sind jedoch kein Ersatz für Endpoint-Telemetrie oder ein universelles
Intrusion-Prevention-System.

## Funktionen

- Ein vollständiger Trail-Build, der mehr als 3.000 mitgelieferte statische Dateien, 42 Integrationen öffentlicher Feeds
  und optionale, vom Betreiber bereitgestellte Trails kombiniert.
- Ein multithreaded Rust-Sensor unter Verwendung von libpcap, mit optionalen Linux-`PACKET_FANOUT`-Capture-Workern.
- Ein Python-Server, der die Reporting-Oberfläche, die Event-Aufnahme und die HTTP-API bereitstellt.
- Benutzerdefinierte Trails und Whitelists im Klartextformat, die überprüft und versioniert werden können.
- Heuristiken für Scanning, DNS-Erschöpfung, DGA-ähnliche Lookups, verdächtige Downloads, Proxy-Probes,
  verdächtige User-Agent-Werte und verwandte Netzwerkaktivitäten.
- Lokales Event-Logging, Remote-Maltrail-Logging, CEF über syslog und Logstash-JSON-Ausgabe.
- Deployment-Validierung mit `maltrail-sensor -T` und optionalen Prometheus-Metriken.

## Inhalt

- [Architektur](#architecture)
- [Reporting-Oberfläche](#reporting-interface)
- [Leistung](#performance)
- [Installation](#installation)
  - [Installer](#installer)
  - [Aus dem Quellcode bauen](#building-from-source)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Konfiguration](#configuration)
- [Trails](#trails)
- [Events und API](#events-and-api)
- [Betrieb](#operations)
  - [Monitoring](#monitoring)
  - [Event-Aufbewahrung](#event-retention)
- [Dokumentation](#documentation)
- [Mitwirken](#contributing)
- [Projekt](#project)
  - [Lizenz](#license)
  - [Maintainer](#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 getrennten Hosts ausgeführt werden können:```text
   ┌──────────┐   events (UDP or file)   ┌──────────┐
   │  sensor  │ ───────────────────────► │  server  │ ◄── browser
   └──────────┘                          └──────────┘
    Rust                                  Python
    libpcap + PACKET_FANOUT               reporting UI + API
    trail matching + heuristics

Ein Capture-Worker wird standardmäßig verwendet. Zusätzliche Worker können die Erfassungskapazität erhöhen, aber das Linux-Flow-Hashing verteilt den Zustand pro Quelle auf die Worker und verringert dadurch die Empfindlichkeit einiger Scan-Heuristiken. Im dokumentierten Test blieben 91 % der Heuristik-Warnungen bei einem einzelnen Worker erhalten, 86 % bei zwei Workern, 86 % bei vier und 65 % bei acht. Der exakte Trail-Abgleich blieb unverändert. Erhöhen Sie `CAPTURE_FANOUT` nur, wenn die Capture-Drop-Metriken zeigen, dass dies erforderlich ist.

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

## Installation

### Installer

Der Installer wird auf zwölf Linux-Distributionen verifiziert — Debian, Ubuntu, Fedora, Rocky, AlmaLinux, Arch, openSUSE Leap und Tumbleweed sowie Alpine — plus FreeBSD und macOS, bei jedem Release, wobei das vollständige Ergebnis in [`docs/compat`](https://github.com/stamparm/maltrail/blob/master/docs/compat) aufgezeichnet wird. Raspberry Pi OS und andere 64-Bit-ARM-Systeme verwenden den `aarch64`-Build; 32-Bit-ARM hat keinen vorgefertigten Sensor und muss ihn aus dem Quellcode erstellen.```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh

Allgemeine Installationsoptionen:```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

Dann den Sensor bauen und validieren:```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

Vorkompilierte Sensor-Binärdateien sind den aktuellen Releases mit SHA-256-Prüfsummen beigefügt: Linux `x86_64`
und `aarch64` sowohl gegen glibc als auch musl, macOS auf Apple Silicon und Intel, FreeBSD `amd64` und
Windows `x86_64`.

Die glibc-Builds linken libpcap statisch und zielen auf glibc 2.28 ab, sodass die C-Bibliothek das Einzige ist, was sie
benötigen — nichts zu installieren, auf RHEL 8+, Debian 10+, Ubuntu 18.04+ und Leap 15.x gleichermaßen. Die musl-
Builds sind vollständig statisch, sodass Alpine überhaupt nichts benötigt. Der Windows-Build ist 64-Bit und benötigt Windows 10 oder später sowie
[Npcap](https://npcap.com), das installiert sein muss, bevor er startet — `wpcap.dll` ist eine Ladezeit-Abhängigkeit,
sodass der Loader ohne sie die ausführbare Datei verweigert, anstatt bei der Erfassung fehlzuschlagen. Das Archiv sagt das
ebenfalls.

Binärdateien aus **3.1.1 und früher** taten das nicht: Sie linkten libpcap dynamisch und fragten sie unter
dem Namen an, den ihr AlmaLinux-Build-Host verwendet. Debian und Ubuntu liefern die identische Bibliothek unter dem
älteren Namen `libpcap.so.0.8`, sodass diese Binärdateien stoppen, bevor sie starten —```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file

### Systemd

Die mitgelieferten Units unter `packaging/systemd/` führen beide Prozesse als
unprivilegierten 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. Bei einer bestehenden Quellinstallation folgen Sie
dem manuellen Dienstverfahren in [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md).

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

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

## Konfiguration

Maltrail liest `maltrail.conf`, das separate `[Sensor]`- und `[Server]`-Einstellungen enthält. Der
Installer legt die verwaltete Konfiguration unter `/etc/maltrail.conf` ab.

Häufig verwendete Sensor-Optionen sind:

| Option | Zweck |
| --- | --- |
| `MONITOR_INTERFACE` | Capture-Schnittstelle oder -Schnittstellen; `any` wählt alle unterstützten Schnittstellen aus |
| `CAPTURE_FILTER` | BPF-Capture-Filter |
| `CAPTURE_FANOUT` | Anzahl der Linux-Capture-Sockets; standardmäßig eins |
| `CAPTURE_WORKERS` | Capture-Worker, jeweils ein Socket; standardmäßig `CAPTURE_FANOUT`, also eins, sofern nicht eine der beiden Optionen gesetzt ist |
| `LOG_DIR` | Lokales Ereignisprotokoll-Verzeichnis |
| `TRAILS_FILE` | Generierte Trail-Datenbank |
| `LOG_SERVER` | Remote-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` | Aktualisierungsintervall für Trails |
| `STATIC_TRAILS_URL` | Quelle, von der das zusammengestellte statische Trail-Set abgerufen wird; binden Sie sie an ein datiertes Release, um zu steuern, wann neue Inhalte eintreffen |
| `USER_WHITELIST` | Vom Betreiber verwaltete Indikatoren, die keinen Alarm auslösen sollen |
| `CUSTOM_TRAILS_DIR` | Vom Betreiber verwaltetes Trail-Verzeichnis |
| `STATIC_TRAILS_DIR` | Optionaler Checkout des Trail-Repositories; wird nur verwendet, um die Quellenangabe eines Trails in der UI anzuzeigen |

`PROCESS_COUNT` gilt für den ausgemusterten Python-Sensor und für die Legacy-Ereignisprotokoll-Drosselung; es
legt **nicht** die Worker-Anzahl des Rust-Sensors fest. Konfigurieren Sie Capture-Worker stattdessen mit `CAPTURE_FANOUT` oder
`CAPTURE_WORKERS`.

Führen Sie die Deployment-Prüfung nach Änderungen an der Konfiguration aus:```bash
sensor/target/release/maltrail-sensor -T

Richte es stattdessen auf ein bestimmtes `content-YYYYMMDD-HHMM`-Release aus, um eine Version festzuzurren, damit eine fehlerhafte Veröffentlichung nicht sofort global wird. Das Set wird neben `TRAILS_FILE` zwischengespeichert, was einen Offline- oder Air-Gapped-Rebuild ermöglicht; die veröffentlichte `sha256` wird vor dem Herunterladen geprüft, sodass ein Deployment, das häufiger aktualisiert als sich der Inhalt ändert, 65 Bytes statt 11 MB überträgt, und eine Payload, die nicht zu ihrem Digest passt, zugunsten des Caches abgelehnt wird.

`update_trails()` veröffentlicht eine neue `TRAILS_FILE` atomar und erst nach einem erfolgreichen Build. Feeds, die nichts zurückgeben, werden namentlich gemeldet, damit ein Deployment nicht stillschweigend von einer Quelle abhängt, die still und leise eingestellt wurde.

Füge deine eigenen Indikatoren unter `CUSTOM_TRAILS_DIR` hinzu und alles, was niemals ein Event auslösen darf, unter `USER_WHITELIST`. Halte beides außerhalb des Installationsverzeichnisses, damit ein Upgrade sie nicht überschreiben kann.

Statische Trail-Beiträge gehen an [stamparm/trails](https://github.com/stamparm/trails); neue Feeds gehören hierher. In beiden Fällen benötigt ein Indikator eine Klassifizierung und eine Quelle, die jemand überprüfen kann — siehe [Contributing](#contributing).

## Events und API

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

| `-s` | `--server` | Server-Modus aktivieren |
| `-c` | `--client` | Client-Modus aktivieren |
| `-p` | `--port` | Port-Nummer angeben |
| `-h` | `--help` | Hilfe-Nachricht anzeigen |
| `-v` | `--version` | Versionsinformationen anzeigen |

### Beispiele

```bash
# Server-Modus starten
./tool -s -p 8080

# Client-Modus starten
./tool -c -p 8080

Das `confidence`-Feld (0-100 oder `null`, wenn nicht verfügbar) gibt an, wie stark die Quellen den
Eintrag stützen: 40 für einen einzelnen Feed, +15 pro zusätzlichem, unabhängig übereinstimmendem Feed bis maximal 100, und
volle Punktzahl für die eigenen benutzerdefinierten und statischen Einträge des Betreibers. Es wird zum Zeitpunkt der Trail-Aktualisierung aus
der Feed-Übereinstimmung in eine `trails.confidence`-Sidecar-Datei neben `trails.csv` berechnet; ein Server, der Trails
von einem `UPDATE_SERVER` bezieht, hat keine Herkunftsdaten zum Bewerten und meldet `null`. Verwenden Sie es zur Priorisierung
der Triage – ein Eintrag aus einem einzelnen Feed mit 40 verdient einen zweiten Blick, bevor er eine Firewall-Regel erhält.

Eine Subdomain-Suche kann auf ihr gelistetes Parent-Verzeichnis passen. URL-Suchen prüfen `host/path`, bevor sie den
Host allein prüfen. Der Server liest die speichergemappte 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
Suche nur nach benutzerdefinierten Trails wird als Fehltreffer gemeldet. Ereignisdaten bleiben authentifiziert.

## Betrieb

### Überwachung

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

Um zu bestätigen, dass die Erkennung selbst funktioniert – nicht nur, dass die Prozesse starten –, führen Sie aus:```bash
python3 server.py --detect-test

`--keep` spielt außerdem `sensor/tests/corpus/` in dasselbe Log ein und gibt aus, hinter welchen der Formen, die das Dashboard anders darstellt, ein Event steht, sodass ein fehlendes Icon, eine fehlende Farbe oder ein fehlendes Glyph sichtbar wird statt angenommen zu werden. Zeitstempel werden so verschoben, dass der neueste Tag heute ist. Eine Sensor-Binary ist erforderlich (`cargo build --release --manifest-path sensor/Cargo.toml`).

Die Daten der öffentlichen Demo werden aus einem solchen Lauf neu generiert:```bash
python3 sensor/tools/gen_demo_js.py --from DIR/logs   # tops up html/js/demo.js

Es führt Formatierung, Clippy mit verweigerten Warnungen sowie die Debug- und Release-Testsuiten aus. Führe die Python-Server-Suite aus mit:```bash
bash tests/run.sh python3

Es kompiliert den Sensor mit mingw-w64 cross, extrahiert Npcaps Userspace-Bibliothek aus dessen Installer
(ein NSIS-Archiv, sodass nichts installiert wird) und führt das Ergebnis unter Wine aus — die gesamte Unit-Suite,
`-T` gegen die mitgelieferte Konfiguration, das pcap-Korpus Byte für Byte gegen die native
Binärdatei verglichen, und der Server, der unter einem Windows-Python auf `/ping` antwortet. Live-Capture ist das Einzige, was es nicht abdecken kann; das benötigt Npcaps Kernel-Treiber und eine echte Windows-Maschine. Voraussetzungen sind
`gcc-mingw-w64-x86-64`, `wine` und `p7zip-full`.

## Projekt

### Lizenz

**TL;DR:** Maltrail ist MIT-lizenziert, aber das Maltrail Trails-Dataset hat separate Bedingungen. Unabhängige IOC-Lookup/Referenz ist in Ordnung; die systematische Nutzung von Trails als Intelligence-Quelle in einem kommerziellen Produkt oder Dienst erfordert Erlaubnis/Lizenzierung.

Maltrail wird unter der MIT-Lizenz vertrieben. Siehe [`LICENSE`](https://github.com/stamparm/maltrail/blob/master/LICENSE).

Das ist die Engine. Das statische Trail-Set ist separate Arbeit unter separaten Bedingungen: kostenlos für interne
defensive Nutzung, Forschung und Lehre, aber ein kommerzielles Produkt, ein Dienst, ein MSSP- oder MDR-Angebot oder ein
weiterverteilter Feed benötigt eine Lizenz. Eine MIT-Engine macht den Inhalt nicht frei verkäuflich — siehe
[`LICENSE.md`](https://github.com/stamparm/trails/blob/main/LICENSE.md) in
[stamparm/trails](https://github.com/stamparm/trails), bevor du es in etwas auslieferst, für das du Geld
verlangst.

### Maintainer

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

### Sponsoren

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

### Präsentationen und Publikationen

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

### Integrationen von Drittanbietern

- [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) (nur Trails)
- [MalwareWorld](https://www.malwareworld.com/) (nur Trails)
- [oisd domain blocklist](https://oisd.nl/?p=inc) (nur Trails)
- [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json) (nur Trails)
- [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md) (nur Trails)
- [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables) (nur Trails)
- [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876) (nur Trails)
- [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json) (nur Trails)
- [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license) (nur Trails)
- [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed) (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)