Mr20x20/PyShield_Sniffer

# PyShield Sniffer 一个基于 Python 的轻量级网络入侵检测器，可实时监控 TCP 流量，并即时标记两种常见的攻击模式： - **端口扫描 / 侦察** — 同一源 IP 在短时间窗口内访问大量不同的端口 - **SYN 洪水攻击** — 同一源 IP 在短时间窗口内以异常速率发送 SYN 数据包 检测结果会输出到控制台，并记录到 JSON 报告文件中，其结构化设计便于直接输入到下游的 SIEM 或仪表盘中。 ## 为什么开发这个工具 大多数简单的“检测端口扫描”脚本只是单纯地统计数据包数量。而 PyShield 则针对每个源 IP 使用了**滑动时间窗口**，这样突发的无关流量就不会触发误报，攻击者也无法仅仅通过稍微放慢速度来逃避检测。两种检测器（扫描与洪水攻击）相互独立，并针对不同的信号类型（不同端口数与原始数据包速率）进行了调优。 ## 工作原理 ``` Live TCP traffic │ ▼ packet_callback() ──filters for pure SYN packets (flags == 0x02) │ ├──> check_smart_port_scan() tracks unique ports per source IP │ over a 10s sliding window → fires if > 3 distinct ports │ └──> check_syn_flood_dos() tracks SYN rate per source IP over a 10s sliding window → fires if > 40 SYNs │ ▼ save_alert_to_json() ──appends to port_scan_report.json (ring buffer, max 500 entries) ``` ## 环境要求 - Python 3.9+ - [Npcap](https://npcap.com/) (Windows) 或 `libpcap` (Linux/Mac) - `scapy` ``` pip install scapy --break-system-packages ``` ## 用法 运行嗅探器（需要管理员/root 权限）： ``` python pyshield_sniffer.py ``` 它将在您默认的网络接口上进行监听。检测到的事件会立即输出，并被写入工作目录下的 `port_scan_report.json` 文件中。 ### 警报输出示例 ``` 🚨 [SCAN ALERT] Reconnaissance threat from 192.168.1.50. Targeted > 3 distinct ports within 10s. 🚨 [DOS ALERT] SYN Flood DoS attack from 192.168.1.50 (> 40 SYNs within 10s) ``` ### JSON 输出示例 ``` [ { "source": "packet_sniffer", "timestamp": "2026-06-21 14:02:31", "alert_type": "PORT_SCAN", "attacker_ip": "192.168.1.50", "message": "Reconnaissance threat from 192.168.1.50. Targeted > 3 distinct ports within 10s.", "status": "ALERT" } ] ``` ## 测试 有两种方法可以验证检测是否确实有效，具体取决于您想证明什么。 ### 1. 单元级测试（无需网络） `test_detection_logic.py` 会将内存中的合成的数据包直接输入到 `packet_callback()` 中，完全绕过网络协议栈。这证明了检测算法本身是正确的，不受操作系统/驱动/防火墙等环境差异的影响。 ``` python test_detection_logic.py ``` 预期结果：会输出一行 `🚨 [SCAN ALERT]` 和一行 `🚨 [DOS ALERT]`，并生成包含两条记录的 `port_scan_report.json` 文件。 ### 2. 实时网络测试（端到端） `trigger_test.py` 会向目标 IP 生成真实的 TCP SYN 数据包，并由嗅探器从网络中实际捕获 —— 这证明了整个数据处理流程是有效的，而不仅仅是检测算法。 **终端 1**（管理员权限） — 启动嗅探器： ``` python pyshield_sniffer.py ``` **终端 2** — 针对**局域网内的另一台设备**运行触发脚本（见下方说明）： ``` python trigger_test.py 10 # port-scan simulation python trigger_test.py --flood 50 # SYN-flood simulation ``` ## 配置 所有检测阈值都是 `pyshield_sniffer.py` 顶部的常量： | 常量 | 默认值 | 含义 | |---|---|---| | `TIME_WINDOW` | `10`（秒） | 两种检测器均使用的滑动窗口 | | `UNIQUE_PORTS_THRESHOLD` | `3` | 触发扫描警报前，单个 IP 访问的不同端口数量 | | `SYN_FLOOD_THRESHOLD` | `40` | 触发洪水警报前，单个 IP 发送的 SYN 数据包数量 | | `MAX_LOG_RETENTION` | `500` | JSON 报告中保留的最大警报数量（优先丢弃最旧的记录） | 将 `UNIQUE_PORTS_THRESHOLD` 设置为 `3` 是为了在测试/演示时表现出明显的灵敏度。在繁忙的实际局域网中，将其提高到 5–8 可以减少由普通多端口流量（例如浏览器向同一主机打开多个连接）引起的误报。 ## 已知的局限性 - 仅检测基于 TCP SYN 的扫描/洪水攻击 —— 目前无法检测 UDP、ICMP 或隐蔽扫描类型（FIN/NULL/XMAS）。 - `save_alert_to_json()` 每次触发警报时都会重写整个报告文件；在当前规模下没有问题，但如果要在高吞吐量的生产环境中使用，则需要改为追加写入格式（例如 JSON Lines）。 - 仅支持单主机检测 —— 目前无法关联多个嗅探器实例或主机的活动。 ## 许可证 MIT — 查看 [LICENSE](LICENSE)。

标签：DoS检测, Python, Scapy, 插件系统, 无后门, 网络安全, 网络流量嗅探, 逆向工具, 隐私保护