Maltrail

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 包含一个基于浏览器的报告界面，用于探索检测到的流量，支持实时更新、字段感知搜索、回溯狩猎、地理视图、分类处置、保存视图和导出。

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

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

然后构建并验证传感器：```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`。

最受欢迎

maltrail