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

默认使用一个捕获工作进程。增加工作进程可以提高捕获能力，但 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

常用安装选项：```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

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

预构建的传感器二进制文件随当前版本附带 SHA-256 校验和：Linux `x86_64`
和 `aarch64` 分别针对 glibc 和 musl，macOS 支持 Apple 芯片和 Intel，FreeBSD `amd64`，以及
Windows `x86_64`。

glibc 构建静态链接 libpcap 并以 glibc 2.28 为目标，因此 C 库是它们唯一需要的东西——无需安装任何东西，在 RHEL 8+、Debian 10+、Ubuntu 18.04+ 和 Leap 15.x 上同样如此。musl
构建是完全静态的，因此 Alpine 完全不需要任何东西。Windows 构建是 64 位的，需要 Windows 10 或更高版本，并且需要先安装
[Npcap](https://npcap.com) 才能启动——`wpcap.dll` 是加载时依赖项，
因此没有它加载器会拒绝该可执行文件，而不是在捕获时失败。归档文件中也说明了这一点。

来自 **3.1.1 及更早版本** 的二进制文件则不是这样：它们动态链接 libpcap，并按其 AlmaLinux 构建主机使用的名称请求它。Debian 和 Ubuntu 以较旧的名称 `libpcap.so.0.8` 提供相同的库，因此这些二进制文件在启动之前就停止了——```
./maltrail-sensor: error while loading shared libraries: libpcap.so.1: cannot open shared object file

### Systemd

提供的 `packaging/systemd/` 单元以非特权用户 `maltrail` 运行这两个进程。Systemd 会创建 `/var/log/maltrail` 和 `/var/lib/maltrail`，限制文件系统访问，并授予传感器 `CAP_NET_RAW` 和 `CAP_NET_ADMIN` 权限。

安装程序会自动配置这些单元。对于现有的源码安装，请遵循 [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md) 中的手动服务步骤。

使用以下命令检查服务状态和日志：```bash
systemctl status maltrail-sensor maltrail-server
journalctl -u maltrail-sensor -f

容器配置、存储、权限和健康检查记录在
[`docker/README.md`](https://github.com/stamparm/maltrail/blob/master/docker/README.md) 中。

## 配置

Maltrail 读取 `maltrail.conf`，其中包含独立的 `[Sensor]` 和 `[Server]` 设置。安装程序将托管配置放置在 `/etc/maltrail.conf`。

常用的传感器选项包括：

| 选项 | 用途 |
| --- | --- |
| `MONITOR_INTERFACE` | 捕获接口；`any` 选择所有支持的接口 |
| `CAPTURE_FILTER` | BPF 捕获过滤器 |
| `CAPTURE_FANOUT` | Linux 捕获套接字数量；默认为一个 |
| `CAPTURE_WORKERS` | 捕获工作进程，每个进程一个套接字；默认为 `CAPTURE_FANOUT`，因此除非设置了其中任一选项，否则为一个 |
| `LOG_DIR` | 本地事件日志目录 |
| `TRAILS_FILE` | 生成的 trail 数据库 |
| `LOG_SERVER` | 远程 Maltrail 事件服务器 |
| `SYSLOG_SERVER` | CEF syslog 目标 |
| `LOGSTASH_SERVER` | Logstash JSON 目标 |
| `STATS_ADDRESS` | Prometheus 指标监听器；除非配置，否则禁用 |
| `UPDATE_PERIOD` | Trail 刷新间隔 |
| `STATIC_TRAILS_URL` | 获取组装好的静态 trail 集的位置；将其固定到某个带日期的发布版本，以控制新内容何时生效 |
| `USER_WHITELIST` | 由操作员管理的、不应触发告警的指标 |
| `CUSTOM_TRAILS_DIR` | 由操作员管理的 trail 目录 |
| `STATIC_TRAILS_DIR` | 可选的 trails 仓库检出；仅用于在 UI 中显示 trail 的来源引用 |

`PROCESS_COUNT` 适用于已弃用的 Python 传感器和旧版事件日志节流；它**不**设置 Rust 传感器的工作进程数。请改用 `CAPTURE_FANOUT` 或 `CAPTURE_WORKERS` 配置捕获工作进程。

更改配置后运行部署检查：```bash
sensor/target/release/maltrail-sensor -T

将其指向特定的 `content-YYYYMMDD-HHMM` 发布版本以固定版本，这样一次糟糕的发布就不会立即影响全局。该集合缓存在 `TRAILS_FILE` 旁边，这正是离线或气隙重建能够工作的原因；下载前会校验已发布的 `sha256`，因此更新频率高于内容变化的部署传输的是 65 字节而非 11 MB，并且与摘要不匹配的载荷会被拒绝，转而使用缓存。

`update_trails()` 会原子性地发布新的 `TRAILS_FILE`，且仅在成功构建之后。返回空内容的源会按名称报告，因此部署不会在不知不觉中依赖一个已悄然退役的源。

在 `CUSTOM_TRAILS_DIR` 下添加你自己的指标，并将任何绝不能触发事件的内容添加到 `USER_WHITELIST`。将两者都放在安装目录之外，这样升级就不会覆盖它们。

静态特征贡献提交至 [stamparm/trails](https://github.com/stamparm/trails)；新的源提交到这里。无论哪种方式，指标都需要一个分类和一个可供他人核查的来源——参见[贡献](#contributing)。

## 事件与 API

Maltrail 每次检测记录一个以空白分隔的事件，当值包含空格时使用 CSV 引号：```text
"<time>" <sensor> <src_ip> <src_port> <dst_ip> <dst_port> <proto> <type> <trail> "<info>" <reference>

- **`--proxy`**：用于所有请求的代理 URL（例如 `http://127.0.0.1:8080`）
- **`--timeout`**：每个请求的超时时间（秒）（默认：10）
- **`--user-agent`**：自定义 User-Agent 字符串
- **`--headers`**：自定义请求头（格式：`Header: Value`，可重复）
- **`--cookie`**：自定义 Cookie 字符串
- **`--follow-redirects`**：跟随 HTTP 重定向
- **`--verify-ssl`**：验证 SSL 证书（默认：true）
- **`--threads`**：并发线程数（默认：10）
- **`--delay`**：请求之间的延迟（秒）（默认：0）
- **`--retries`**：失败请求的重试次数（默认：3）
- **`--output`**：输出文件路径
- **`--format`**：输出格式（`json`、`csv`、`txt`）（默认：`json`）
- **`--verbose`**：启用详细输出
- **`--quiet`**：抑制所有输出，仅显示结果
- **`--no-color`**：禁用彩色输出
- **`--config`**：配置文件路径（YAML 或 JSON）
- **`--log-level`**：日志级别（`debug`、`info`、`warn`、`error`）（默认：`info`）
- **`--log-file`**：日志文件路径
- **`--rate-limit`**：每秒最大请求数（默认：0 = 无限制）
- **`--random-agent`**：为每个请求使用随机 User-Agent
- **`--tor`**：通过 Tor 网络路由请求
- **`--tor-port`**：Tor SOCKS 代理端口（默认：9050）
- **`--tor-host`**：Tor SOCKS 代理主机（默认：127.0.0.1）
- **`--check-tor`**：验证 Tor 连接是否正常工作
- **`--update`**：将工具更新到最新版本
- **`--version`**：显示版本信息并退出
- **`--help`**：显示帮助信息并退出```json
{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)",
  "confidence": 100
}

它通过已安装的传感器重放一个精心构造的 pcap 文件，其中包含模拟的恶意流量（对 DNS 查询、IP、`IP:port`、URL 路径和 `Host` 头的 trail 命中，以及 SQL 注入、目录遍历、RCE、XSS、代理探测、sinkhole、缺失 `Host` 和端口/Web/感染扫描启发式规则），并断言每个预期的检测都会触发。它不需要 root 权限、不需要网络接口，也不需要自己的 trail 集。安装正常时会输出 `20/20 detection(s) fired`。

当配置了 `STATS_ADDRESS` 时，至少监控以下 Prometheus 指标：

| 指标 | 运维含义 |
| --- | --- |
| `maltrail_up == 0` | 没有捕获工作进程在运行 |
| `maltrail_capture_dropped_total` 持续增长 | 捕获环形缓冲区正在丢包 |
| `maltrail_local_log_errors_total` 持续增长 | 事件已产生但无法写入本地 |
| `maltrail_remote_log_errors_total` 持续增长 | 事件无法投递到远程接收端；在启用 `DISABLE_LOCAL_LOG_STORAGE` 时会丢失 |
| `maltrail_trail_generation` 不再推进 | 活动 trail 集未被刷新 |
| `maltrail_log_dir_free_bytes` | 本地事件存储的剩余容量 |
| `maltrail_state_saturations_total` 持续增长 | 某个启发式规则的状态上限已达到 |
| `maltrail_throttle_evictions_total` 持续增长 | 事件限流表已达上限，因此事件比配置的更早被聚合 |

状态饱和会影响对应的启发式规则；精确的 trail 匹配仍然有效。

发送 `SIGHUP` 或使用 `systemctl reload maltrail-sensor` 来请求重新加载 trail。由其他进程更新的 trail 文件会被自动检测并发布到工作进程，无需重启传感器。

精简可观测存储（`USE_CONDENSED_STORAGE`、`meta.sqlite`）为服务器的新颖性和回溯狩猎视图提供支持。按天的事件日志附属索引（`USE_EVENT_INDEX`、`LOG_DIR/index/*.sqlite`，磁盘占用约为日志大小的两倍）使 `/counts` 精确、`/hunt` 快速；它从日志本身增量维护，并可通过 `server.py --rebuild-index` 重建。与已退役传感器的兼容性记录在 [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) 中。

### 事件保留

Maltrail 不会轮转或删除事件日志。运维人员需根据存储需求和组织策略负责定义保留、归档和删除。

推荐做法：

- 使用 `LOG_SERVER`、`SYSLOG_SERVER` 或 `LOGSTASH_SERVER` 将持久事件副本发送到远程 Maltrail 服务器或 SIEM。
- 对 `maltrail_log_dir_free_bytes` 设置告警，并留出足够的余量以应对预期的事件速率。
- 使用外部工具轮转、归档或删除本地每日日志。
- 将报告界面所需的文件以未压缩形式保留在 `LOG_DIR` 中；将压缩文件归档到其他地方。

当日志文件系统已满时，传感器无法追加事件。事件日志还可能包含在某些司法管辖区被监管为个人数据的 IP 地址和域名；保留策略应考虑到适用的要求。

### 合成流量

为了在不等待真实流量的情况下检查检测和仪表盘是否仍然正常工作：```bash
python3 server.py --detect-test                      # assert every detection fires, then exit
python3 server.py --detect-test --keep DIR --serve   # ...and keep the events, serving them on :8338

## 文档

| 文档 | 内容 |
| --- | --- |
| [`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/INSTALL.md) | 安装、权限、配置和故障排除 |
| [`sensor/docs/ARCHITECTURE.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ARCHITECTURE.md) | 传感器内部结构和数据流 |
| [`sensor/docs/COMPATIBILITY.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/COMPATIBILITY.md) | 与已弃用的 Python 传感器的有意差异 |
| [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/REPORT.md) | 测量、配置文件和测试结果 |
| [`sensor/docs/ROADMAP.md`](https://github.com/stamparm/maltrail/blob/master/sensor/docs/ROADMAP.md) | 未完成的传感器工作 |
| [`SekuriPy Labs`](https://www.sekuripy.hr/labs/maltrail/) | 工程笔记、基准测试和文章 |

## 贡献

欢迎添加特征、维护数据源、报告错误、改进文档和传感器。
特征提交应包含可靠的来源，并应使用最合适的
分类。

在提交代码之前运行相关检查。完整的传感器检查门是：```bash
bash sensor/tools/check.sh

Windows 构建可以在 Linux 上运行，其漏洞正是在那里被发现的：```bash
sh sensor/tools/check_windows.sh