# 无线入侵检测（`ids`）

`wifisec ids` 是项目的防御视角模块：把攻击工具（deauth/brute/clone）的检测责任反向承担起来。命令启动一个持续监测会话，对空域做两类检测——**扫描差分**（免 root，全平台）与**帧级监测**（需要特权，尽力而为），覆盖五类威胁面：伪造 AP、KARMA、加密降级、泛洪（信标/去认证风暴）、弱加密与开放网络盘点。

| 检测器 | 层面 | 等级 | 平台要求 |
|:---|:---|:---|:---|
| 伪造 AP（Evil Twin） | 扫描差分 | 警告 | 免 root；macOS 需定位授权拿 BSSID |
| KARMA（同一 BSSID 宣称多 SSID） | 扫描差分 | 严重 | 同上 |
| 加密降级（WPA3→WEP 等） | 扫描差分 | 严重 | 同上 |
| 弱加密 / 开放网络 | 扫描差分 | 警告 / 提示 | 免 root |
| 去认证 / 解除关联风暴 | 帧级监测 | 严重 | Linux monitor VIF（root）或 macOS BPF（sudo/access_bpf 组） |
| 信标泛洪（beacon flood） | 两层 | 严重 | 扫描面免 root；帧面需特权 |

## 获取二进制

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

其他获取方式见仓库 README。

## 1. 用法

```bash
wifisec ids                  # 全空域持续监测到 Ctrl-C
wifisec ids 3600             # 监测 1 小时后自动收尾
wifisec ids 'MyWiFi'         # 锁定单个 SSID：只评估它的差分与针对它的风暴
wifisec ids 'MyWiFi' 3600    # 锁定 + 定时
wifisec ids en0              # 指定帧级监测绑定的网卡
```

参数按位置语义解析：纯整数是秒数（0 与缺省 = 持续到 Ctrl-C）；其余 token 先按网卡名试探（系统里存在即网卡），否则视为要锁定的 SSID。

**锁定模式**（推荐企业值守使用）：启动时先用一轮扫描把 SSID 解析成 BSSID 集与信道集——之后扫描差分只评估该 SSID（伪装者、降级、KARMA），帧级风暴检测只统计收发双方命中目标 BSSID 的帧，Linux monitor 跳频钉在目标信道不再全频段轮转。泛洪类检测保持全局（泛洪波及整个空域，不因选定目标而豁免）。目标当前不可见会直接报错退出，不空转；macOS 未授权定位导致 BSSID 被系统隐藏时，锁定退化为纯 SSID 匹配并明确提示。

## 2. 输出示例（真机）

```text
18:33:58 [警告] 监测仅限自有网络或已获书面授权的环境
18:34:03 [信息] 接口 en0 链路为以太网视角（DLT 1），空中管理帧不可见；已降级为仅扫描差分
18:34:03 [信息] 无线入侵检测启动（扫描差分）· 扫描间隔 15s · Ctrl-C 结束
18:34:03 [信息] 基线已建立（首轮扫描不做差分），进入持续监测
[严重] 14:32:01 伪造AP · MyWiFi — SSID 出现第二个 BSSID BB:00:…（信道 6 · WPA2），与已知基线配置不一致，疑似 Evil Twin
[严重] 14:33:40 去认证风暴 · AA:00:… — 10 秒内 12 帧（阈值 12），目标为本机——你的连接正在被强制断开
18:35:20 [信息] 检测结束：追踪 12 个 BSSID · deauth 47 帧 · disassoc 0 帧 · 告警 2 条
18:35:20 [信息] 告警分布：伪造AP 1 · 去认证风暴 1
18:35:20 [警告] 重点来源 AA:00:…：deauth×47 · disassoc×0
```

告警行按等级着色：**严重=红、警告=黄、提示=灰**。设计原则是"宁可少报、报了必有证据"——每条告警的 Detail 都带着触发依据（阈值数字、配置差异、目标 MAC），可直接进工单或交接给网络管理员。

## 3. 检测器原理

### 3.1 扫描差分引擎（免 root）

引擎维护以 BSSID 为键的基线（SSID/信道/安全等级），每 15 秒一轮快照对比。**首轮只建基线不做差分**——没有参照物的差分全是误报。

- **伪造 AP**：SSID 已被其他 BSSID 占用，且新 BSSID 与基线成员**同频段**但信道或安全等级不一致 → 警告。两个关键豁免：跨频段（2.4GHz 与 5GHz 各起一个 BSSID 是双频路由器的默认拓扑，静默记录不告警）；同频段且配置完全一致（更像 Mesh/漫游组，只给提示）。SSID 一旦出现过伪造成员，后续任何新成员与伪造者必然配置冲突，继续按警告从严处理。
- **KARMA**：同一 BSSID 累计宣称 6 个以上不同 SSID → 严重。合法 AP 终生只用一两个 SSID，KARMA 工具应答任意探测请求会轻松越线。隐藏网络（空 SSID）不参与统计。
- **加密降级**：同一 BSSID 的安全等级（0=开放、1=WEP、2=WPA/TKIP、3=WPA2-CCMP、4=WPA3）下跌 → 严重。信道变化是正常的（DFS/RRM），不参与判定。
- **泛洪（扫描面）**：单轮快照全新 BSSID ≥ 30 → 严重。mdk4 等工具每秒伪造数百个 BSS，正常空域很难单轮出现 30 个新邻居。
- **弱加密/开放盘点**：WEP → 警告（可离线破解），WPA/TKIP → 提示，开放 → 提示；每个 BSSID 只报一次。

安全等级用包含匹配而不是等值比较（iw 输出 `WPA2-PSK-CCMP`、macOS 输出 `WPA2/WPA3`、netsh 又是另一套口径）；识别不了时保守给 WPA2 级，不制造降级误报。

### 3.2 帧级监测引擎（尽力而为）

拿到原始 802.11 管理帧时叠加以下检测（实现于 `internal/ieee80211` 的解码 + `internal/wids` 的滑窗计数）：

- **去认证/解除关联风暴**：同一发送方 10 秒滑动窗口内 ≥ 12 帧 → 严重（同源冷却 60 秒防刷屏）。证据行区分三种目标：**本机**（receiver 命中本机 MAC——你正在被强制断开的直接证据）、广播（波及整个 BSS）、单播（点名目标）。
- **信标泛洪（帧面）**：10 秒内 ≥ 40 个去重发送方在打信标 → 严重。
- 计数表有 512 发送方的状态上限：攻击者可用随机 MAC 灌爆内存，超限整体重建——泛洪本身已由泛洪检测覆盖。

帧源的 DLT 分诊是**诚实降级**而非假装检测：

| 场景 | DLT | 结果 |
|:---|:---|:---|
| Linux monitor VIF（root） | 127（radiotap） | 完整帧级监测，2 秒跳频覆盖 2.4/5GHz |
| macOS BPF sudo（连接态） | 127 或 1 | 127 时可检测针对本机的 deauth 与当前信道信标 |
| 连接态以太网视角 | 1 | 如实打印"管理帧不可见"，降级为纯扫描差分 |
| Windows Npcap | 1 或 127 | 同上分诊 |

## 4. 平台能力矩阵与排错

| 现象 | 原因 | 处理 |
|:---|:---|:---|
| "已降级为仅扫描差分" | 帧源不可用或 DLT 为以太网 | Linux `sudo` 建 monitor VIF；macOS `sudo` 或把用户加入 `access_bpf` 组 |
| Linux 建口失败 | 缺 iw 或无 CAP_NET_ADMIN | `apt install iw` + `sudo` 运行 |
| macOS 全程"追踪 0 个 BSSID" | 未授权定位，系统隐藏周边 BSSID | 系统设置 → 隐私与安全性 → 定位服务 → 允许 wifisec；未授权时差分检测退化为仅安全盘点 |
| 大量"快照 #N"刷屏属正常 | 每轮扫描的心跳行，证明监测活着 | 告警行永远优先于心跳行出现 |
| deauth 告警但源是自家 AP | AP 在负载均衡/漫游引导时也会发管理帧 | 看证据行的帧数与目标：攻击是持续高频且指向性强；结合 `clone` 做对抗演练前先排除自家设备 |
| 想要 7×24 常驻 | 本命令面向人工值守与渗透演练对照 | 常驻部署建议配合 systemd/launchd 拉起并重定向日志 |

## 5. 阈值与可信度

所有阈值集中在 `internal/wids/wids.go` 常量区，调参时必须同步更新本节：

| 阈值 | 默认值 | 出处 |
|:---|:---|:---|
| 扫描快照泛洪 | 30 个新 BSSID/轮 | mdk4 beacon flood 每秒数百，正常商圈空域单轮极少超过 |
| KARMA | 6 个 SSID/BSSID | 合法 AP 终生 1-2 个 SSID |
| deauth 风暴 | 12 帧/10 秒/发送方 | 正常漫游偶发 deauth；高频集中单窗口是攻击特征 |
| 信标泛洪（帧面） | 40 发送方/10 秒 | 正常空域 10 秒内打信标的去重 BSS 数远低于此 |
| 告警冷却 | 5 分钟（风暴类 60 秒） | 防止同类告警刷屏淹没终端 |

误报可解释（每条告警带证据）、漏报有边界（跳频间隙与扫描间隔的盲区如实记录）——这是把 wifisec 放进企业值守流程的底气。

## 6. 部署形态与边界

- **企业自部署**：在一台常开的 Linux 机器上 `sudo wifisec ids` + systemd 拉起，即是最低成本的空域哨兵；配合 `ids 3600` 定时任务做巡检亦可。
- **渗透演练对照**：跑 `deauth`/`clone` 前先在另一台机器开 `ids`，攻击开始后 IDS 应当报警——这既是工具自检，也是给客户演示"攻击可被看见"的最直观方式。
- **单网卡物理边界**：一台机器只有一个射频前端时，跳频存在盲区（monitor 在 A 信道时 B 信道的帧不可见）；要无盲区覆盖需要多射频或专用传感器。ESP 协处理器的 promiscuous 嗅探是规划中的传感器路线。
- **隐私边界**：扫描差分记录的是周边网络的元数据（SSID/BSSID/信道/加密方式），不涉及任何用户通信内容；帧级监测只解析管理帧的 MAC 头与 SSID 元素，不触数据帧载荷。即便如此，部署点仍应限定在自有场所或已获书面授权的环境。

## 7. 法律红线

无线入侵检测本身是被动的监听与比对，但部署位置决定合法性边界：在自家/自家企业场所部署是正当防卫措施；在他人网络或公共场所做持续监测并留存他人设备指纹，可能违反《中华人民共和国个人信息保护法》与《刑法》第二百八十五条。检测记录只用于防护目的，不得用于追踪定位第三方设备。
