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) 中。

## 安装

### 安装程序

该安装程序支持 Debian、Ubuntu、Raspberry Pi OS、RHEL、Fedora 和 openSUSE：```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

预构建的 `x86_64` 和 `aarch64` 传感器二进制文件随当前版本发布，并附带 SHA-256 校验和。它们静态链接 libpcap，并面向 glibc 2.28，因此 C 库是它们唯一需要的依赖——在 RHEL 8+、Debian 10+、Ubuntu 18.04+ 以及 Leap 15.x 上均无需安装任何东西。在基于 musl 的系统（如 Alpine Linux）上，请从源码构建。

**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` | 生成的轨迹数据库 |
| `LOG_SERVER` | 远程 Maltrail 事件服务器 |
| `SYSLOG_SERVER` | CEF syslog 目标或目标列表 |
| `LOGSTASH_SERVER` | Logstash JSON 目标或目标列表 |
| `STATS_ADDRESS` | Prometheus 指标监听器；除非配置，否则禁用 |
| `UPDATE_PERIOD` | 轨迹刷新间隔 |
| `STATIC_TRAILS_URL` | 获取组装静态轨迹集的来源；将其固定到带日期的版本，以控制新内容何时落地 |
| `USER_WHITELIST` | 操作员管理的、不应触发告警的指标 |
| `CUSTOM_TRAILS_DIR` | 操作员管理的轨迹目录 |
| `STATIC_TRAILS_DIR` | 可选的轨迹仓库检出；仅用于在 UI 中显示轨迹的来源引用 |

`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>

## 安装

### 使用 pip 安装

```bash
pip install pywhisker

git clone https://github.com/ShutdownRepo/pywhisker.git
cd pywhisker
python3 setup.py install

usage: pywhisker.py [-h] [-v] -t TARGET [-u USERNAME] [-p PASSWORD] [-d DOMAIN]
                    [-H HASHES] [-k] [-a ACTION] [-n NEW_TARGET] [-s TARGET_SID]
                    [-m] [-o OUTPUT_FILE] [-q]

pywhisker - 针对目标对象的 msDS-KeyCredentialLink 属性的攻击工具

options:
  -h, --help            显示此帮助信息并退出
  -v, --verbose         启用详细输出
  -t TARGET, --target TARGET
                        目标对象（用户或计算机）
  -u USERNAME, --username USERNAME
                        用于认证的用户名
  -p PASSWORD, --password PASSWORD
                        用于认证的密码
  -d DOMAIN, --domain DOMAIN
                        目标域
  -H HASHES, --hashes HASHES
                        LM:NT 格式的哈希值
  -k, --kerberos        使用 Kerberos 认证
  -a ACTION, --action ACTION
                        要执行的操作（add、remove、list、clear、export）
  -n NEW_TARGET, --new-target NEW_TARGET
                        新目标对象（用于 add 操作）
  -s TARGET_SID, --target-sid TARGET_SID
                        目标对象的 SID（用于 remove 操作）
  -m, --mock            模拟操作，不实际执行
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        输出文件（用于 export 操作）
  -q, --quiet           安静模式，减少输出

pywhisker.py -t target_user -u user -p password -d domain.local -a list

pywhisker.py -t target_user -u user -p password -d domain.local -a add -n new_user

pywhisker.py -t target_user -u user -p password -d domain.local -a remove -s target_sid

pywhisker.py -t target_user -u user -p password -d domain.local -a clear

pywhisker.py -t target_user -u user -p password -d domain.local -a export -o output_file

`confidence` 字段（0-100，或不可用时为 `null`）表示来源对条目的支持强度：单一订阅源为 40，每个独立同意的额外订阅源加 15，最高为 100，而操作者自己的自定义和静态条目则获得满分。它是在轨迹更新时根据订阅源一致性计算出来的，并写入 `trails.csv` 旁边的 `trails.confidence` 侧车文件；从 `UPDATE_SERVER` 拉取轨迹的服务器没有可评分的来源信息，因此报告为 `null`。用它来优先安排分流——单一订阅源条目为 40 时，在它获得防火墙规则之前值得再看一眼。

子域名查询可以匹配其列出的父域名。URL 查询会先检查 `host/path`，然后再单独检查主机。服务器读取内存映射的轨迹数据库，并在不重启的情况下观察轨迹更新。

公共静态和订阅源轨迹无需认证即可访问，这与远程传感器使用的 `/trails` 端点一致。自定义轨迹需要授权会话；未经授权的仅自定义查询会被报告为未命中。事件数据始终保持认证状态。

## 操作

### 监控

使用 `maltrail-sensor -T` 作为部署和配置的关口。提供的 systemd 单元将其作为 `ExecStartPre` 运行。

要确认检测本身是否正常工作——而不仅仅是进程是否启动——请运行：```bash
python3 server.py --detect-test

它运行格式化检查、Clippy（拒绝所有警告）以及调试版和发布版测试套件。使用以下命令运行 Python 服务器测试套件：```bash
bash tests/run.sh python3