实时恶意流量检测系统,利用公共黑名单、静态恶意软件痕迹和启发式分析,识别 DNS、HTTP 和 IP 流量中的威胁。

Maltrail 是一个网络流量检测系统,用于识别与已知恶意基础设施的通信,并报告选定的流量异常。它将网络上观察到的域名、URL、IP 地址、IP:port 对以及 User-Agent 值与一组称为 trails 的指标进行匹配。
一次检测被记录为单个事件,包含源、目标、协议、匹配的 trail、分类以及 trail 来源:```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 专为基于指标的网络监控而设计。其启发式检测补充了
线索匹配,但它不能替代端点遥测或通用入侵
防御系统。
## 功能特性
- 完整的线索构建,结合了 3,000 多个捆绑静态文件、42 个公共源集成,
以及可选的运营方提供的线索。
- 使用 libpcap 的多线程 Rust 传感器,支持可选的 Linux `PACKET_FANOUT` 捕获工作进程。
- 提供报告界面、事件接收和 HTTP API 的 Python 服务器。
- 纯文本自定义线索和白名单,可进行审查和版本控制。
- 针对扫描、DNS 耗尽、类 DGA 查询、可疑下载、代理探测、
可疑 User-Agent 值及相关网络活动的启发式检测。
- 本地事件日志记录、远程 Maltrail 日志记录、基于 syslog 的 CEF 以及 Logstash JSON 输出。
- 使用 `maltrail-sensor -T` 进行部署验证,以及可选的 Prometheus 指标。
## 目录
- [架构](#architecture)
- [报告界面](#reporting-interface)
- [性能](#performance)
- [安装](#installation)
- [安装程序](#installer)
- [从源码构建](#building-from-source)
- [Systemd](#systemd)
- [Docker](#docker)
- [配置](#configuration)
- [线索](#trails)
- [事件与 API](#events-and-api)
- [运维](#operations)
- [监控](#monitoring)
- [事件保留](#event-retention)
- [文档](#documentation)
- [贡献](#contributing)
- [项目](#project)
- [许可证](#license)
- [维护者](#maintainers)
- [赞助商](#sponsors)
- [演示与出版物](#presentations-and-publications)
- [衍生黑名单](#derived-blacklist)
- [第三方集成](#third-party-integrations)
- [致谢](#acknowledgements)
## 架构
Maltrail 由两个独立的进程组成,它们可以运行在同一主机上,也可以运行在不同主机上:```text
┌──────────┐ events (UDP or file) ┌──────────┐
│ sensor │ ───────────────────────► │ server │ ◄── browser
└──────────┘ └──────────┘
Rust Python
libpcap + PACKET_FANOUT reporting UI + API
trail matching + heuristics
传感器捕获流量,执行特征匹配和启发式分析,并生成事件。
它可以将事件写入本地(LOG_DIR),发送到远程 Maltrail 服务器(LOG_SERVER),或两者
同时进行。它还可以通过 syslog(SYSLOG_SERVER)发送 CEF,并将 JSON 发送到 Logstash
(LOGSTASH_SERVER)。
服务器接收并存储远程事件,提供本地可用的事件日志,并提供 Web 界面和 API。
Maltrail 包含一个基于浏览器的报告界面,用于探索检测到的 流量,支持实时更新、字段感知搜索、回溯狩猎、地理 视图、分类处置、保存视图和导出。

该界面由 server.py 在 HTTP_ADDRESS:HTTP_PORT 上提供。它使用纯 JavaScript,仅有
一个第三方运行时依赖(PapaParse,用于 CSV 解析),且无需构建步骤。一次查看一天,
通过日期选择器选择,该选择器同时充当可用每日日志的事件密度网格。事件从 /events
流式传输,并在浏览器中聚合为威胁——每个不同的 (source, trail) 一行——显示在
可排序的网格中,并带有详情面板。
| 功能 | 说明 |
|---|---|
| 实时模式 | 追加的事件通过 Server-Sent Events(/live)推送,并合并到当前视图中。当 SSE 不可用,或对于该流无法服务的会话时,回退到轮询每日日志的字节范围。新的高严重性威胁可以触发桌面通知和声音警报;两者均可静音 |
| 搜索 | 字段限定令牌(src: dst: port: proto: type: trail: info: family: tag: uid: sev: dir: status:;family:interlock 会拉入 interlock-1/-2,即一次 feed 转储拆分成的分片)与空格组合表示 AND,- 表示排除,* 通配符,CIDR(src:10.0.0.0/8),以及数值范围和比较(port:>1024、count:>=100)。活动过滤器显示为可移除的标签 |
| 回溯狩猎 | 搜索所有保留的每日日志以查找一个指标(/hunt),而不仅仅是当前查看的那一天。受天数限制、墙钟时间预算和样本上限约束;因预算而提前中断的一天会与已完成的天数分开报告,而不是计入已完成总数。每日附属索引(LOG_DIR/index/、USE_EVENT_INDEX)使扫描可以跳过所有不匹配的行,并使 /counts 精确 |
| 世界地图 | 所选日期按国家的事件密度(/geo),放置每个事件的外部端点。无法归因到外部地址的事件报告为未映射,而不是猜测。设置 HOME_LAT / HOME_LON 以绘制来源弧线 |
| 分类处置 | 每个威胁的状态(新建 / 调查中 / 已解决 / 误报)、自由文本备注、标签和隐藏。白名单规则和 OSINT 透视可从行上下文菜单中使用 |
| 保存视图 | 命名的过滤器预设 |
| 导出 | 当前过滤视图导出为 CSV、JSON 或 defanged 指标 |
| 外观 | 深色和浅色主题,以及离散的文本大小步进 |
分类处置状态、保存视图、标签和外观设置存储在浏览器中
(localStorage),而不是服务器上:它们是按浏览器和按来源的,不会在
分析师之间共享。
受网络过滤器限制的会话只能看到来自其自身网络的事件,并且该 限制适用于计数、地图和黑名单端点以及事件列表。
单个地址的国家和 ASN 富化由服务器在 stat.ripe.net 查询,
服务器缓存结果并从其自己的 /ripe 端点提供给界面;浏览器只与 Maltrail
通信。设置 DISABLE_RIPE_LOOKUPS 可完全关闭出站查询。没有这些查询时——或在
没有互联网访问的主机上——标志来自本地 RIR 表,界面中的其他所有内容均可离线工作。
性能取决于处理器、流量组成、特征集大小、捕获驱动程序和网络 接口。以下数据测量的是传感器数据包处理路径的独立性能;它们不是 端到端实时捕获测量。
在启用启发式且特征集为 150 万行的 AMD Ryzen 7 PRO 4750U 上的代表性 测量结果:
| 流量 | 每数据包时间 |
|---|---|
| ICMP echo,58 字节 | 101 ns |
| TCP SYN,70 字节 | 302 ns |
| 批量 TLS,1,473 字节 | 402 ns |
| 热缓存下的 DNS 查询,93 字节 | 452 ns |
| 混合流量,平均 866 字节 | 552 ns |
| HTTP 请求,169 字节 | 602 ns |
| 唯一名称的 DNS 查询,93 字节 | 1,102 ns |
使用相同生成的捕获、配置和特征集进行的离线比较运行,在测试系统上测得
稳态每数据包成本比已退役的 Python 传感器低 14–37 倍。
这些数据将整个进程时间与稳态分开,因为特征加载在短回放中占主导地位。
检测本身由 sensor/tests/replay.rs 中的 42 个用例语料库单独断言。
在目标系统上使用以下命令进行测量:```bash cargo bench --manifest-path sensor/Cargo.toml --bench hotpath
默认使用一个捕获工作进程。增加工作进程可以提高捕获能力,但 Linux 流哈希会在工作进程之间划分每个源的状态,因此会降低某些扫描启发式的灵敏度。在文档记录的测试中,单工作进程启发式告警在双工作进程下保留了 91%,四工作进程下保留了 86%,八工作进程下保留了 65%。精确轨迹匹配保持不变。仅当捕获丢包指标表明有必要时,才增加 `CAPTURE_FANOUT`。
基准测试方法、硬件结果、性能分析器输出、内存测量以及实时扇出检查记录在 [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md) 中。
## 安装
### 安装程序
安装程序已在十二个 Linux 发行版上验证——Debian、Ubuntu、Fedora、Rocky、AlmaLinux、Arch、openSUSE Leap 和 Tumbleweed,以及 Alpine——外加 FreeBSD 和 macOS,在每个版本上均经过验证,完整结果记录在 [`docs/compat`](https://github.com/stamparm/maltrail/blob/master/docs/compat) 中。Raspberry Pi OS 和其他 64 位 ARM 系统使用 `aarch64` 构建;32 位 ARM 没有预构建的传感器,必须从源代码构建。```bash
curl -fsSL https://raw.githubusercontent.com/stamparm/maltrail/master/install.sh | sudo sh
它会安装依赖项,在 /opt/maltrail 下创建受管理的检出,验证预构建传感器的校验和,
创建非特权 maltrail 账户,安装 systemd 单元,准备
日志和状态目录,并启动传感器和服务器。重新运行安装程序会升级
受管理的检出。
在以提升的权限运行脚本之前,请先审查该脚本。从现有检出中,试运行 会显示命令而不更改系统:```bash sh install.sh --dry-run
常用安装选项:```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
安装完成后,仪表盘可通过 http://127.0.0.1:8338 访问。请注意,默认的
HTTP_ADDRESS 是 0.0.0.0,因此它可以在所有网络接口上访问,而不仅仅是回环接口——并且
默认凭据是 admin / changeme!。在主机处于不受信任的网络之前,请更改 USERS,并将 HTTP_ADDRESS 设置为
127.0.0.1(或将服务器置于带有 TLS 的反向代理之后)。
初始的 trail 构建可能需要几分钟。在有效的 trail 集可用之前,传感器不会检测 trail 匹配。systemd 单元在启动前运行传感器的 -T 验证,以便
缺失的权限、不可写的日志目录或无效的 trail 集会导致启动明显失败。
安装程序测试框架覆盖十二个发行版,并且“它安装了”并不是断言:在
每个发行版中,服务器被启动并请求 /ping,传感器被要求用 -T 验证自身,单元被检查路径是否可解析,安装程序被重新运行以证明升级
保留了操作员配置,并且运行了 --uninstall。每个结果都按平台记录在
docs/compat 中,那里的页面是从这些行生成的,而不是手工编写的。
Alpine 和其他 musl 系统获得 -musl 传感器构建。它们过去被告知预构建的二进制文件
是 glibc 链接的,需要自己编译;传感器在 musl 上原生构建和运行,所以那是一个
缺失的产物,而不是平台限制。
传感器需要 Rust 1.74 或更新版本、libpcap 开发头文件以及系统的 capability 工具。服务器和 trail 更新器需要 Python 3.6 或更新版本。
安装发行版软件包:```bash
sudo apt-get install cargo libpcap-dev libcap2-bin python3
sudo dnf install cargo libpcap-devel libcap python3
sudo zypper install cargo rust libpcap-devel libcap-progs python311
然后构建并验证传感器:```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
在另一个终端或另一台主机上启动服务器:```bash python3 server.py
预构建的传感器二进制文件随当前版本附带 SHA-256 校验和:Linux `x86_64`
和 `aarch64` 分别针对 glibc 和 musl,macOS 支持 Apple 芯片和 Intel,FreeBSD `amd64`,以及
Windows `x86_64`。