mrcord77/beacon-hunter
GitHub: mrcord77/beacon-hunter
Beacon Hunter 通过双门递归检测流水线，从 Zeek 连接日志中识别采用 phi 兼容加法递归调度的非周期性 C2 信标，弥补传统规律性检测器的盲区。
Stars: 9 | Forks: 0
# Beacon Hunter
**通过加法递归检测非周期性结构化 C2**
Beacon Hunter 旨在检测使用与 phi 兼容的加法递归调度的命令与控制（C2）信标活动——这是一种不断增长的非周期性时间模式，其中每次连接的间隔大约等于前两次间隔之和。此类模式在设计上能够规避基于规律性的检测器（如 RITA、AC-Hunter），但通过双门递归测试仍然可以进行结构化识别。
## 快速开始
*Beacon Hunter 双门流水线：Gate 1 通过 phi 比率聚类进行过滤，Gate 2 测试加法递归结构。*
```
pip install -r requirements.txt
# 在 Zeek conn.log 上运行
python beacon_hunter.py /path/to/conn.log
# 复现所有论文结果
python run_full_evaluation.py --quick # ~2 min, skips full evidence suite
python run_full_evaluation.py # ~5 min, full pipeline
# 运行单元测试
pytest tests/
# 端到端验证（验证论文声明）
python validate.py
```
## 工作原理
Beacon Hunter 是一个运行在 Zeek 连接日志上的双门流水线。
**Gate 1 — 比率测试**
对来自相同源/目标对的连接进行分组，并计算连续的连接间隔（ICI）比率。如果平均比率在 ±0.20 的误差范围内接近 phi（φ = 1.618），且比率变异系数（CV）低于 0.50，则通过测试。最低要求：5 个间隔。
**Gate 2 — 加法递归测试**
在所有连续的三个间隔组合中，测试 ICI[n+2] ≈ ICI[n+1] + ICI[n] 是否成立，使用基于 500 次置换零假设的平均相对误差进行评估。如果平均误差 < 0.20 且 p < 0.05，则通过测试。此门控会拒绝幂律增长（残差 0.40）和指数退避（残差 0.56）——这两者可能偶然通过 Gate 1。
**分类标签**
| 标签 | 含义 |
|-------|---------|
| `ADDITIVE_RECURRENCE_BEACON` | 两个门控均通过 — 与 phi 兼容的递增间隔调度 |
| `JITTERED_BEACON` | 带有抖动的周期性信标 — 通过比率门控，未通过递归门控 |
| `REGULAR_BEACON` | 恒定间隔的信标 |
| `BACKGROUND` | 未检测到信标结构 |
| `INSUFFICIENT_DATA` | 少于 5 个间隔 |
**接受区间：** 几何比率在 [1.45, 1.80] 之间，通过边界扫描实证确认。
## 架构
```
beacon_hunter_github/
├── beacon_hunter.py # CLI detector — entry point
├── detectors.py # Pure stateless gate functions (556 lines)
├── validate.py # 32-check end-to-end validation
├── run_full_evaluation.py # One-command reproduction pipeline
├── requirements.txt # Pinned dependencies
├── evidence/
│ ├── evidence_suite.py # All 6 evaluation batteries (Experiments A-J)
│ ├── rita_comparison.py # RITA-style periodicity baseline + real RITA comparison
│ ├── roc_and_ci.py # ROC curve (AUC=0.900) + Wilson CI
│ ├── generate_figures.py # Figures 1-7 (PNG + PDF)
│ └── *.json # Pre-computed results
├── data/
│ ├── pcaps/ # Ground-truth PCAPs (see Dataset Notes below)
│ └── zeek/ # Zeek conn.log files
├── figures/ # fig1-fig8 PNG + PDF (sequential)
├── paper/ # Full paper with appendices A-G
├── reports/ # Beacon Hunter output reports + real RITA v5.1.2 output
├── tests/
│ └── test_detectors.py # 34 unit tests (34/34 pass)
├── tools/
│ ├── fib_beacon_client.py # Fibonacci beacon traffic generator
│ ├── fib_beacon_server.py
│ └── uwf_to_connlog.py # UWF-ZeekData22 parquet → Zeek conn.log converter
└── archive/ # Deprecated scripts (legacy_detectors.py, old scanners)
```
## 证据流水线
| 脚本 | 实验 | 输出 |
|--------|-------------|--------|
| `evidence/evidence_suite.py` | A（合成数据）、B（实验室 PCAP）、C（AC 抖动）、E（对抗性测试集）、F（抖动扫描）、G（长度敏感性）、H（零假设分布）、I（phi 边界）、J（Logistic 映射） | `evidence_results.json` |
| `evidence/roc_and_ci.py` | G.5（ROC, AUC=0.900）、G（Wilson 置信区间 [0.992, 1.000]） | `roc_results.json` |
| `evidence/rita_comparison.py` | D（RITA 风格的基线比较） | `rita_comparison_results.json` |
| `evidence/generate_figures.py` | 图表 1-7 | `figures/fig*.png/pdf` |
## 数据集说明
| 文件 | 类型 | 描述 |
|------|------|-------------|
| `data/pcaps/fib_beacon_validation.pcapng` | Ground truth | 实验室生成的 Fibonacci 信标 PCAP；用于实验 B |
| `data/pcaps/jit_var_d30_j0_1h.pcap` | Ground truth | 30 秒恒定信标，0% 抖动，持续 1 小时 |
| `data/pcaps/jit_var_d30_j10_1h.pcap` | Ground truth | 30 秒信标，10% 抖动，持续 1 小时 |
| `data/pcaps/jit_var_d30_j99_1h.pcap` | Ground truth | 30 秒信标，99% 抖动（纯噪声），持续 1 小时 |
| `data/zeek/delay_var_d30_j25_combined.log` | 真实 + 注入 | 2 小时企业 Zeek conn.log，注入了 30 秒 + 25% 抖动信标 |
| `data/zeek/delay_var_d30_j25_24h_combined.log` | 真实 + 注入 | 上述数据集的 24 小时版本 |
| `reports/rita_output_v5.1.2_24h.txt` | 真实 RITA 输出 | RITA v5.1.2 可执行程序在 24 小时数据集上的实际输出（共评估了 100 个流） |
关于 UWF-ZeekData22 评估：请从 https://datasets.uwf.edu/data/ 下载，并使用 `tools/uwf_to_connlog.py` 进行转换。
## 关键结果
| 实验 | 结果 |
|------------|--------|
| 合成数据检测（实验 A） | 3/3 个信标类别正确，0 个误报 (FP) |
| 实验室 PCAP（实验 B） | ADDITIVE_RECURRENCE_BEACON，rec_err=0.000，p<0.002 |
| 抖动扫描（实验 F） | 在 20% 抖动下达到 100% 检测率；30% 时检测率急剧下降 |
| 幂律与指数退避对比（实验 E） | 残差分别为 0.40 和 0.56 > 阈值 0.20；被正确拒绝 |
| ROC AUC（实验 G.5） | 0.900；在 FPR=0.071 时 TPR=1.000 |
| 真实 RITA v5.1.2 检测抖动信标 | 0.617 低严重性（两个工具均检测到；分类方式不同） |
| UWF-ZeekData22（100 万个流，良性） | 0/12,083 个已分析流被标记为 ARB — 0.00% 的误报率 (FPR) |
| Logistic 映射测试集（实验 J） | 纯 Logistic 映射：0% 检测率；偏向 phi 且噪声 ≤20%：100% 检测率 |
| Phi 边界扫描（实验 I） | 确认接受窗口为 [1.45, 1.80] |
## 操作验证
以下结果是将 Beacon Hunter 应用于真实企业流量的结果：
**真实 RITA v5.1.2 对比**（`reports/rita_output_v5.1.2_24h.txt`）：
两个工具都检测到了 30 秒抖动的周期性信标。RITA 将其在其他 50 个严重/高危警报中评为 0.617 的低严重性。Beacon Hunter 将其分类为 `JITTERED_BEACON`。纯加法递归调度在 RITA 中的得分低于 0.35——这在附录 A 中得到了分析证明，并经过了实证确认。
**UWF-ZeekData22（100 万条真实企业连接）**：
在良性数据周中，0/12,083 个已分析流被标记为 `ADDITIVE_RECURRENCE_BEACON`。在侦察/发现攻击周中，0/1,995 个已分析流被标记（正确——端口扫描不是信标活动）。所有 4 个注入的 Fibonacci 信标在 0–25% 抖动下均被检测到。
**24 小时企业 Zeek 背景流量**：
1/243 个已分析流被标记——IPv6 NDP（邻居发现协议），在分析员分流启发式规则中占 34%，属于边缘情况且可归因于协议特性。
## 复现
有关预期的精确数值输出，请参阅 [`EXPECTED_RESULTS.md`](EXPECTED_RESULTS.md)。
```
# 快速验证所有论文声明：
python validate.py
# 完整 pipeline（从头生成所有输出）：
python run_full_evaluation.py
# 预期：32/32 项验证检查通过，ROC AUC=0.900，jitter 20%=100% 检出率
```
## 局限性
- 目前尚未发现使用与 phi 兼容调度的真实恶意软件（威胁模型仅停留在理论层面）
- 误报率已在两个真实数据集上进行表征；企业规模的多周评估仍是未来的工作
- 检测范围在设计上较为狭窄——检测器专门针对某一种结构化时间序列模式
## 引用
如果您使用了本项工作，请引用附带的论文：
[](https://doi.org/10.5281/zenodo.20431555)
## 许可证
AGPL-3.0。详见 `LICENSE`。
可通过 RepoSignal.io LLC 获取商业授权。
标签：C2检测, IP 地址批量处理, Python, Rootkit, Zeek, 安全规则引擎, 无后门, 网络安全, 逆向工具, 隐私保护