Maltrail ist für die indikatorbasierte Netzwerküberwachung 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 optionale, vom Betreiber bereitgestellte Trails kombiniert.
- Ein multithreaded Rust-Sensor mit libpcap, optional mit Linux-`PACKET_FANOUT`-Capture-Workern.
- Ein Python-Server, der die Berichtsoberfläche, die Ereignisaufnahme und die HTTP-API bereitstellt.
- Klartext-Custom-Trails und Whitelists, die überprüft und versioniert werden können.
- Heuristiken für Scans, DNS-Erschöpfung, DGA-ähnliche Lookups, verdächtige Downloads, Proxy-Probes,
  verdächtige User-Agent-Werte und damit verbundene Netzwerkaktivitäten.
- Lokale Ereignisprotokollierung, Remote-Maltrail-Protokollierung, CEF über Syslog und Logstash-JSON-Ausgabe.
- Bereitstellungsvalidierung mit `maltrail-sensor -T` und optionale Prometheus-Metriken.

## Inhalt

- [Architektur](#architektur)
- [Berichtsoberfläche](#berichtsoberfläche)
- [Leistung](#leistung)
- [Installation](#installation)
  - [Installationsprogramm](#installationsprogramm)
  - [Build aus dem Quellcode](#build-aus-dem-quellcode)
  - [Systemd](#systemd)
  - [Docker](#docker)
- [Konfiguration](#konfiguration)
- [Trails](#trails)
- [Ereignisse und API](#ereignisse-und-api)
- [Betrieb](#betrieb)
  - [Überwachung](#überwachung)
  - [Ereignisaufbewahrung](#ereignisaufbewahrung)
- [Dokumentation](#dokumentation)
- [Mitwirken](#mitwirken)
- [Projekt](#projekt)
  - [Lizenz](#lizenz)
  - [Betreuer](#betreuer)
  - [Sponsoren](#sponsoren)
  - [Präsentationen und Veröffentlichungen](#präsentationen-und-veröffentlichungen)
  - [Abgeleitete Blacklist](#abgeleitete-blacklist)
  - [Drittanbieter-Integrationen](#drittanbieter-integrationen)
  - [Danksagungen](#danksagungen)

## Architektur

Maltrail besteht aus zwei unabhängigen Prozessen, die auf demselben Host oder auf getrennten Hosts laufen 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 Flow-Hashing von Linux
verteilt den Zustand pro Quelle zwischen den Workern und reduziert daher die Empfindlichkeit einiger
Scan-Heuristiken. Im dokumentierten Test blieben 91 % der Heuristik-Warnungen eines einzelnen Workers 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 dies notwendig 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 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

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

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

Vorgefertigte `x86_64`- und `aarch64`-Sensor-Binaries sind den aktuellen Releases mit SHA-256-Prüfsummen beigefügt. Sie verlinken libpcap statisch und zielen auf glibc 2.28 ab, sodass die C-Bibliothek das Einzige ist, was sie benötigen — nichts zu installieren, gleichermaßen auf RHEL 8+, Debian 10+, Ubuntu 18.04+ und Leap 15.x. Auf musl-basierten Systemen wie Alpine Linux muss aus dem Quellcode gebaut werden.

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

### Systemd

Die mitgelieferten `packaging/systemd/`-Units führen beide Prozesse als
unprivilegierter `maltrail`-Benutzer 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 Service-Verfahren in [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md).

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

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

## Konfiguration

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

Häufig verwendete Sensor-Optionen umfassen:

| Option | Zweck |
| --- | --- |
| `MONITOR_INTERFACE` | Erfassungs-Interface oder -Interfaces; `any` wählt alle unterstützten Interfaces aus |
| `CAPTURE_FILTER` | BPF-Erfassungsfilter |
| `CAPTURE_FANOUT` | Anzahl der Linux-Erfassungs-Sockets; Standard ist eins |
| `CAPTURE_WORKERS` | Erfassungs-Worker, jeweils ein Socket; Standard ist `CAPTURE_FANOUT`, also eins, sofern keines 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` | Trail-Aktualisierungsintervall |
| `STATIC_TRAILS_URL` | Wo der zusammengestellte statische Trail-Satz abgerufen wird; auf eine datierte Version festlegen, um zu steuern, wann neue Inhalte eintreffen |
| `USER_WHITELIST` | Vom Betreiber verwaltete Indikatoren, die keine Warnung auslösen sollen |
| `CUSTOM_TRAILS_DIR` | Vom Betreiber verwaltetes Trail-Verzeichnis |
| `STATIC_TRAILS_DIR` | Optionaler Checkout des Trails-Repository; 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
setzt **nicht** die Worker-Anzahl des Rust-Sensors. Konfigurieren Sie Erfassungs-Worker stattdessen mit `CAPTURE_FANOUT` oder
`CAPTURE_WORKERS`.

Führen Sie nach Änderungen an der Konfiguration den Bereitstellungs-Check aus:```bash
sensor/target/release/maltrail-sensor -T

Richten Sie es stattdessen auf ein bestimmtes `content-YYYYMMDD-HHMM`-Release, um eine Version festzupinnen, damit eine fehlerhafte Veröffentlichung nicht sofort global wirksam wird. Der Satz wird neben `TRAILS_FILE` zwischengespeichert, was einen Offline- oder Air-Gapped-Rebuild ermöglicht; die veröffentlichte `sha256` wird vor dem Download geprüft, sodass eine Bereitstellung, die häufiger aktualisiert als sich der Inhalt ändert, 65 Bytes statt 11 MB überträgt, und ein Payload, der nicht zu seinem 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, sodass eine Bereitstellung nicht stillschweigend von einer Quelle abhängt, die sich inzwischen zurückgezogen hat.

Fügen Sie eigene Indikatoren unter `CUSTOM_TRAILS_DIR` hinzu, und alles, was niemals ein Ereignis auslösen darf, unter `USER_WHITELIST`. Halten Sie beide 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 hierher. In beiden Fällen benötigt ein Indikator eine Klassifizierung und eine Quelle, die jemand überprüfen kann – siehe [Contributing](#contributing).

## Ereignisse und API

Maltrail zeichnet ein durch Leerzeichen getrenntes Ereignis pro Erkennung auf, wobei CSV-Quoting verwendet wird, wenn ein Wert Leerzeichen enthält:```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
}
```
Das Feld `confidence` (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 zustimmendem Feed bis maximal 100, und volle Punktzahl für eigene benutzerdefinierte und statische Einträge des Betreibers. Es wird zum Zeitpunkt der Trail-Aktualisierung aus der Feed-Übereinstimmung in eine `trails.confidence`-Seitendatei neben `trails.csv` berechnet; ein Server, der Trails von einem `UPDATE_SERVER` abruft, hat keine Herkunft zum Bewerten und meldet `null`. Nutzen 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-Abfrage kann ihren gelisteten Elterneintrag abgleichen. 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 Nur-Custom-Abfrage wird als Fehlschlag 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 Folgendes aus:```bash
python3 server.py --detect-test
```
Es führt einen präparierten pcap-Dump emulierten bösartigen Datenverkehrs (Treffer auf eine DNS-Abfrage, eine IP, eine
`IP:port`, einen URL-Pfad und einen `Host`-Header, plus die Heuristiken für SQL-Injection, Traversal, RCE, XSS, Proxy-Probe,
Sinkhole, fehlenden `Host` sowie Port-/Web-/Infektions-Scanning) durch den installierten Sensor aus
und stellt sicher, dass jede erwartete Erkennung ausgelöst wird. Es benötigt kein Root, keine Schnittstelle und keinen eigenen
Trail-Satz. Eine fehlerfreie Installation gibt `20/20 detection(s) fired` aus.

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

| Metrik | Betriebliche Bedeutung |
| --- | --- |
| `maltrail_up == 0` | Kein Capture-Worker läuft |
| Steigendes `maltrail_capture_dropped_total` | Der Capture-Ring verwirft Pakete |
| Steigendes `maltrail_local_log_errors_total` | Ereignisse wurden erzeugt, konnten aber nicht lokal geschrieben werden |
| Steigendes `maltrail_remote_log_errors_total` | Ereignisse konnten nicht an ein entferntes Ziel geliefert werden; mit `DISABLE_LOCAL_LOG_STORAGE` gehen sie verloren |
| `maltrail_trail_generation` schreitet nicht voran | Der aktive Trail-Satz wird nicht aktualisiert |
| `maltrail_log_dir_free_bytes` | Verbleibende Kapazität für die lokale Ereignisspeicherung |
| Steigendes `maltrail_state_saturations_total` | Ein Heuristik-Zustandslimit wurde erreicht |
| Steigendes `maltrail_throttle_evictions_total` | Die Ereignis-Drosselungstabelle hat ihr Limit erreicht, sodass Ereignisse früher als konfiguriert aggregiert werden |

Die Zustandssättigung betrifft die jeweilige Heuristik; die exakte Trail-Übereinstimmung bleibt aktiv.

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

Der kondensierte Beobachtungsspeicher (`USE_CONDENSED_STORAGE`, `meta.sqlite`) unterstützt die Neuheits- und
Retro-Hunt-Ansichten des Servers. Der tagesweise Ereignisprotokoll-Seitenindex (`USE_EVENT_INDEX`,
`LOG_DIR/index/*.sqlite`, etwa doppelt so groß wie die Protokolldateien auf der Festplatte) macht `/counts` exakt und
`/hunt` schnell; er wird inkrementell aus den Protokollen selbst gepflegt und kann mit
`server.py --rebuild-index` neu aufgebaut werden. Die Kompatibilität mit dem eingestellten Sensor ist in
[`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) dokumentiert.

### Ereignisaufbewahrung

Maltrail rotiert oder löscht keine Ereignisprotokolle. Die Betreiber sind für die Festlegung von Aufbewahrung,
Archivierung und Löschung gemäß den Speicheranforderungen und der Unternehmensrichtlinie verantwortlich.

Empfohlene Vorgehensweisen:

- Senden Sie die dauerhafte Ereigniskopie mit `LOG_SERVER`,
  `SYSLOG_SERVER` oder `LOGSTASH_SERVER` an einen entfernten Maltrail-Server oder ein SIEM.
- Warnen Sie bei `maltrail_log_dir_free_bytes` mit ausreichend Puffer für die erwartete Ereignisrate.
- Rotieren, archivieren oder entfernen Sie lokale Tagesprotokolle mit externen Werkzeugen.
- Halten Sie Dateien, die die Berichtsoberfläche benötigt, unkomprimiert in `LOG_DIR`; archivieren Sie komprimierte Dateien
  woanders.

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

## Dokumentation

| Dokument | Inhalt |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md) | Installation, Berechtigungen, Konfiguration und Fehlerbehebung |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ARCHITECTURE.md) | Sensor-Interna und Datenfluss |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) | Bewusste Unterschiede zum eingestellten Python-Sensor |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md) | Messungen, Profile und Testergebnisse |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ROADMAP.md) | Offene Sensor-Arbeiten |
| [`SekuriPy Labs`](https://www.sekuripy.hr/labs/maltrail/) | Technische Notizen, Benchmarks und Berichte |

## Mitwirken

Trail-Ergänzungen, 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
```
It runs formatting, Clippy with warnings denied, and the debug and release test suites. Run the
Python server suite with:```bash
bash tests/run.sh python3
```
## Projekt

### Lizenz

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

### Betreuer

- 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 Veröffentlichungen

- 47. TF-CSIRT-Treffen, 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))

### Abgeleitete Blacklist

Eine reine Domänenliste, die aus den statischen `malware/`-Trails abgeleitet wurde, wird unter
[`maltrail-malware-domains.txt`](https://raw.githubusercontent.com/stamparm/aux/master/maltrail-malware-domains.txt) veröffentlicht.
Sie kann als Eingabe für DNS-Filtersysteme verwendet werden, aber Betreiber sollten sie vor der
Aktivierung der Blockierung prüfen und testen. Threat-Intelligence-Listen können False Positives oder Indikatoren enthalten, die nicht für
jede Umgebung geeignet sind.

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

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