at0m-b0mb/AirDriver

## ⚡ 快速开始 ``` git clone https://github.com/at0m-b0mb/AirDriver cd AirDriver sudo ./install.sh # installs deps + the `airdriver` command sudo airdriver # opens the GUI ``` **不想进行全系统安装？** 直接在文件夹中运行即可： ``` git clone https://github.com/at0m-b0mb/AirDriver cd AirDriver ./run.sh # sets up a local env on first run, then launches the GUI ./run.sh scan # …or any CLI command ``` 第一次运行遇到问题？请跳转到[**故障排除**](#-troubleshooting) — 最常见 的两个问题（在 `sudo` 下无法打开 GUI，以及 Qt `xcb` 错误）都在那里得到了解决。 ## 为什么需要它 让 Alfa/Panda/TP-Link 适配器在 Kali 或 Parrot 上工作是一项必修课： 弄清芯片组，找到*合适的* DKMS 仓库（其中一半已被废弃）， 安装 kernel headers，与 Secure Boot 作斗争，将 in-tree 模块列入黑名单…… AirDriver 自动完成所有这些工作，并解释它在做什么。 它还解决了** catch-22 **困境：没有 WiFi 驱动意味着没有互联网，这意味着你 无法*下载*驱动。AirDriver 可以离线打包驱动源代码，并在气隙隔离（air-gapped）的机器上构建 它们。 ## 功能 - 🔍 **自动检测** — 枚举 USB (`lsusb`) 和 PCI (`lspci`) 适配器，从 sysfs 读取 实时的无线网络接口，并将 `VID:PID` 映射到芯片组。 - 🧠 **智能驱动选择** — 当你的 kernel 足够新时，优先使用 **in-kernel** 驱动（避免无意义的 DKMS 编译），否则依次使用 apt → DKMS-from-git → 离线包。 - 🌐 **混合在线/离线** — 连接时使用 apt/git，未连接时回退到 预先获取的离线副本。 - 🩺 **系统诊断** — 在尝试编译之前，检查 kernel headers、DKMS、构建工具、**Secure Boot** 和 root 权限，以便尽早发现故障。 - 🚫 **冲突处理** — 将劫持本应由 out-of-tree 驱动控制的适配器的 in-tree 模块（例如 `r8188eu`）列入黑名单。 - 📶 **监听模式 + 注入** — 一键启用/禁用，并提供 `aireplay-ng` 自测功能。 - 🎯 **真实的性能指标** — 每个芯片组都标明了监听模式**和**真实的 注入质量，让你在购买前就知道网卡是攻击级别的，还是 仅能用于连接。 - 🖥️ **精美的 GUI**（PySide6）**以及**完整的 **CLI**，适用于无头/SSH 环境。 - 📄 **诊断报告** — 导出 JSON + Markdown，非常适合在论坛求助帖中使用。 - ❓ **未知适配器流程** — 如果你的 `VID:PID` 尚未被收录，可以选择最接近的 芯片组进行尝试，并获得提交反馈的提醒。 ## 截图 ## 安装与运行 ### 选项 A — 完整安装（推荐） ``` sudo ./install.sh ``` 安装程序会： - 安装系统必备组件 — `dkms`、`build-essential`、kernel headers、 `usbutils`、`pciutils`、`iw`、`aircrack-ng` 等。 - 安装 GUI 所需的 **Qt 运行时库**（这是导致 *“已安装但无法打开窗口”*的常见原因）， - 创建一个隔离的 virtualenv 并安装 GUI（PySide6）， - 将一个智能的 `airdriver` 启动器放入你的 PATH 中。 然后： ``` sudo airdriver # GUI (installs run as root — smoothest) airdriver scan # CLI: list detected adapters airdriver doctor # CLI: is the system ready to build drivers? ``` ### 选项 B — 免安装运行 ``` ./run.sh # GUI (no root needed; install steps ask for sudo) ./run.sh scan # or any CLI command ``` ### 选项 C — Make targets ``` make install # = sudo ./install.sh make gui # set up a local venv and launch the GUI make scan # CLI scan make doctor # CLI readiness check make offline # pre-fetch driver sources for air-gapped use make help # list everything ``` ### 为离线使用打包驱动（请在有网时操作） ``` ./scripts/fetch_offline_drivers.sh ``` 这会将 DKMS 驱动仓库预克隆到 `airdriver/data/drivers/` 中，以便 AirDriver 稍后能在**没有网络**的机器上 构建它们。 ## 用法 ### 图形用户界面 ``` sudo airdriver # launch the graphical app ``` 从左侧的卡片中选择你的适配器，查看芯片组详情和建议的 安装计划，然后点击 **Install driver**。在 日志中观看进度流。使用 **Dry run** 可以预览而不做任何更改。**? Help** 按钮内置了 快速入门指南和故障排除工具。 ### 命令行界面 ``` airdriver scan # list detected adapters airdriver doctor # system readiness (headers, dkms, secure boot…) airdriver info 0bda:8812 # database details for a usb id / chipset id airdriver install # install driver for the first known adapter airdriver install rtl8812au --dry-run # preview the plan for a chipset airdriver install 0bda:c811 --offline # force the bundled offline driver airdriver monitor start wlan0 # enable monitor mode airdriver monitor test wlan0 # aireplay-ng injection self-test airdriver report # write a JSON + Markdown diagnostic report airdriver db # dump the chipset database ``` ## 🛟 故障排除 **运行 `sudo airdriver` 时 GUI 无法打开 / 我遇到了 Qt `xcb` 错误。** 这是头号问题，AirDriver 现在已为你自动处理： - 在 `sudo` 下运行 GUI 通常会破坏 X11 连接。AirDriver 的启动器 会自动重新连接你的桌面会话，因此 `sudo airdriver` *应该*可以直接运行。 - 如果你仍然看到 `could not load the Qt platform plugin "xcb"`，说明缺少 Qt 运行时库。 请安装它们： sudo apt install -y libxcb-cursor0 libxkbcommon-x11-0 libegl1 \ libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \ libxcb-randr0 libxcb-render-util0 libxcb-shape0 （`sudo ./install.sh` 会为你安装所有这些库。） **安装后提示 `airdriver: command not found`。** 启动器被放入了 `~/.local/bin`（非 root 安装）。将其添加到你的 PATH 中： ``` echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc ``` …或者直接重新运行 `sudo ./install.sh` 将其放入 `/usr/local/bin`，或者使用 `./run.sh`。 **尝试 `pip install` 时出现 `error: externally-managed-environment`。** 这是现代版 Debian/Kali (PEP 668) 阻止了系统级的 pip。不要与之对抗 — 请使用 `./install.sh` 或 `./run.sh`；这两者都会创建一个隔离的 virtualenv 来绕过它。 **完全没有显示界面（无头机器 / SSH）。** 完全跳过 GUI — CLI 能做任何事情：`airdriver scan`、`doctor`、`install`、 `monitor`、`report`。 **我的适配器显示为“未知”。** 选中它，在 **Identify as** 下（GUI）选择最接近的芯片组，或者运行 `airdriver install `（CLI）。请[提交一个 issue](https://github.com/at0m-b0mb/AirDriver/issues) 并提供 `VID:PID`，以便将其添加到数据库中。 ## 支持的芯片组 AirDriver 知道跨越 160+ USB/PCI ID 的 **28 个芯片组系列**。性能指标 非常真实 — 有些芯片连接正常但无法注入，AirDriver 会提前告诉你。 ### 🏆 攻击级 — 可靠的监听模式 + 注入 | 芯片组 | 典型适配器 | 频段 | 注入 | 驱动路径 | |---|---|---|---|---| | **MT7612U** | Alfa AWUS036ACM, Panda PAU09 | 2.4+5 AC1200 | **极佳** | in-kernel (4.19+) | | **RTL8187** | Alfa AWUS036H | 2.4 G | **极佳** | in-kernel | | **AR9271** | Alfa AWUS036NHA, TL-WN722N **v1** | 2.4 N | **极佳** | in-kernel + firmware | | **RTL8812AU** | Alfa AWUS036ACH | 2.4+5 AC1200 | 良好 | apt → DKMS → offline (in-kernel 6.14+) | | **RTL8814AU** | Alfa AWUS1900 | 2.4+5 AC1900 | 良好 | apt → DKMS → offline (in-kernel 6.16+) | | **AR7010** | Alfa AWUS051NH v2 | 2.4+5 N | 良好 | in-kernel + firmware | | **RT3070 / RT5370** | Alfa AWUS036NH, Panda PAU06 | 2.4 N | 良好 | in-kernel (rt2800usb) | | **RT3572 / RT5572** | Alfa AWUS051NH/052NH, Panda PAU09 | 2.4+5 N | 良好 | in-kernel (rt2800usb) | | **MT7610U** | Alfa AWUS036ACHM | 2.4+5 AC600 | 良好 | in-kernel (4.19+) | | **MT7921AU** | Alfa AWUS036AXML, Brostrend AX9L | WiFi 6E | 良好 | in-kernel (5.18+) | | **MT7925U** | Netgear A9000 | WiFi 7 | 良好 | in-kernel (6.7+) | ### 👍 可用 — 一般的注入 | 芯片组 | 典型适配器 | 频段 | 驱动路径 | |---|---|---|---| | RTL8811AU/8821AU | Alfa AWUS036ACS | 2.4+5 AC600 | apt → DKMS → offline (in-kernel 6.14+) | | RTL8811CU/8821CU | TP-Link T2U Nano/Plus | 2.4+5 AC600 | apt → DKMS → offline | | RTL8822BU/8812BU | TP-Link Archer T3U/T4U v3 | 2.4+5 AC1200 | apt → DKMS (morrownr 88x2bu) | | RTL8188EUS | TL-WN722N **v2/v3** | 2.4 N | DKMS (将 `r8188eu` 列入黑名单) | | RTL8192EU | TL-WN822N v4/v5 | 2.4 N | apt → DKMS | | RTL8852BU/8832BU | Alfa AWUS036AXM | WiFi 6 | DKMS (morrownr) / in-kernel 6.17+ | | RTL8852CU/8832CU | 通用 AXE | WiFi 6E | DKMS (morrownr) / in-kernel 6.19+ | ### 🔌 仅限连接 — 让你联网，**不**适用于攻击 | 芯片组 | 备注 | |---|---| | RTL8192CU / RTL8188CUS | Edimax EW-7811Un, TL-WN725N v2 — 监听不稳定，注入不可靠 | | RTL8723BU | WiFi+BT 组合适配器 — 仅限连接 | | RTL8188FU | 廉价微型适配器 — 监听受限 | | MT7601U | 超廉价nano适配器 — 仅限监听嗅探，**无法注入** | | AR9170 (carl9170) | 旧版 draft-N — 注入微弱 | ### 💻 内置笔记本网卡 (PCIe) — 修复“安装后无 WiFi” | 芯片组 | 备注 | |---|---| | RTL8821CE / RTL8822CE | 非常常见的 Lenovo/HP/Acer 网卡 — `rtw88`，仅限连接 | | RTL8723DE | 预算型笔记本电脑 — `rtw88`，仅限连接 | | Intel AX200 / AX201 / AX210 / AX211 | `iwlwifi` — 监听可用，注入不可靠 | ## 驱动选择的工作原理 ``` detect adapter ─► match VID:PID ─► chipset │ ┌────────────────────────┼─────────────────────────────┐ in-kernel driver exists online? offline bundle & kernel new enough │ │ present? │ yes no │ load + verify apt pkg └─► DKMS from git ◄───────────┘ (no build) (fast) (compile + dkms install) ``` 在开始任何构建之前，AirDriver 会验证是否安装了 kernel headers、DKMS 和构建工具， 警告有关 Secure Boot 的事项，并将冲突的 in-tree 模块列入黑名单。 ## 添加芯片组 整个数据库就是一个 文件 — 无需更改代码。向 [`airdriver/data/chipsets.json`](airdriver/data/chipsets.json) 添加一个条目（或者只是 向现有条目添加一个 `VID:PID`）： ``` { "id": "rtl8812au", "name": "Realtek RTL8812AU", "monitor_mode": true, "injection": true, "injection_quality": "good", "usb_ids": ["0bda:8812", "2357:0103"], "kernel_native": {"module": "rtw88_8812au", "min_kernel": "6.14"}, "drivers": [ {"method": "apt", "package": "realtek-rtl88xxau-dkms", "priority": 1}, {"method": "dkms_git", "repo": "https://github.com/morrownr/8812au-20210820", "priority": 2} ] } ``` 使用 `lsusb`（USB）或 `lspci -nn`（PCI）找到你适配器的 ID，然后提交一个 PR — 或者 带 ID 提交一个 issue，我们会将其添加进去。 ## ⚠️ 负责任的使用 AirDriver 安装驱动并切换监听模式，用于**已授权的**无线 安全测试、研究和教育。在 不属于你或没有书面测试许可的网络上使用监听模式 / 数据包注入可能是违法的。你 需对遵守法律和你的交战规则负责。 ## 项目布局 ``` AirDriver/ ├── airdriver/ │ ├── core/ # detection, database, system probes, install engine │ │ ├── chipset_db.py detector.py system.py │ │ ├── installer.py monitor.py modules.py report.py │ ├── data/chipsets.json # the chipset → driver database (28 families) │ ├── data/drivers/ # offline driver bundle (populated by script) │ ├── gui/ # PySide6 app (theme, main window) │ └── cli.py # full-featured command line ├── scripts/fetch_offline_drivers.sh ├── install.sh # full system installer ├── run.sh # zero-install quick launcher └── Makefile # convenience targets ``` ## 路线图构想 - 用于未知适配器的社区 VID:PID 提交 endpoint - 用于 Secure Boot 系统的 MOK 签名助手 - 针对单个适配器的 TX 功率 / 监管区域调整 - 可启动 USB 持久化配置文件 - AppImage / `.deb` 打包 ## 许可证 MIT © [at0m-b0mb](https://github.com/at0m-b0mb)

标签：PySide6, WiFi适配器, 应用安全, 渗透测试辅助, 逆向工具, 驱动安装