mustard-research/BeaconButty

# BeaconButty **一款 Raspberry Pi 网络设备，通过作为 NAT 路由器串联接入，并使用 Zeek + RITA + ClickHouse 分析每一个数据流，从而在您的局域网中捕获恶意软件的命令与控制 (C2) 信标。** BeaconButty 是一个围绕 Pi 5 构建的小型 DIY 网络检测设备。它接入在您的家庭或小型办公室交换机与现有的互联网路由器之间，成为局域网网关，并持续分析出站流量，寻找能将 C2 回调与正常浏览区分开来的周期性检入模式。一旦发现此类模式，它会通过 Slack 和本地 Web 仪表板通知您。 本仓库包含完整的源代码：安装脚本、systemd 单元、Flask 仪表板、Zeek 站点策略、RITA 包装器、告警流水线，以及从全新 Pi 重新构建它所需的文档。  ## 为什么开发这个项目 EDR 用于在端点捕获恶意软件；防火墙用于拦截已知的恶意目的地；SIEM 则从已知遭受攻击的系统中摄取日志。目前的盲区在于小型网络中无人看管的角落——IoT 设备、家庭成员的笔记本电脑，以及任何无法或不愿运行代理的程序——它们正在向由 CDN 隐藏的 C2 发送信标。在单个数据流层面没有什么值得大惊小怪的告警；真正的信号是*数小时或数天内的周期性规律*。 这正是 RITA 擅长的地方。BeaconButty 将 Zeek + RITA + ClickHouse 进行了具有强烈主观色彩的整合，封装在一个约 420 英镑的盒子里，您只需一个下午就能搭建完成。此外，它还配备了一个 Web 应用，将 RITA 的发现转化为人类可操作的形式（并具备快速处理误报的工作流，确保其在使用首日之后依然实用）。 它**不是**企业级 NDR 的替代品。它是您部署在无人监控的小型网络上的备用方案。 ## 功能特性 - **信标评分** —— RITA 通过熵和离散度，在每个每日 Zeek 数据集中标记出具有规律性连接的目标地址。 - **低频检测器** —— 用于检测低频信标（连续 ≥5 天，每天 ≤6 次连接）的二轮检测器，这类信标可能会被 RITA 的单日分析漏检。 - **JA4 TLS 指纹识别** —— 在网络上对每个 TLS Client Hello 进行指纹识别，按设备进行索引，并与 [FoxIO 的 ja4db](https://github.com/FoxIO-LLC/ja4) 进行交叉比对，以匹配已知的恶意指纹。 - **威胁情报富化** —— 将裸外部 IP 与 Shodan InternetDB、AbuseIPDB、Spamhaus DROP 和 Tor 出口节点列表进行交叉比对（每日刷新）。 - **L2 异常检测** —— 通过自定义的 Zeek 记录器，在 ARP 层提供网关伪装告警。 - **误报处理工作流** —— 点击即可完成注册表的抑制操作（支持按设备 MAC、目标域名/IP 或协议进行抑制），具备顶级域名感知的 fnmatch 以及基于 ASN 推导出的原因预填充功能。 - **Slack 告警** —— 支持按检测器启用/禁用，通过结构性过滤条件来降低噪声（例如“仅限独立 IP + 非超大规模云服务商”），并在您确实需要仔细阅读每一条告警时提供 Slack 频道清除按钮。 - **OLED 状态显示屏** —— 前端 128×64 SSD1306 显示屏，可实时显示信标计数、运行时间和系统负载。 - **每日 Slack 摘要、每周归档、14 天自动备份、USB 克隆** —— 内置完整的运维流水线。 ## 架构 ``` flowchart LR subgraph LAN D1[Laptop] D2[IoT device] D3[Phone] end LAN -- eth1 capture --> Z[Zeek 8.1] LAN -- NAT/dnsmasq --> WAN((Internet)) Z -->|conn / ssl / dns / http / arp logs| L2[(/var/log/zeek)] L2 -->|hourly import| R[RITA v5] L2 -->|hourly slow-cadence| SC[slow-cadence.py] R --> CH[(ClickHouse)] SC --> CH CH --> REP[beacon-report.sh
daily 07:00] CH --> WEB[Flask dashboard
https://your-host] REP --> AL[alert.sh] SC --> AL AL --> LAM[AWS Lambda
dedup] LAM --> SLK[Slack #channel] ``` Pi 采用**串联**方式接入——而不是 SPAN/镜像侦听——因此它无需托管交换机支持即可捕获每一个数据包。捕获过程在 `eth1`（局域网侧）进行；`eth0` 是面向 WAN 的接口。dnsmasq 负责处理局域网的 DHCP/DNS，这意味着 BeaconButty 还能免费获得干净的主机名解析。 更深入的分析详见 [`docs/architecture/`](docs/architecture/) —— 请从 [system-overview.md](docs/architecture/system-overview.md) 开始阅读。 ## 硬件 总成本约 420 英镑（2026 年中英国零售价）： | 组件 | 原因 | 备注 | |---|---|---| | Raspberry Pi 5 8GB (~£170) | ClickHouse + Zeek + RITA 全部运行在 8GB 内 | 4GB 也能运行但内存吃紧 | | Pironman 5 NVMe 机箱 (~£170) | 主动散热、NVMe 插槽、OLED、RGB 风扇 | 包含分级风扇控制脚本 | | 1TB NVMe SSD (~£60) | Zeek 日志 + ClickHouse 历史；通过 log2ram 提升 SSD 寿命 | 适用于任何 M.2 2280 规格 | | USB-C 2.5G 以太网适配器 (~£20) | 用于 WAN 侧捕获的第二块网卡 | Pi 5 仅板载了一个网卡 | | MicroSD 64GB (~£10) | 用于紧急启动的备份操作系统 | 选配 | 完整的物料清单和组装说明请见：[`docs/hardware/hardware-setup.md`](docs/hardware/hardware-setup.md)。 ## 快速开始 1. **将 Raspberry Pi OS Lite (64-bit) Bookworm** 刻录到您的 NVMe 中。在 Pi Imager 的自定义步骤中设置主机名、您的用户名和 SSH 密钥。其中的 systemd 单元和备份脚本假定默认用户为 `dm`，并且仓库位于 `/home/dm/BeaconButty/` —— 如果您选择了不同的用户名，请在进行下一步之前运行 `grep -rl '/home/dm/' scripts/ systemd/ webapp/ | xargs sed -i "s|/home/dm|/home/$USER|g"`。 2. **在 Pi 上克隆此仓库**： git clone https://github.com/mustard-research/BeaconButty.git cd BeaconButty 3. **复制本地站点配置模板**： sudo mkdir -p /etc/beaconbutty sudo cp config/local.env.example /etc/beaconbutty/local.env sudoedit /etc/beaconbutty/local.env # 设置 BB_HOST, BB_LAN_GATEWAY_MAC 等。 MAC 地址至关重要 —— `ip -o link show eth1 | awk '{print $17}'` 会为您提供正确的值。 4. **按顺序运行安装脚本**： sudo ./scripts/01_system_deps.sh sudo ./scripts/02_install_zeek.sh sudo ./scripts/03_install_clickhouse.sh sudo ./scripts/04_install_rita.sh sudo ./scripts/05_configure.sh sudo ./scripts/07_router_mode.sh # 将 Pi 变为 NAT 网关 —— 务必在最后执行 sudo ./scripts/08_install_suricata.sh 5. **将 Pi 串联接入网络** —— `eth0`（或 USB 网卡）连接到您的互联网路由器，`eth1` 连接到您的局域网交换机。重启设备。 6. **访问仪表板**，地址为 `https:///`（如果尚未设置 TLS，则访问 `http://:8080/`），并观察首日数据的流入情况。 完整的部署指南（包括通过 Let's Encrypt 和 Route 53 DNS 配置 TLS）位于 [`RESTORE.md`](RESTORE.md) 中（它是作为灾难恢复指南编写的，因此也是最严格的安装路径）。 ## 日常使用 每天早上，您会看到一份 Slack 摘要，其中包含前一天排名靠前的信标候选者。该 Web 应用共有八个页面——最常用的几个是： - **Dashboard** —— 系统状态磁贴、今日信标计数、风扇状态、log2ram 占用情况、告警摘要。 - **Beacons** —— RITA 热点列表，带有可排序的表格、内联的误报 (FP) 处理工作流以及逐行富化信息（JA4、ASN、威胁情报）。 - **Network** —— 头部活跃主机、新信标、数据外发/夜间活动面板、JA4 清单。 - **Slow Beacons** —— 被 RITA 单日分析窗口遗漏的多日低频目标地址。 - **Health** —— 涵盖每个组件的结构化状态卡片，带有 Slack“测试告警” / “清除频道”按钮。  详细的 UI 导览——包括八个页面的完整截图库——请见 [`docs/development/webapp.md`](docs/development/webapp.md)。 Pi 上的少量运维脚本涵盖了其他所有操作——它们位于 `/usr/local/bin/beaconbutty-*.sh`，并在 [`docs/development/scripts-and-timers.md`](docs/development/scripts-and-timers.md) 中有详细文档说明： ``` beaconbutty-summary.sh # today's findings beaconbutty-fp.sh list # current FP registry beaconbutty-fp.sh add "..." # add an FP beaconbutty-health.sh # full system check ``` ## 文档 其他所有内容均位于 [`docs/`](docs/) 下： | | | |---|---| | [architecture/](docs/architecture/) | 系统设计、服务、数据流水线、告警链 | | [hardware/](docs/hardware/) | Pi 构建、散热、OLED | | [operation/](docs/operation/) | 日常运维、健康监控、备份、容量规划、故障排查、重启程序 | | [security/](docs/security/) | 系统加固 —— SSH、防火墙、fail2ban、sudoers | | [development/](docs/development/) | Web 应用内部机制、完整的脚本/定时任务清单、许可说明 | | [investigation/](docs/investigation/) | 误报工作流、告警调优、低频检测器设计、IP 富化、威胁案例研究 | ## 状态 **稳定且处于活跃的生产使用中**；自 2026 年初起即在原始设备 `bb0` 上运行；自最初配置 Zeek+RITA 以来，已积累了约 150 次旨在完善运维体验的提交。该 Web 应用、检测器、告警流水线、备份层级和健康监控均已通过家庭网络上的真实流量实战检验。 **实验性/部分功能：** - ClickHouse 26 —— 运行良好，但通过 apt-mark hold 锁定了版本，以避免其静默清空配置目录（详见[故障排查](docs/operation/troubleshooting.md)）。 ## 许可说明 BeaconButty 自身的代码采用 **MIT 许可协议**（详见 [`LICENSE`](LICENSE)）。 我们用于 TLS Client Hello 的 JA4 指纹算法采用 **BSD-3** 许可协议。然而，JA4+ 的扩展指纹（JA4S/JA4H/JA4X 等）是在 FoxIO License 1.1 下授权的——*仅供非商业用途*。此处打包的 BeaconButty 完全适用于个人/内部使用。如果您想在商业产品中使用 JA4+ 扩展指纹，则需要向 FoxIO 申请单独的 OEM 许可。完整分析请见 [`docs/development/licensing.md`](docs/development/licensing.md)。 所使用的第三方工具（RITA, Zeek, ClickHouse, Suricata, dnsmasq）各自受其自身的许可协议约束，并从各自的软件包仓库中进行安装。 ## 演讲与文章 - **BSides UK 2026** (七月) —— *使用 Zeek、RITA 和 Raspberry Pi 构建家庭网络信标检测器*。幻灯片及录像链接即将发布。 由 [Mustard Research](https://mustardresearch.com) 构建。

标签：AMSI绕过, IP 地址批量处理, Metaprompt, Raspberry Pi, RITA, Rootkit, Zeek, 内存执行, 命令与控制检测, 威胁检测, 网络安全, 网络流量分析, 逆向工具, 隐私保护