m61a/BeaconSentry

## ⚡ 3 秒简介 ``` $ python3 core/entropy_engine.py === Simulated DNS-tunneling burst (25 queries, same source) === [LOW ] f8a91cbe7710eae1998ecf8427e.exfil-c2.attacker-do score= 15 ttp=['T1071.004'] [MEDIUM ] 6a1d9f0033bb887ceeaa1029fd8801.exfil-c2.attacker score= 37 ttp=['T1071.004'] [HIGH ] 6a1d9f0033bb887ceeaa1029fd8801.exfil-c2.attacker score= 62 ttp=['T1071.004','T1048.003'] ``` 这是真实的输出，基于真实的数学运算，针对模拟的数据外泄通道——**零特征，零 YARA 规则，零威胁情报源。** 仅使用 Shannon 熵、自适应基线学习和频率分析，随着模式的显现实时提升严重级别。 这个代码库是背后输出结果的完整大师课——你将自己亲手构建每一个模块，逐模块地理解每一行代码背后的*原因*。 ## 🧠 为什么会有这个项目 基于特征的工具（Suricata 规则集、YARA、静态 IOC 源）非常擅长捕获以前被捕获过的内容。但在结构上，它们对以下情况视而不见： - 使用前所未见域名的新型 C2 框架 - 域名轮换速度比威胁情报更新还快的 DNS 隧道工具 - 专门设计用于击败固定间隔检测的 Beacon jitter - 通过目前还没人为其编写规则的协议进行的“靠山吃山”（Living off the land）式数据外泄 **BeaconSentry 颠覆了这一模式。** 每个模块不再问*“我以前见过这个具体的恶意行为吗？”*，而是问*“这看起来像人类或正常应用会做出的行为吗？”*——使用与威胁猎人手动使用的同类数学方法，实现自动化并实时运行。 ## 🗺️ 架构 ``` flowchart LR A[("🌐 Live NIC Traffic")] --> B["BPF Filter\nudp/53, tcp/80"] B --> C["CaptureThread\nscapy.sniff()"] C --> D[("Bounded Raw\nPacket Queue\ndrop-oldest")] D --> E1["ParserWorker #1"] D --> E2["ParserWorker #2"] D --> E3["ParserWorker #N"] E1 & E2 & E3 --> F{{"Event Router"}} F -->|DNS Query| G["🧮 Shannon Entropy Engine"] F -->|Connection Timing| H["📈 Jitter & Beaconing Analyzer"] F -->|Feature Vector| I["🌲 Isolation Forest"] G --> J["MITRE ATT&CK Mapper"] H --> J I --> J J --> K["🎨 Rich CLI Dashboard"] J --> L[("alerts.jsonl")] ``` **设计原则：** 捕获线程保持极简（复制字节、打时间戳、入队列——仅此而已）。所有的解析、数学计算和 ML 都在工作线程中发生，因此缓慢的检测器永远不会导致网卡丢包。请参阅 [`core/packet_capture.py`](core/packet_capture.py) 了解完整原理。 ## 📊 功能矩阵 | 模块 | 技术 | 检测内容 | MITRE ATT&CK | 状态 | |---|---|---|---|---| | **Entropy Engine** | Shannon 熵 + 按域名自适应基线 + 字符类启发式算法 | DNS 隧道、基于 DNS 的数据外泄 | `T1071.004` `T1048.003` `T1568.002` | ✅ **阶段 1 — 本代码库** | | **Packet Capture Core** | 多线程 `scapy` 嗅探 + BPF 过滤器 + 异步桥接 | 为上述每个模块提供实时 DNS/HTTP 解析基础 | — | ✅ **阶段 1 — 本代码库** | | **Jitter & Beaconing Analyzer** | 间隔方差、自相关、变异系数评分 | C2 beaconing，*包括*随机化/带 jitter 的睡眠定时器 | `T1071` `T1029` `T1571` | 🔜 阶段 2 | | **Isolation Forest** | 基于 flow 特征的 `scikit-learn` 无监督异常检测 | 异常出站流量、低速隐蔽的 C2、新型行为 | `T1071` `T1567` | 🔜 阶段 3 | | **Rich CLI Dashboard** | 实时终端 UI：微型图表、告警推送、严重级别颜色标记 | 为上述所有内容提供人工分诊层 | — | 🔜 阶段 4 | | **MITRE Mapper & Reporter** | TTP 关联 + JSONL/Markdown 事件导出 | 跨模块的攻击场景重建 | — | 🔜 阶段 5 | ## 🎨 未来发展：仪表板（阶段 4 预览） ``` ┌─ BeaconSentry // Live Behavioral Threat Detector ──────────────────────────────┐ │ uptime 00:42:17 pkts/s ▂▃▅▇█▆▄▂▁ 1,204/s mode: BEHAVIORAL (no sigs)│ ├────────────────────────────────┬─────────────────────────────────────────────┤ │ 🧮 ENTROPY RADAR │ 🚨 LIVE ALERT FEED │ │ │ │ │ attacker-domain.net 4.02 ▇▇│ [CRITICAL] DNS Tunneling src 10.0.0.99 │ │ cdn.jsdelivr.net 2.11 ▂▂│ → exfil-c2.attacker-domain.net │ │ google.com 1.84 ▁▁│ T1071.004 · T1048.003 · score 87/100 │ │ │ │ │ │ [HIGH] Beacon Detected src 10.0.0.44 │ │ │ → 45.33.x.x:443 interval 30s ±2s │ │ │ T1071 · T1571 · jitter-score 0.94 │ ├────────────────────────────────┴─────────────────────────────────────────────┤ │ 🌲 ISOLATION FOREST anomaly score ▓▓▓▓▓▓▓░░░ 0.71 flows/min: 3,410 │ └────────────────────────────────────────────────────────────────────────────┘ ``` *（概念图——将在阶段 4 使用 `rich` 库构建。给本代码库点个 Star ⭐ / 关注 👁️，以便在发布时收到通知。）* ## 🧩 MITRE ATT&CK 覆盖范围 | TTP | 技术 | 检测者 | |---|---|---| | `T1071.004` | 应用层协议：DNS | Entropy Engine | | `T1048.003` | 通过替代协议外泄（非 C2，DNS） | Entropy Engine（频率 + 熵） | | `T1568.002` | 动态解析：域名生成算法 | Entropy Engine（基线偏差） | | `T1071` | 应用层协议（通用 C2） | Beaconing Analyzer *(阶段 2)* | | `T1029` | 定时传输 | Beaconing Analyzer *(阶段 2)* | | `T1571` | 非标准端口 | Beaconing Analyzer *(阶段 2)* | | `T1567` | 通过 Web 服务外泄 | Isolation Forest *(阶段 3)* | ## 🛠️ 亲手构建路线图 每个阶段都是一个独立的大师课：阅读模块，理解数学原理，运行演示，然后进行扩展。 - [x] **阶段 1 — 基础** *（本代码库，现在）* - [x] `core/entropy_engine.py` — Shannon 熵、自适应基线学习、综合评分 - [x] `core/packet_capture.py` — 多线程捕获核心、BPF 过滤、异步桥接 - [ ] **阶段 2 — 时序 Beaconing 检测** - [ ] 按源/目标对提取间隔 - [ ] 变异系数 + 自相关，以捕获带 *jitter* 的 beacon - [ ] **阶段 3 — 无监督异常检测** - [ ] Flow 特征工程（字节比率、数据包时序、会话持续时间） - [ ] `IsolationForest` 训练 + 实时评分 pipeline - [ ] **阶段 4 — Rich 仪表板** - [ ] 实时微型图表、按严重级别上色的告警推送、键盘驱动分诊 - [ ] **阶段 5 — MITRE 映射与事件导出** - [ ] 将跨模块的 TTP 关联整合为单一攻击叙事 - [ ] 生成 JSONL + Markdown 事件报告 ## 🚀 快速开始 **立即尝试 Entropy Engine——无需 root 权限，无需网络访问：** ``` git clone https://github.com//beaconsentry.git cd beaconsentry python3 core/entropy_engine.py ``` **运行实时捕获**（需要 root 权限/CAP_NET_RAW——这会接触真实的数据包）： ``` python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt sudo python3 core/packet_capture.py ``` ## 📁 项目结构 ``` beaconsentry/ ├── core/ │ ├── entropy_engine.py # Phase 1 — Shannon entropy DNS tunneling detector │ └── packet_capture.py # Phase 1 — threaded live traffic parsing core ├── requirements.txt ├── README.md └── LICENSE ``` ## 🧪 Entropy Engine 的实际工作原理 Shannon 熵衡量不可预测性。像 `www` 或 `prod-api-eu` 这样人类键入的子域名遵循语言模式——低熵。而塞进标签里的 base32/十六进制编码的外泄 payload 看起来像 `f8a91cbe7710eae...`——每个字符出现的概率几乎相等，具有高熵。 但是，仅凭熵会对 CDN 哈希和 S3 存储桶产生误报。因此，BeaconSentry 将**五个独立的弱信号**组合成一个综合评分——这比围绕单一阈值进行调参更难被绕过： 1. 目标标签的原始 + 归一化 Shannon 熵 2. 字符类异常（十六进制比例、辅音连续出现模式） 3. 结构异常（子域名深度） 4. **自适应**统计偏差——一个*按根域名*自学习的基线，因此它会根据你的网络进行校准，而不是使用硬编码的数值 5. 滑动窗口内的查询频率——一次高熵查询只是噪音；两分钟内对同一域名的二十次查询就是数据外泄通道 请阅读 [`core/entropy_engine.py`](core/entropy_engine.py) 中带有完整注释的源代码——每一个函数都解释了*为什么*这么做，而不仅仅是做了*什么*。 ## ⚠️ 负责任的使用 BeaconSentry 是一款**防御性、教育性**工具。仅在你拥有或获得明确授权监控的网络上对其流量运行此工具。这里使用的技术反映了任何合格的蓝队或检测工程师已经在做的工作——本项目只是向你展示如何自己构建它。 ## 📜 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：Apex, DNS安全, Python, 异常检测, 无后门, 机器学习, 网络安全, 逆向工具, 隐私保护