Maltrail 专为基于指标的网络监控而设计。其启发式检测补充了特征匹配，但并不能替代端点遥测或通用入侵防御系统。

## Features

- 完整特征构建，包含超过 3,000 个捆绑静态文件、42 个公共源集成，以及可选的运维人员提供的特征。
- 一个多线程 Rust 传感器，使用 libpcap，并提供可选的 Linux `PACKET_FANOUT` 捕获工作线程。
- 一个 Python 服务器，提供报告界面、事件接收和 HTTP API。
- 纯文本自定义特征和白名单，可审查并纳入版本控制。
- 针对扫描、DNS 耗尽、类 DGA 查询、可疑下载、代理探测、可疑 User-Agent 值及相关网络活动的启发式检测。
- 本地事件日志、远程 Maltrail 日志、基于 syslog 的 CEF 以及 Logstash JSON 输出。
- 通过 `maltrail-sensor -T` 进行部署验证，并提供可选的 Prometheus 指标。

## Contents

- [架构](#architecture)
- [性能](#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`。

基准测试方法、硬件结果、性能分析器输出、内存测量以及实时 fanout 检查已记录在 [`sensor/docs/REPORT.md`](https://github.com/stamparm/maltrail/blob/HEAD/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.1        # 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
校验和。它们面向 glibc 2.28，并在运行时需要 libpcap。在基于 musl 的系统（如
Alpine Linux）上，请从源码构建。

已退役的 Python 传感器仅用于比较与一致性工具。这些工具还
要求 `pcapy-ng` 和 Python 开发头文件，如
[`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/sensor/docs/INSTALL.md) 中所述。

### Systemd

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

安装程序会自动配置这些单元。对于现有的源码安装，请按照
[`sensor/docs/INSTALL.md`](https://github.com/stamparm/maltrail/blob/HEAD/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/HEAD/docker/README.md)。

## 配置

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

常用的传感器选项包括：

| Option | Purpose |
| --- | --- |
| `MONITOR_INTERFACE` | 捕获接口或接口列表；`any` 选择所有受支持的接口 |
| `CAPTURE_FILTER` | BPF 捕获过滤器 |
| `CAPTURE_FANOUT` | Linux 捕获套接字数量；默认为一 |
| `LOG_DIR` | 本地事件日志目录 |
| `TRAILS_FILE` | 生成的 trail 数据库 |
| `LOG_SERVER` | 远程 Maltrail 事件服务器 |
| `SYSLOG_SERVER` | CEF syslog 目标或目标列表 |
| `LOGSTASH_SERVER` | Logstash JSON 目标或目标列表 |
| `STATS_ADDRESS` | Prometheus 指标监听器；除非配置，否则禁用 |
| `UPDATE_PERIOD` | Trail 刷新间隔 |
| `USER_WHITELIST` | 不应触发告警的操作员管理指标 |
| `CUSTOM_TRAILS_DIR` | 操作员管理的 trail 目录 |

`PROCESS_COUNT` 适用于已退役的 Python 传感器。Rust 传感器的捕获工作进程应改用 `CAPTURE_FANOUT` 配置。

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

在 `CUSTOM_TRAILS_DIR` 下添加本地指标。将永远不应生成警报的指标添加
到 `USER_WHITELIST`。将自定义数据保留在受管检出之外可防止升级
覆盖它。

更新程序根据已启用的数据源、捆绑的静态 trail 和自定义 trail 重新构建 `TRAILS_FILE`。只有
在构建成功后才以原子方式发布新文件。空数据源或失败的数据源会被报告，因此运行中的部署不会静默
依赖过期或已停用的数据源。

Trail 贡献应包含指标、分类和可验证的来源。在提交拉取请求之前，请参阅
[Contributing](#contributing)。

## 事件与 API

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

请提供需要翻译的Markdown内容。```json
{
  "query": "www.sub.evil.example",
  "found": true,
  "trail": "evil.example",
  "info": "asyncrat (malware)",
  "reference": "(static)"
}

它运行格式化、Clippy（禁止警告）、调试与发布测试，以及针对已退役 Python 传感器的奇偶校验回放。使用以下命令运行 Python 服务器套件：```bash
bash tests/run.sh python3