stamparm/maltrail实时恶意流量检测系统，利用公共黑名单、静态恶意软件痕迹和启发式分析，识别 DNS、HTTP 和 IP 流量中的威胁。
 [](#license) [](sensor/) [](server.py) [](#trails) [](https://x.com/maltrail) # 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 包含一个基于浏览器的报告界面，用于探索检测到的 流量，支持实时更新、字段感知搜索、回溯狩猎、地理 视图、分类处置、保存视图和导出。  该界面由 `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`](https://github.com/stamparm/maltrail/blob/master/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`。 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 ``` — 在已安装 libpcap 的机器上。`install.sh` 会为你链接缺失的名称。手动操作：```bash # adjust the directory for your architecture: aarch64-linux-gnu, or /usr/lib64 on RPM distributions sudo ln -sf /usr/lib/x86_64-linux-gnu/libpcap.so.0.8 /usr/lib/x86_64-linux-gnu/libpcap.so.1 sudo ldconfig ``` ### 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 使用以下命令启动提供的 Compose 部署：```bash docker compose -f docker/docker-compose.yml up -d ``` 容器配置、存储、权限和健康检查记录在 [`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 ``` 检查会验证配置、trails、白名单条目、捕获过滤器、权限、日志存储、更新支持以及 worker 设置。成功的检查会包含正向的 trail 和白名单计数，而不仅仅是确认文件存在。 ## Trails 一个 trail 是一个指标——一个域名、URL、IP 地址、`IP:port` 对、User-Agent、JA3/JA4 指纹或证书哈希——连同它的含义和来源。更新器按以下顺序将四个来源合并到 `TRAILS_FILE`： | 来源 | 来源位置 | | --- | --- | | Feeds | `feeds/*.py`，由你的部署直接从每个发布者处获取 | | Custom | `CUSTOM_TRAILS_DIR` 和 `CUSTOM_TRAILS_URL`，你自己的指标 | | Static | 来自 [stamparm/trails](https://github.com/stamparm/trails) 的汇总集合，从 `STATIC_TRAILS_URL` 获取；[单独许可](https://github.com/stamparm/trails/blob/main/LICENSE.md) | | Engine lists | `data/mass_scanner*.txt`，随此处发布，因为它们很少变动 | 静态 trails 存放在它们自己的仓库中。检测内容每天变化数十次；而引擎不会，将它们放在一起意味着更新检测需要拉取代码，并使本仓库的历史记录无法使用。`STATIC_TRAILS_URL` 指向最新发布的集合：```text STATIC_TRAILS_URL https://github.com/stamparm/trails/releases/latest/download/trails.csv.gz ``` 将其指向特定的 `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> ``` `type` 字段标识匹配到的内容类型，包括 `DNS`、`IP`、`IPORT`、`URL`、`PATH`、`HTTP`、 `UA`、`PORT`、`CERT`、`JA3` 和 `JA4`。`info` 字段包含轨迹分类，而 `reference` 标识产生该匹配的静态列表、feed、自定义来源或启发式规则。 `JA3`/`JA4` 类型基于 TLS *客户端* 指纹触发：植入物的 TLS 栈在每次 地址和域名轮换后依然存在，因此即使其他所有特征都已失效，其 hello 哈希仍会持续匹配 （由 abuse.ch SSLBL JA3 feed 发布）。 ### 指标查询 使用 `/check` 查询单个域名、IP 地址或 URL：```bash curl 'http://127.0.0.1:8338/check?q=www.sub.evil.example' ``` - **`--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 } ``` `confidence` 字段（0-100，不可用时为 `null`）表示各来源对该条目的支持强度：单一 feed 为 40，每增加一个独立且一致的 feed 加 15，最高 100，而运营方自定义和静态条目则获得满分。该值在 trail 更新时根据 feed 一致性计算，并写入 `trails.csv` 旁边的 `trails.confidence` sidecar 文件；从 `UPDATE_SERVER` 拉取 trails 的服务器没有可评分的来源信息，因此报告 `null`。可用它来划分处置优先级——单一 feed 且置信度为 40 的条目在获得防火墙规则之前值得再核查一次。 子域名查询可以匹配其列出的父域名。URL 查询会先检查 `host/path`，再单独检查 host。服务器读取内存映射的 trail 数据库，无需重启即可感知 trail 更新。 公开的静态和 feed trails 无需认证即可访问，这与远程传感器使用的 `/trails` 端点一致。自定义 trails 需要已授权的会话；未授权且仅涉及自定义 trails 的查询会被报告为未命中。事件数据仍需认证。 ## 运维 ### 监控 使用 `maltrail-sensor -T` 作为部署和配置的检查关口。随附的 systemd unit 将其作为 `ExecStartPre` 运行。 要确认检测本身有效——而不仅仅是进程能够启动——请运行：```bash python3 server.py --detect-test ``` 它通过已安装的传感器重放一个精心构造的 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 ``` `--keep` 还会将 `sensor/tests/corpus/` 重放到同一日志中，并打印出仪表盘渲染效果不同的形状中哪些背后有事件，这样缺失的图标、颜色或字形就能被看到，而不是靠假设。时间戳会被平移，使最新的一天成为今天。需要传感器二进制文件（`cargo build --release --manifest-path sensor/Cargo.toml`）。 公开演示的数据就是通过这样一次运行重新生成的：```bash python3 sensor/tools/gen_demo_js.py --from DIR/logs # tops up html/js/demo.js ``` ## 文档 | 文档 | 内容 | | --- | --- | | [`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 ``` 它运行格式化检查、将警告视为错误的 Clippy，以及调试和发布测试套件。使用以下命令运行 Python 服务器测试套件：```bash bash tests/run.sh python3 ``` Windows 构建可以在 Linux 上运行，其漏洞正是在那里被发现的：```bash sh sensor/tools/check_windows.sh ``` 它使用 mingw-w64 交叉编译传感器，从安装程序中提取 Npcap 的用户空间库 （一个 NSIS 归档文件，因此不会安装任何内容），并在 Wine 下运行结果——整个单元测试套件、 针对随附配置的 `-T`、逐字节与原生二进制文件对比的 pcap 语料库，以及在 Windows Python 下 应答 `/ping` 的服务器。实时捕获是它唯一无法覆盖的部分；那需要 Npcap 的内核驱动和一台真实的 Windows 机器。先决条件是 `gcc-mingw-w64-x86-64`、`wine` 和 `p7zip-full`。 ## 项目 ### 许可证 **简而言之：** Maltrail 采用 MIT 许可证，但 Maltrail Trails 数据集有单独的条款。独立的 IOC 查询/引用没有问题；在商业产品或服务中系统性地将 Trails 用作情报来源则需要许可/授权。 Maltrail 在 MIT 许可证下分发。参见 [`LICENSE`](https://github.com/stamparm/maltrail/blob/master/LICENSE)。 那是引擎。静态 trail 集是采用单独条款的独立作品：可免费用于内部防御用途、研究和教学， 但商业产品、服务、MSSP 或 MDR 服务，或再分发的 feed 需要许可证。MIT 引擎并不意味着内容 可以免费出售——在将其用于收费产品之前，请参阅 [stamparm/trails](https://github.com/stamparm/trails) 中的 [`LICENSE.md`](https://github.com/stamparm/trails/blob/main/LICENSE.md)。 ### 维护者 - Miroslav Stampar ([@stamparm](https://github.com/stamparm)) - Mikhail Kasimov ([@MikhailKasimov](https://github.com/MikhailKasimov)) ### 赞助商 - [Sansec](https://sansec.io/) (2024–2025) - [Sansec](https://sansec.io/) (2020–2021) ### 演示和出版物 - 第 47 届 TF-CSIRT 会议，布拉格，2016 年 ([幻灯片](https://web.archive.org/web/20161109135211/https://www.terena.org/activities/tf-csirt/meeting47/M.Stampar-Maltrail.pdf)) - _Detect attacks on your network with Maltrail_，Linux Magazine，2022 年 ([文章](https://www.linux-magazine.com/Issues/2022/258/Maltrail)) - _Best Cyber Threat Intelligence Feeds_，Silent Push，2022 年 ([评论](https://www.silentpush.com/blog/best-cyber-threat-intelligence-feeds)) - _Research on Network Malicious Traffic Detection System Based on Maltrail_，Nanotechnology Perceptions，2024 年 ([论文](https://nano-ntp.com/index.php/nano/article/view/1915/1497)) ### 第三方集成 - [FreeBSD Port](https://www.freshports.org/security/maltrail) - [OPNsense Gateway Plugin](https://github.com/opnsense/plugins/pull/1257) - [D4 Project](https://www.d4-project.org/2019/09/25/maltrail-integration.html) - [BlackArch Linux](https://github.com/BlackArch/blackarch/blob/master/packages/maltrail/PKGBUILD) - [Validin](https://x.com/ValidinLLC/status/1719666086390517762) - [Maltrail Add-on for Splunk](https://splunkbase.splunk.com/app/7211) - [Maltrail decoder and rules for Wazuh](https://github.com/MikhailKasimov/maltrail-wazuh-decoder-and-rules) - [GScan](https://github.com/grayddq/GScan)（仅 trails） - [MalwareWorld](https://www.malwareworld.com/)（仅 trails） - [oisd domain blocklist](https://oisd.nl/?p=inc)（仅 trails） - [NextDNS](https://github.com/nextdns/metadata/blob/e0c9c7e908f5d10823b517ad230df214a7251b13/security/threat-intelligence-feeds.json)（仅 trails） - [NoTracking](https://github.com/notracking/hosts-blocklists/blob/master/SOURCES.md)（仅 trails） - [OWASP Mobile Audit](https://github.com/mpast/mobileAudit#environment-variables)（仅 trails） - [Mobile Security Framework MobSF](https://github.com/MobSF/Mobile-Security-Framework-MobSF/commit/12b07370674238fa4281fc7989b34decc2e08876)（仅 trails） - [pfBlockerNG-devel](https://github.com/pfsense/FreeBSD-ports/blob/devel/net/pfSense-pkg-pfBlockerNG-devel/files/usr/local/www/pfblockerng/pfblockerng_feeds.json)（仅 trails） - [Sansec eComscan](https://sansec.io/kb/about-ecomscan/ecomscan-license)（仅 trails） - [Palo Alto Networks Cortex XSOAR](https://xsoar.pan.dev/docs/reference/integrations/github-maltrail-feed)（trail 连接器） ### 致谢 - Thomas Kristner - Eduardo Arcusa Les - James Lay - Ladislav Baco (@laciKE) - John Kristoff (@jtkdpu) - Michael Münz (@mimugmail) - David Brush - @Godwottery - Chris Wild (@briskets) - Keith Irwin (@ki9us) - Simon Szustkowski (@simonszu)
