maltrail - Malicious traffic detection system

项目说明

!Maltrail

![X]()

Maltrail

Maltrail is a network traffic detection system that identifies communication with known malicious
infrastructure and reports selected traffic anomalies. It matches domains, URLs, IP addresses,
IP:port pairs, and User-Agent observed on the network against a set of indicators called
_trails_.

A detection is recorded as a single event containing the source, destination, protocol, matched
trail, classification, and trail source:

Maltrail is designed for indicator-based network monitoring. Its heuristic detections supplement
trail matching, but it is not a replacement for endpoint telemetry or a general-purpose intrusion
pre system.

Features

A full trail build combining more than 3,000 bundled static files, 42 public-feed integrations,

and optional operator-supplied trails.

A multithreaded Rust sensor using libpcap, with optional Linux PACKET_FANOUT capture workers.

A Python ser the reporting interface, event intake, and HTTP API.

Plain-text custom trails and whitelists that can be re and .

Heuristics for scanning, DNS exhaustion, DGA-like lookups, suspicious downloads, proxy probes,

suspicious User-Agent , and related network activity.

Local event logging, remote Maltrail logging, CEF o, and Logstash JSON output.

Deployment with maltrail-sensor -T and optional Prometheus metrics.

Contents

Architecture

Reporting interface

Performance

Installation

- Installer
- Building from source
- Systemd
- Docker

Configuration

Trails

Events and API

Operations

- Monitoring
- Event retention

Documentation

Contributing

Project

- License
- Maintainers
- Sponsors
- Presentations and publications
- Deri
- Third-party integrations
- Acknowledgements

Architecture

Maltrail has two independently deployable processes that can run on the same host or on separate
hosts: the sensor detects suspicious traffic, while the server stores and exposes events for
reporting and API access.

The sensor captures network traffic, performs trail matching and heuristic analysis, and produces
events. It can write events locally to LOG_DIR, send them to a remote Maltrail ser
LOG_SERVER, or do both. It can also emit CEF o with SYSLOG_SERVER and JSON to
Logstash with LOGSTASH_SERVER.

The ser remote events, stores them in the event logs, reads locally a daily logs,
and provides the HTTP API and browser-based reporting interface. The sensor does not depend on the
reporting interface and can be deployed independently when events are forwarded to another system.

Reporting interface

Maltrail includes a browser-based reporting interface for exploring detected traffic, with live
updates, field-aware search, retro hunting, geographic views, triage, sensor status, sa and
export.

!Maltrail reporting interface

The interface is served by server.py at HTTP_ADDRESS:HTTP_PORT. It is plain Ja with a
single third-party runtime dependency (PapaParse, for CS) and no build step. One day is
at a time, selected with a date picker that also acts as an e grid over the
a daily logs. Events are streamed from /events and aggregated in the browser into
*threats* — one row per distinct (source, trail) — shown in a sortable grid with a detail panel.

| Feature | Notes |
| --- | --- |
| Live mode | Appended events arrive o Events (/live) and are merged into the current view. When SSE is una, or the stream cannot serve the session, the interface falls back to polling byte ranges of the daily log. New high-se threats can raise desktop and audible alerts; both can be muted |
| Search | Field-aware queries support src:, dst:, port:, proto:, type:, trail:, info:, family:, tag:, uid:, sev:, dir: and status: selectors, plus exclusions, wildcards, CIDR matching and numeric comparisons. Acti appear as removable chips |
| Retro hunt | /hunt searches all retained daily logs for one indicator rather than only the selected day. Searches are bounded by configurable limits; an optional per-day sidecar index accelerates the sweep and makes /counts exact |
| World map | /geo shows per-country event density for the selected day using the external endpoint of each event. Unattributable events remain unmapped rather than being guessed. HOME_LAT / HOME_LON can be set to draw origin arcs |
| Triage | Per-threat status (new / in / resolved / false positive), free-text notes, tags and hiding. Whitelist rules and OSINT pivots are a from the row context menu |
| Sensor status | /sensors shows which sensors are reporting, the each runs and how long ago it last checked in |
| Sa | Named filter presets |
| Export | The current filtered view as CSV, JSON, or defanged indicators |
| Appearance | Dark and light themes, with discrete text-size steps |

Search terms separated by spaces are combined as AND. Prefix a term with - to exclude it, use
* for wildcards, use CIDR notation such as src:10.0.0.0/8, and use numeric ranges or comparisons
such as port:>1024 and count:>=100. family:interlock also includes interlock-1 and
interlock-2, the shards in which that feed dump arrives.

Retro hunts are bounded by a day limit, a wall-clock budget and a sample cap. If the time budget cuts
a day short, that day is reported separately rather than counted as a completed day. With
USE_E enabled, the per-day sidecar index under LOG_DIR/index/ lets the hunt skip
non-matching lines and provides exact /counts results.

Sensor li is tracked separately from event activity: a failed sensor and a healthy sensor on a
quiet link can both produce no events. Sensors therefore announce themselves over the LOG_SERVER
channel every HEARTBEAT_PERIOD seconds. When LOG_SER is configured, heartbeats are
signed in the same way as events.

Triage state, sa, tags and appearance settings are stored in the browser
(localStorage), not on the server. They are therefore per-browser and per-origin and are not shared
between analysts.

Sessions restricted with a network filter see only events from their own networks. The same
restriction also applies to the counts, map and blacklist endpoints, not only to the event list.

Country and ASN enrichment for indi addresses is looked up at stat.ripe.net by the
server, cached there, and exposed to the interface through Maltrail's own /ripe endpoint. The
browser talks to nothing but Maltrail. Set DISABLE_RIPE_LOOKUPS to disable outbound lookups
entirely. Without RIPE lookups — including on hosts without internet access — flags fall back to the
local RIR table and the rest of the interface continues to work offline.

Performance

Performance depends on processor, traffic composition, trail-set size, capture driver, and network
interface. The figures below measure the sensor's packet-processing path in isolation; they are not
end-to-end li measurements.

Representati on an AMD Ryzen 7 PRO 4750U with heuristics enabled and a 1.5
million-row trail set:

| Traffic | Time per packet |
| --- | ---: |
| ICMP echo, 58 bytes | 101 ns |
| TCP SYN, 70 bytes | 302 ns |
| Bulk TLS, 1,473 bytes | 402 ns |
| DNS query with a warm cache, 93 bytes | 452 ns |
| Mixed traffic, 866-byte a | 552 ns |
| HTTP request, 169 bytes | 602 ns |
| DNS query with a unique name, 93 bytes | 1,102 ns |

Offline comparison runs using the same generated capture, configuration, and trail set measured a
14–37× lower steady-state per-packet cost than the retired Python sensor across the tested systems.
Those figures separate whole-process time from steady state, because trail loading dominates a
short replay. Detection itself is asserted separately, by the 42-case corpus in
sensor/tests/replay.rs.

Measure it on the target system with:

One capture worker is used by default. Additional workers can increase capture capacity, but Linux
flow hashing divides per-source state between workers and therefore reduces the sensitivity of some
scan heuristics. In the documented test, 91% of single-worker heuristic alerts remained with two
workers, 86% with four, and 65% with eight. Exact trail matching was unchanged. Increase
CAPTURE_FANOUT only when capture-drop metrics show that it is necessary.

Benchmark methodology, hardware results, profiler output, memory measurements, and li
checks are documented in sensor/docs/REPORT.md.

Installation

Installer

The installer is on twel distributions — Debian, Ubuntu, Fedora, Rocky, AlmaLinux,
Arch, openSUSE Leap and Tumbleweed, and Alpine — plus FreeBSD, NetBSD, OpenBSD and macOS, on every
release, with the full result recorded in docs/compat. Raspberry Pi OS and other
64-bit ARM systems use the aarch64 build; 32-bit ARM has no prebuilt sensor and must build it
from source.

It installs dependencies, creates a managed checkout under /opt/maltrail, the checksum
of the prebuilt sensor, creates an unpri maltrail account, installs systemd units, prepares
the log and state directories, and starts the sensor and server. Re-running the installer upgrades
the managed checkout.

Review the script before running it with elevated pri. From an existing checkout, the dry
run shows the commands without changing the system:

Common installer options:

The dashboard is a at < after installation. Note that the shipped
HTTP_ADDRESS is 0.0.0.0, so it is reachable on every interface, not only loopback — and
the default credentials are admin / changeme!. Change USERS, and set HTTP_ADDRESS to
127.0.0.1 (or put the ser a reverse proxy with TLS), before the host is on an
untrusted network.

The initial trail build can take several minutes. The sensor does not detect trail matches until a
valid trail set is a. The systemd unit runs the sensor's -T before startup so
that missing pri, an unwritable log directory, or an invalid trail set causes startup to
fail .

The installer test harness covers twel, and "it installed" is not the assertion: in
each one the server is started and asked for /ping, the sensor is asked to itself with
-T, the units are checked for paths that resolve, the installer is re-run to prove an upgrade
keeps operator configuration, and --uninstall is run. Every result is recorded per platform in
docs/compat, and the page there is generated from those rows rather than written
by hand.

Alpine and other musl systems get a -musl sensor build. They used to be told the prebuilt binary
was glibc-linked and to compile their own; the sensor builds and runs on musl natively, so that was
a missing artefact rather than a platform limit.

Building from source

The sensor requires Rust 1.74 or newer, libpcap de headers, and the system's capability
tools. The server and trail updater require Python 3.6 or newer.

Install the distribution packages:

Then build and the sensor:

Start the server in another terminal or on another host:

Prebuilt sensor binaries are attached to current releases with SHA-256 checksums: Linux x86_64
and aarch64 against both glibc and musl, macOS on Apple silicon and Intel, FreeBSD amd64, and
Windows x86_64.

The glibc builds link libpcap statically and target glibc 2.28, so the C library is the only thing
they need — nothing to install, on RHEL 8+, Debian 10+, Ubuntu 18.04+ and Leap 15.x alike. The musl
builds are fully static, so Alpine needs nothing at all. The Windows build is 64-bit and needs Windows 10 or later plus
Npcap installed before it will start — wpcap.dll is a load-time dependency,
so without it the loader refuses the executable rather than failing at capture. The archive says so
too. From a checkout, install.ps1 does the rest:

It refuses to install without Npcap, puts the binary, configuration and support tree under
%ProgramFiles%\Maltrail, keeps logs and the trail set in %ProgramData%\Maltrail, seeds the trail
set from the release, runs the sensor's own -T preflight, and starts it at boot as SYSTEM via a
scheduled task. -Uninstall removes the task and the program directory and keeps e under
%ProgramData%.

Binaries from 3.1.1 and earlier did not: they linked libpcap dynamically, and asked for it by
the name their AlmaLinux build host uses. Debian and Ubuntu ship the identical library under the
older name libpcap.so.0.8, so those binaries stop before they start —

— on a machine that has libpcap installed. install.sh links the missing name for you. By hand:

Systemd

The supplied packaging/systemd/ units run both processes as the
unpri maltrail user. Systemd creates /var/log/maltrail and /var/lib/maltrail, restricts
filesystem access, and grants the sensor CAP_NET_RAW and CAP_NET_ADMIN.

The installer configures these units automatically. For an existing source installation, follow
the manual service procedure in sensor/docs/INSTALL.md.

Check service state and logs with:

Docker

Start the supplied Compose deployment with:

Container configuration, storage, pri, and health checks are documented in
docker/README.md.

Configuration

Maltrail reads maltrail.conf, which contains separate [Sensor] and [Server] settings. The
installer places the managed configuration at /etc/maltrail.conf.

Frequently used sensor options include:

| Option | Purpose |
| --- | --- |
| MONITOR_INTERFACE | Capture interface or interfaces; any selects all supported interfaces |
| CAPTURE_FILTER | BPF capture filter |
| CAPTURE_FANOUT | Number of Linux capture sockets; defaults to one |
| CAPTURE_WORKERS | Capture workers, one socket each; defaults to CAPTURE_FANOUT, so one unless either is set |
| LOG_DIR | Local e directory |
| TRAILS_FILE | Generated trail database |
| LOG_SERVER | Remote Maltrail event server |
| SYSLOG_SERVER | CEF syslog destination or destinations |
| LOGSTASH_SERVER | Logstash JSON destination or destinations |
| STATS_ADDRESS | Prometheus metrics listener; disabled unless configured |
| UPDATE_PERIOD | Trail refresh interval |
| STATIC_TRAILS_URL | Where the assembled static trail set is fetched from; pin it to a dated release to control when new content lands |
| USER_WHITELIST | Operator-managed indicators that should not alert |
| CUSTOM_TRAILS_DIR | Operator-managed trail directory |
| STATIC_TRAILS_DIR | Optional checkout of the trails repository; only used to show a trail's source citation in the UI |

PROCESS_COUNT applies to the retired Python sensor and to the legacy e throttle; it does
not set the Rust sensor's worker count. Configure capture workers with CAPTURE_FANOUT or
CAPTURE_WORKERS instead.

Run the deployment check after changing configuration:

The check configuration, trails, whitelist entries, capture filter, pri, log
storage, update support, and worker settings. A successful check includes positi and
whitelist counts rather than only confirming that files exist.

Trails

A trail is one indicator — a domain, URL, IP address, IP:port pair, User-Agent, JA3/JA4
fingerprint or certificate hash — together with what it means and where it came from. The updater
merges four sources into TRAILS_FILE, in this order:

| source | where it comes from |
| --- | --- |
| Feeds | feeds/*.py, fetched directly by your deployment from each publisher, e.g. IPnoise |
| Custom | CUSTOM_TRAILS_DIR and CUSTOM_TRAILS_URL, your own indicators |
| Static | the assembled set from stamparm/trails, fetched from STATIC_TRAILS_URL; separately licensed |
| Engine lists | data/mass_scanner*.txt, shipped here because they change rarely |

Feeds are fetched by your own deployment rather than bundled here, so each is as current as its
publisher keeps it. IPnoise, for example, publishes the addresses
caught attacking a distributed network of honeypot sensors — hosts running no legitimate service,
so every connection reaching them is hostile by construction — and feeds/ipnoise.py pulls its
7-day list.

The static trails live in their own repository. Detection content changes tens of times a
day; the engine does not, and keeping them together meant updating detection required pulling code
and made this repository's history unusable. STATIC_TRAILS_URL points at the newest published
set:

Point it at a specific content-YYYYMMDD-HHMM release instead to pin a , so a bad publish
is not immediately global. The set is cached next to TRAILS_FILE, which is what makes an offline
or air-gapped rebuild work; the published sha256 is checked before downloading, so a deployment
that updates more often than the content changes transfers 65 bytes rather than 11 MB, and a
payload that does not match its digest is refused in favour of the cache.

update_trails() publishes a new TRAILS_FILE atomically and only after a successful build. Feeds
that return nothing are reported by name, so a deployment does not silently depend on a source that
has quietly retired.

Add your own indicators under CUSTOM_TRAILS_DIR, and anything that must ne an event to
USER_WHITELIST. Keep both outside the installation directory so an upgrade cannot o them.

Static trail contributions go to stamparm/trails; new feeds
go here. Either way an indicator needs a classification and a source somebody can check — see
Contributing.

Events and API

Maltrail records one whitespace-separated event per detection, using CS where a value
contains spaces:

The type field identifies what matched, including DNS, IP, IPORT, URL, PATH, HTTP,
UA, PORT, CERT, JA3, and JA4. The info field contains the trail classification, and
reference identifies the static list, feed, custom source, or heuristic that produced it. The
JA3/JA4 types fire on TLS *client* fingerprints: an implant's TLS stack survi
address and domain rotation, so its hello hash keeps matching after e else has burned
(published by the abuse.ch SSLBL JA3 feed).

Indicator lookup

Use /check to query one domain, IP address, or URL:

The confidence field (0-100, or null when una) says how strongly the sources back the
listing: 40 for a single feed, +15 per additional feed agreeing independently up to 100, and full
marks for the operator's own custom and static entries. It is computed at trail-update time from
feed agreement into a trails.confidence sidecar next to trails.csv; a ser trails
from an UPDATE_SERVER has no pro to score and reports null. Use it to prioritize
triage - a single-feed listing at 40 deserves a second look before it earns a firewall rule.

A subdomain lookup can match its listed parent. URL lookups check host/path before checking the
host alone. The ser the memory-mapped trail database and obser updates without a
restart.

Public static and feed trails are a without authentication, consistent with the /trails
endpoint used by remote sensors. Custom trails require an authorized session; an unauthorized
custom-only lookup is reported as a miss. Event data remains authenticated.

Operations

Monitoring

Use maltrail-sensor -T as a deployment and configuration gate. The supplied systemd unit runs it
as ExecStartPre.

To confirm that detection itself works — not just that the processes start — run:

It replays a crafted pcap of emulated malicious traffic (trail hits on a DNS query, an IP, an
IP:port, a URL path and a Host header, plus the SQL-injection, tra, RCE, XSS, proxy-probe,
sinkhole, missing-Host and port/web/infection-scanning heuristics) through the installed sensor
and asserts that every expected detection fires. It needs no root, no interface and no trail set of
its own. A healthy install prints 20/20 detection(s) fired.

When STATS_ADDRESS is configured, monitor at least these Prometheus metrics:

| Metric | Operational meaning |
| --- | --- |
| maltrail_up == 0 | No capture worker is running |
| Increasing maltrail_capture_dropped_total | The capture ring is dropping packets |
| Increasing maltrail_local_log_errors_total | Events were produced but could not be written locally |
| Increasing maltrail_remote_log_errors_total | Events could not be delivered to a remote sink; with DISABLE_LOCAL_LOG_STORAGE they are lost |
| maltrail_trail_generation not ad | The acti set is not being refreshed |
| maltrail_log_dir_free_bytes | Remaining capacity for local event storage |
| Increasing maltrail_state_saturations_total | A heuristic state limit was reached |
| Increasing maltrail_throttle_e | The e table is at its cap, so events are aggregated earlier than configured |

State saturation affects the corresponding heuristic; exact trail matching remains active.

Send SIGHUP or use systemctl reload maltrail-sensor to request a trail reload. Trail files
updated by another process are detected automatically and published to workers without restarting
the sensor.

The condensed observable store (USE_CONDENSED_STORAGE, meta.sqlite) supports the server's
novelty and retro-hunt views. The per-day e sidecar index (USE_E,
LOG_DIR/index/*.sqlite, roughly twice the log size on disk) is what makes /counts exact and
/hunt fast; it is maintained incrementally from the logs themselves and can be rebuilt with
server.py --rebuild-index. Compatibility with the retired sensor is documented in
sensor/docs/COMPATIBILITY.md.

Event retention

Maltrail does not rotate or delete event logs. Operators are responsible for defining retention,
archival, and deletion according to storage requirements and organizational policy.

Recommended practices:

Send the durable event copy to a remote Maltrail server or SIEM with LOG_SERVER,

SYSLOG_SERVER, or LOGSTASH_SERVER.

Alert on maltrail_log_dir_free_bytes with enough headroom for the expected event rate.

Rotate, archive, or remo daily logs using external tooling.

Keep files needed by the reporting interface uncompressed in LOG_DIR; archi files

elsewhere.

When the log filesystem is full, the sensor cannot append events. Event logs may also contain IP
addresses and domains that are regulated as personal data in some jurisdictions; retention policy
should account for the applicable requirements.

Synthetic traffic

To check that detection and the dashboard both still work, without waiting for real traffic:

--keep also replays sensor/tests/corpus/ into the same log and prints which of the shapes the
dashboard renders differently have an event behind them, so a missing icon, colour or glyph is
rather than assumed. Timestamps are shifted so the newest day is today. A sensor binary is
required (cargo build --release --manifest-path sensor/Cargo.toml).

The public demo's data is regenerated from such a run:

Documentation

| Document | Contents |
| --- | --- |
| sensor/docs/INSTALL.md | Installation, pri, configuration, and troubleshooting |
| sensor/docs/ARCHITECTURE.md | Sensor internals and data flow |
| sensor/docs/COMPATIBILITY.md | Deliberate differences from the retired Python sensor |
| sensor/docs/REPORT.md | Measurements, profiles, and test results |
| sensor/docs/ROADMAP.md | Open sensor work |
| SekuriPy Labs | Engineering notes, benchmarks and write-ups |

Contributing

Trail additions, feed maintenance, bug reports, documentation, and sensor impro are welcome.
Trail submissions should include a reliable source and should use the narrowest appropriate
classification.

Run the relevant checks before submitting code. The complete sensor gate is:

It runs formatting, Clippy with warnings denied, and the debug and release test suites. Run the
Python ser with:

The Windows build can be exercised from Linux, which is where its bugs have been found:

It cross-compiles the sensor with mingw-w64, extracts Npcap's userspace library from its installer
(an NSIS archive, so nothing is installed), and runs the result under Wine — the whole unit suite,
-T against the shipped configuration, the pcap corpus compared byte for byte against the native
binary, and the ser /ping under a Windows Python. Li is the one thing it
cannot cover; that needs Npcap's kernel driver and a real Windows machine. Prerequisites are
gcc-mingw-w64-x86-64, wine, and p7zip-full.

Project

License

TL;DR: Maltrail is MIT-licensed, but the Maltrail Trails dataset has separate terms. Independent IOC lookup/reference is fine; systematic use of Trails as an intelligence source in a commercial product or service requires permission/licensing.

Maltrail is distributed under the MIT License. See LICENSE.

That is the engine. The static trail set is separate work under separate terms: free for internal
defensive use, research and teaching, but a commercial product, service, MSSP or MDR offering, or a
redistributed feed needs a licence. An MIT engine does not make the content free to sell — see
LICENSE.md in
stamparm/trails before shipping it in something you charge
for.

Maintainers

Mirosla ()

Mikhail Kasimov ()

Sponsors

Sansec (2024–2025)

Sansec (2020–2021)

Presentations and publications

47th TF-CSIRT Meeting, Prague, 2016

(slides)

_Detect attacks on your network with Maltrail_, Linux Magazine, 2022

(article)

_Best Cyber Threat Intelligence Feeds_, Silent Push, 2022

(review)

_Research on Network Malicious Traffic Detection System Based on Maltrail_, Nanotechnology

Perceptions, 2024
(paper)

Third-party integrations

FreeBSD Port

OPNsense Gateway Plugin

D4 Project

BlackArch Linux

Maltrail Add-on for Splunk

Maltrail decoder and rules for Wazuh

GScan (trails only)

MalwareWorld (trails only)

oisd domain blocklist (trails only)

NextDNS (trails only)

NoTracking (trails only)

OWASP Mobile Audit (trails only)

Mobile Security Framework MobSF (trails only)

pfBlockerNG-devel (trails only)

Sansec eComscan (trails only)

Palo Alto Networks Cortex XSOAR (trail connector)

Acknowledgements

Thomas Kristner

Eduardo Arcusa Les

James Lay

Ladislav Baco ()

John Kristoff ()

Michael M&uuml;nz ()

Da

Chris Wild ()

Keith Irwin ()

Simon Szustkowski ()

项目信息

开发语言：Python

Star 数：8616

技术要点

该项目属于病毒分析方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Malicious traffic detection system展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。