# 在线密码字典爆破（`wifisec brute`）

`wifisec brute` 把密码字典逐条交给无线芯片执行真实关联尝试，命中即停并输出密码。它是**在线破解**（online attack）路径：每次都走完整的 WPA 四次握手，由 AP 亲自判定密码对错，而不是离线猜测。

**两条执行路径自动选择**：插入 ESP 开发板时走协处理器（关联跑在板载射频上，不碰本机网络配置，支持 SSID 与 BSSID 目标）；未检测到设备时回落**本机无线网卡**（macOS `networksetup` / Linux `nmcli` / Windows `netsh`，仅支持 SSID 目标，爆破期间本机 WiFi 会反复断开重连）。Android（Termux）未 root 时系统禁止编程关联 WiFi，只能走 ESP 路径。

固件烧录与串口排错见 [wifi_deauth.md §5.4-§5.5](wifi_deauth.md)；串口发现见 [wifi_serial.md](wifi_serial.md)。

## 获取二进制

```bash
go install github.com/ctkqiang/wifisec/cmd/wifisec@latest
```

其他获取方式（Release 下载、源码编译）见仓库 README。

## 1. 功能定位

`brute` 回答的问题是：**「这个 AP 的密码在不在这本字典里」**。它只适用于：

- 自有网络的口令强度自查——验证管理密码是否弱到能被常见字典一击命中；
- 已获书面授权的渗透测试——在授权范围内评估目标 AP 的口令策略。

它**不适用**于大字典硬刚：在线破解的吞吐被 AP 的应答速度钉死在每次 2-5 秒，百万级字典需要数天，且 AP 侧的限速与锁定会让后期尝试全部超时。需要大字典时应当走离线握手破解路线（见 §7）。

## 2. 用法

```bash
wifisec brute <ssid|bssid> with-pass: <字典文件> [串口]
```

| 参数 | 说明 |
|:---|:---|
| `<ssid|bssid>` | 目标。BSSID 时先在扫描结果中反查对应 SSID，再按 SSID 发起关联 |
| `with-pass: <字典文件>` | 密码字典路径。`with-pass:` 关键字可省略（直接传路径），大小写不敏感，冒号可有可无 |
| `[串口]` | 可选。缺省自动探测唯一 USB 串口；多板插入时按 `wifisec serial` 输出手动指定 |

示例：

```bash
wifisec brute 'MyWiFi' with-pass: pass.txt                          # 按 SSID
wifisec brute 01:23:45:67:89:ab with-pass: pass.txt                 # 按 BSSID
wifisec brute 'MyWiFi' pass.txt /dev/cu.usbserial-XXXX              # 省略关键字 + 指定串口
```

## 3. 字典格式

纯文本、每行一个候选密码：

```text
# 常见弱口令字典（# 开头为注释行，自动跳过）
12345678
password
admin123

87654321
```

规则：

- 空行与 `#` 开头的注释行自动跳过；
- 每行首尾空白自动剔除；
- **不去重、不重排**——字典可能有意重复以观察 AP 的失败计数行为，保持原始顺序与频次；
- WPA 密码合法区间为 8-63 字节，越界的条目仍会尝试（部分 AP 对非法长度直接拒绝，也视为失败）。

## 4. 执行流程与输出判读

```
[信息] 字典 pass.txt 加载完成：4 个候选密码
[警告] 未检测到 ESP 协处理器，回落到本机无线网卡（darwin）
[警告] 爆破期间本机 WiFi 会反复断开重连，当前网络连接将不可用
[信息] 开始爆破 SSID："MyWiFi"
[警告] 在线爆破模式：每次尝试约 2-5 秒，AP 可能在多次失败后限速；仅用于授权测试
[信息] [1/4] 失败："123456"（14.3s）
[信息] [2/4] 失败："password"（15.4s）
[信息]
════════════ 爆破成功 ════════════
  SSID   : MyWiFi
  BSSID  : aa:bb:cc:dd:ee:ff
  密码   : correcthorse
  尝试   : 3/4 · 总耗时 41s
═══════════════════════════════════
```

| 输出 | 含义 |
|:---|:---|
| `[n/total] 失败："xxx"（Ns）` | 该密码被 AP 拒绝（或超时/关联验证未通过），带本次尝试耗时，继续下一个 |
| `尝试 X 出错` | 串口/固件层异常（非密码判定结果），该条跳过不重试 |
| `爆破成功` 凭证块 | 关联验证通过，命中即停——SSID、BSSID、密码、尝试序数与总耗时一次给齐 |
| `字典遍历完毕，未找到正确密码` | 字典内无答案；注意区分「密码不在字典」与「AP 已限速」（见 §6.2） |

凭证块中 BSSID 的来源按路径分级：

| 来源 | 适用路径 | 说明 |
|:---|:---|:---|
| 扫描结果带出 | ESP 协处理器 | 定位目标时扫描条目自带 BSSID |
| 关联当下缓存 | 本机网卡 | 验证关联成功的一瞬间向系统回查——Linux/Windows 命中后临时配置立即清理，事后查询现场已不存在 |
| 如实标注「未知」 | 兜底 | macOS 未授权定位时系统把 BSSID 脱敏为 `<redacted>`，不猜不编 |

执行中 Ctrl-C 可随时终止；串口句柄随进程退出释放。

## 5. 协议细节（0x03 关联命令）

`brute` 复用 deauth 的同一根串口与同一份固件，新增一对命令/回复：

| cmd | 方向 | 含义 | payload |
|:---|:---|:---|:---|
| `0x03` | 主机→ESP | 关联尝试 | ssidLen(1) + ssid + passLen(1) + password |
| `0x03` | ESP→主机 | 关联结果 | result(1)：0 = 失败/超时，1 = 成功 |

固件侧行为（`handleAssoc`）：

1. 校验 payload 长度三段式布局，畸形直接回 `REP_ERROR`；
2. `WiFi.begin(ssid, pass)` 发起关联，最长轮询 **12 秒**（覆盖多数 AP 的拒绝应答窗口），超时按失败处理；
3. 回 `REP_ASSOC_RESULT` 后**立即 `WiFi.disconnect()`**——只需要知道密码对错，不需要真正上网；保持连接会占用 STA 资源影响后续扫描/注入；
4. 关联期间板载 LED 常亮（与扫描态一致），结束恢复心跳。

主机侧 `Associate()` 的读取预算为 15 秒 = 固件 12 秒上限 + 3 秒串口回传余量。

> 旧固件不含 `0x03` 命令：收到后会回 `REP_ERROR(出错命令, 0xFF)`，主机报「固件执行关联命令失败」——按 README 固件烧录章节重刷最新固件即可。

## 6. 局限与对抗

### 6.1 为什么是「每个密码 2-5 秒」

在线尝试的耗时大头不在串口也不在固件，而在 **AP 的应答**：密码错误时，多数 AP 不会立即拒绝，而是让握手在 EAPOL 阶段沉默超时，这个窗口通常 2-5 秒。主机与固件都无法压缩它——这是 802.11 协议行为，不是实现缺陷。

### 6.2 AP 限速与锁定

企业级与较新的家用 AP 普遍带暴力破解防护：连续失败 3-10 次后对该 STA 的 MAC 限速或直接拉黑数分钟。现象是**后期尝试全部超时失败**——此时「字典遍历完毕未命中」不等于字典里没有，需要换 STA MAC（换一块板子/改固件 MAC）后分段重试。wifisec 当前固件按板子真实 MAC 关联，未做 MAC 随机化。

### 6.3 WPA3 / SAE

WPA3 的 SAE（Dragonfly）握手设计目标之一就是抗在线爆破：每次失败的计算成本更高、AP 侧普遍强制限速。对 WPA3 目标的命中率显著低于 WPA2，属预期行为。

### 6.4 隐藏 SSID

目标是 BSSID 且对应 AP 隐藏 SSID 时，扫描结果中 SSID 字段为空，反查失败会直接报「未找到目标」。隐藏网络的在线破解需要先经其他渠道获知 SSID。

## 7. 与离线破解的边界

| | 在线（本命令） | 离线（aircrack 路线） |
|:---|:---|:---|
| 原理 | 逐密码真实关联，AP 判定 | 抓取握手包，本地算 PBKDF2 比对 MIC |
| 吞吐 | 2-5 秒/次 | 数千至数十亿次/秒（GPU） |
| 对 AP 的压力 | 高（触发限速/告警） | 零（抓包被动） |
| 前置条件 | 无需 | 需 monitor 抓包能力 + 捕获到完整握手 |

wifisec 当前固件未实现 monitor 抓包回传，离线路线不在能力范围内；在线路径的价值在于**零抓包依赖、插上板子就能验**。

## 8. 排错

| 报错/现象 | 原因 | 处理 |
|:---|:---|:---|
| `缺少字典文件参数` | 未传 `with-pass:` 路径 | 按 §2 用法补齐 |
| `打开字典文件 ... 失败` | 路径错误或权限不足 | 确认路径；Termux 下注意 `~/storage` 需先 `termux-setup-storage` |
| `字典文件为空` | 字典全是空行/注释 | 检查文件内容 |
| `未找到目标` | ESP 路径下目标不在信号范围，或隐藏 SSID（§6.4） | 先用 `wifisec list` 或 `deauth` 的扫描确认目标可见 |
| `固件执行关联命令失败` | 固件过旧，不含 `0x03` 命令 | 重刷最新 `core/esp/esp.ino` |
| `等待关联结果超时` | 串口链路中断或固件死机 | 重插板子；观察板载 LED 是否仍有心跳 |
| `未找到 nmcli` | Linux 本机路径依赖 NetworkManager | 安装 `network-manager`，或插 ESP 走协处理器路径 |
| `Android 未 root 无法编程关联 WiFi` | Android 10+ 系统限制 | 只能插 ESP 走协处理器路径 |
| `本机网卡路径仅支持按 SSID 爆破` | 本机路径无法按 BSSID 反查 | 改用 SSID 作目标，或插 ESP |
| 全部尝试连续超时 | AP 已限速/锁定（§6.2） | 暂停数分钟或换板后分段重试 |

### 本机网卡路径的补充说明

- **macOS**：经 `networksetup -setairportnetwork` 发起关联，采用**两段式判定**——该命令返回 0 仅代表 join 请求被系统受理，不代表关联完成；必须再轮询 `-getairportnetwork`（最长 10 秒）确认接口真实接入目标 SSID 才算命中，杜绝「受理了但没连上」的假阳性。密码错误时输出「Failed to join」直接按失败处理；失败尝试不会写入钥匙串，但当前已连的 WiFi 会被断开。
- **Linux**：经 `nmcli` 用固定名 `wifisec-brute` 的**一次性连接配置**尝试，无论成败都删除——不会污染系统里你自己的同名 SSID 配置。`--wait 15` 压缩了 NetworkManager 默认 90 秒的激活等待。
- **Windows**：`netsh` 导入临时 WLAN 配置发起连接，`connect` 返回只代表请求受理，成败靠轮询 `netsh wlan show interfaces` 判定（最多 12 秒）；配置用完即删。
- 三者命中后都**不主动保留连接**：本机路径命中意味着本机已连上目标网络，不需要继续时手动断开即可。

串口级排错（找不到板子、端口占用、74880 乱码）与 deauth 完全相同，见 [wifi_serial.md §6](wifi_serial.md) 与 [wifi_deauth.md §5.5](wifi_deauth.md)。

## 9. 法律红线

在线爆破对目标 AP 产生真实认证流量，属于「尝试侵入网络」的主动行为。《中华人民共和国网络安全法》第二十七条与《刑法》第二百八十五条第三款同样适用于本功能——**仅限自有网络或已获书面授权的目标**。自用路由器验字典强度是合法典型场景；对邻居、公共场所、任何第三方 AP 使用即越线。
