vinayak-sriv/DNSGuard
GitHub: vinayak-sriv/DNSGuard
DNSGuard是一个基于Python的DNS隧道检测系统，结合规则引擎和孤立森林机器学习模型，支持离线PCAP分析和实时流量监控，帮助安全团队识别隐藏在DNS查询中的数据泄露和隐蔽通信行为。
Stars: 0 | Forks: 0
# DNSGuard
DNSGuard 是一个基于 Python 的 DNS 隧道检测项目。它可以分析保存的 PCAP 文件，监控实时的 DNS 流量，对可疑查询进行评分，并在本地的 Flask 仪表盘中显示结果。
## 它的功能
DNS 隧道将数据隐藏在 DNS 查询中。DNSGuard 不是寻找单一的固定特征，而是通过以下方式对 DNS 流量进行评分：
- 基于规则的指标，例如长子域名、高熵、频繁查询以及 TXT/NULL/MX 记录的使用
- 在当前捕获/会话上训练的 Isolation Forest 异常模型
- 基于来源的行为特征，使来自单个 IP 的重复可疑活动变得可见
- 一个使结果更容易检查和解释的仪表盘
该项目包含三个主要脚本：
| 文件 | 用途 |
| --- | --- |
| `pcap_detector.py` | 用于离线 PCAP 分析和实时 DNS 捕获的核心检测器 |
| `dashboard.py` | 用于 PCAP 上传、告警、主机摘要和实时事件的本地 Flask 仪表盘 |
| `generate.py` | 用于演示和测试的合成 DNS 流量生成器 |
## 功能特性
- 带有 CSV 输出的离线 PCAP 分析
- 使用 Scapy 进行实时 DNS 数据包捕获
- 通过 `POST /live/push` 进行实时仪表盘更新
- 可搜索的告警表和每台主机的摘要
- 带有样本查询和原因的隧道来源注册表
- 用于正常、混合、仅隧道、突发和升级演示的合成流量模式
## 仓库结构
```
DNSGuard/
├── README.md
├── requirements.txt
├── .gitignore
├── pcap_detector.py
├── dashboard.py
├── generate.py
└── samples/
├── dns_tunneling_demo.pcap
├── dns_tunneling_demo_results.csv
├── dns_test_2600_packets.pcap
└── dns_test_2600_packets_results.csv
```
## 环境要求
- Python 3.10 或更高版本
- `pip`
- 用于实时数据包捕获或数据包生成的管理员/root 权限
安装依赖项：
```
pip install -r requirements.txt
```
本项目使用：
```
flask
numpy
pandas
requests
scapy
scikit-learn
```
桌面通知是可选的。如果您需要此功能，请安装：
```
pip install plyer
```
## 快速开始
分析包含的示例 PCAP：
```
python pcap_detector.py samples/dns_tunneling_demo.pcap --no-dashboard --no-notify
```
启动仪表盘：
```
python dashboard.py
```
打开：
```
http://127.0.0.1:8080
```
您可以从仪表盘上传 PCAP，或者单独运行检测器并将结果推送到其中。
## 使用说明
### 离线 PCAP 分析
当您已经拥有来自 Wireshark、tcpdump 或示例文件夹的 `.pcap` 文件时，请使用此模式。
```
python pcap_detector.py capture.pcap
python pcap_detector.py samples/dns_tunneling_demo.pcap
python pcap_detector.py capture.pcap --no-notify
```
检测器会打印一份控制台报告，并在捕获文件旁边保存一个 CSV 文件：
```
capture_results.csv
```
要将离线结果推送到运行中的仪表盘：
```
python dashboard.py
python pcap_detector.py capture.pcap --dashboard http://127.0.0.1:8080
```
### 实时捕获
实时捕获从网络接口读取数据包，通常需要提升的权限。
```
sudo python pcap_detector.py --live
sudo python pcap_detector.py --live --iface eth0
sudo python pcap_detector.py --live --iface eth0 --window 120
sudo python pcap_detector.py --live --iface eth0 --no-dashboard
sudo python pcap_detector.py --live --iface eth0 --no-notify
```
重要选项：
| 选项 | 默认值 | 描述 |
| --- | --- | --- |
| `--live` | 关 | 启用实时 DNS 捕获 |
| `--iface` | `eth0` | 进行嗅探的网络接口 |
| `--window` | `300` | 滑动窗口大小（以秒为单位） |
| `--dashboard` | `http://127.0.0.1:8080` | 用于事件流的仪表盘 URL |
| `--no-dashboard` | 关 | 禁用仪表盘流式传输 |
| `--no-notify` | 关 | 禁用桌面通知 |
查找您的接口名称：
```
# Linux
ip a
# macOS
ifconfig
# Windows
ipconfig
```
### 仪表盘
运行仪表盘：
```
python dashboard.py
```
然后打开 `http://127.0.0.1:8080`。
仪表盘支持：
- PCAP 上传和自动分析
- 总查询数、隧道数和风险等级的概览卡片
- 可搜索的告警表
- 来源主机摘要
- 实时事件流
- 已确认的隧道注册表
对于实时模式，请在单独的终端中运行仪表盘和检测器：
```
# Terminal 1
python dashboard.py
# Terminal 2
sudo python pcap_detector.py --live --iface eth0
```
### 流量生成器
`generate.py` 创建用于实验室测试的合成 DNS 流量。它使用 Scapy 来构造数据包，因此可能需要管理员/root 权限。
```
sudo python generate.py
sudo python generate.py --mode normal --packets 100
sudo python generate.py --mode tunnel --packets 200
sudo python generate.py --mode burst --packets 100 --delay 0.1
sudo python generate.py --mode escalate
```
流量模式：
| 模式 | 描述 | 使用场景 |
| --- | --- | --- |
| `mixed` | 40% 类隧道和 60% 正常流量 | 常规演示 |
| `normal` | 仅良性 DNS 查询 | 基线测试 |
| `tunnel` | 仅类隧道的高熵查询 | 敏感度测试 |
| `burst` | 来自单个攻击者 IP 的快速查询 | 速率规则测试 |
| `escalate` | 正常、混合，然后是突发流量 | 端到端演示 |
## 端到端演示
使用三个终端：
```
# Terminal 1: dashboard
python dashboard.py
```
```
# Terminal 2: live detector
sudo python pcap_detector.py --live --iface lo --dashboard http://127.0.0.1:8080
```
```
# Terminal 3: traffic generator
sudo python generate.py --mode escalate
```
打开 `http://127.0.0.1:8080` 并观察实时流。如果您的操作系统不支持环回捕获，请将 `lo` 替换为 Scapy 可以嗅探的接口。
## 检测原理
DNSGuard 从每个 DNS 查询中提取词汇和行为特征。
| 特征 | 类型 | 测量内容 |
| --- | --- | --- |
| `query_length` | 词汇 | 完整查询域名的长度 |
| `subdomain_length` | 词汇 | 注册域之前的标签长度 |
| `subdomain_entropy` | 词汇 | 类似有效载荷的子域名的随机性 |
| `hex_ratio` | 词汇 | 子域名中十六进制字符的比例 |
| `digit_ratio` | 词汇 | 完整查询中数字的比例 |
| `dot_count` | 词汇 | 域名中的标签数量 |
| `query_rate_per_min` | 行为 | 来自源 IP 的查询速率 |
| `avg_entropy` | 行为 | 源 IP 的平均熵 |
| `avg_response` | 行为 | 源 IP 的平均响应大小 |
| `special_type_count` | 行为 | TXT、NULL 和 MX 查询的数量 |
最终得分融合了规则和异常检测：
```
risk_score = (rule_hits / TOTAL_RULES) * 50 + ml_score * 50
```
当前规则阈值：
| 规则 | 阈值 |
| --- | --- |
| 子域名长度 | `> 45` 个字符 |
| 子域名熵 | `> 3.8` |
| 查询速率 | `> 5` 次查询/分钟 |
| 特殊记录计数 | `> 10` 次 TXT/NULL/MX 查询 |
风险等级：
| 级别 | 分数范围 | 含义 |
| --- | --- | --- |
| 低 | 0-30 | 弱或无隧道信号 |
| 中 | 30-60 | 值得审查 |
| 高 | 60-100 | 强可疑模式 |
`risk_score >= 50` 的行被标记为 `TUNNEL`。
## 仪表盘 API
默认情况下，仪表盘仅限本地访问。仅当您有意希望远程客户端调用它时，才设置 `DNS_SHIELD_ALLOW_REMOTE=1`。
| 端点 | 方法 | 用途 |
| --- | --- | --- |
| `/` | `GET` | 仪表盘 UI |
| `/analyse` | `POST` | 上传并分析 PCAP 文件 |
| `/results` | `GET` | 读取最新的离线分析结果 |
| `/live/push` | `POST` | 接收实时检测器事件 |
| `/live/status` | `GET` | 读取实时流状态 |
| `/live/reset` | `POST` | 清除实时流状态 |
PCAP 上传示例：
```
curl -X POST http://127.0.0.1:8080/analyse -F "pcap=@capture.pcap"
```
## 示例输出
```
========================================================================
DNS TUNNELING DETECTION REPORT
Generated: 2026-04-24 15:05:46
========================================================================
Traffic Summary
------------------------------------------------------------------------
Total DNS queries analysed : 800
Unique source IPs : 17
Flagged as TUNNEL : 266 (33.2%)
High risk queries : 192
Medium risk queries : 188
Low risk queries : 420
Per-IP Summary
------------------------------------------------------------------------
IP Queries Max Risk Avg Risk Tunnels
----------------- ------- --------- --------- --------
10.0.0.77 150 87.5 68.3 150 *** SUSPECTED TUNNEL SOURCE ***
10.0.0.42 150 86.0 59.1 116 *** SUSPECTED TUNNEL SOURCE ***
```
CSV 输出包含：
```
ts, src_ip, dst_ip, sport, query, record_type, response_size,
subdomain_length, subdomain_entropy, hex_ratio, query_rate_per_min,
risk_score, risk_level, prediction
```
## 局限性
- 除非在上游进行解密，否则 DNS-over-HTTPS 和 DNS-over-TLS 对此解析器是不可见的。
- 原始解析器主要针对 IPv4 UDP DNS 流量。
- 小型捕获为异常评分提供的行为上下文较少。
- 攻击者可以通过用类似字典的标签填充有效载荷来降低熵。
- 合成生成器用于实验室验证，不能替代真实的网络基线。
## 参考文献
1. Farnham, G. and Atlasis, A. - *Detecting DNS Tunneling.* SANS Institute InfoSec Reading Room, 2013.
https://www.sans.org/white-papers/34152/
2. Ellens, W. et al. - *Flow-based Detection of DNS Tunnels.* Lecture Notes in Computer Science, 2013.
https://link.springer.com/chapter/10.1007/978-3-642-40973-7_11
3. Homem, I., Papapetrou, P. and Dosis, S. - *Information-Entropy-Based DNS Tunnel Prediction.* IFIP AICT, 2018.
https://link.springer.com/chapter/10.1007/978-3-319-99277-8_8
4. Liu, F.T., Ting, K.M. and Zhou, Z.-H. - *Isolation Forest.* IEEE ICDM, 2008.
https://ieeexplore.ieee.org/document/4781136/
5. iodine - IP-over-DNS 隧道。
https://github.com/yarrick/iodine
6. DNScat2 - 基于 DNS 的命令和控制框架。
https://github.com/iagox86/dnscat2
7. Zeek 网络安全监控器。
https://zeek.org
## 作者
DNSGuard 由 Vinayak Srivastava 在 UPES Dehradun 的 Dr. Richa Kumari 指导下，作为 B.Tech CSE 毕业设计项目开发。
标签：AI安全, Apex, Chat Copilot, DNSGuard, DNS安全, DNS数据外发检测, DNS枚举, DNS隧道检测, Flask, Isolation Forest, PCAP分析, Python, Scapy, Scikit-learn, 主机行为分析, 人工智能, 威胁情报, 安全仪表盘, 开发者工具, 异常检测, 无后门, 机器学习, 流量可视化, 用户模式Hook绕过, 网络安全, 网络安全工具, 网络安全检测系统, 逆向工具, 隐私保护