Huelbeque/wardriving-scanner
GitHub: Huelbeque/wardriving-scanner
一款结合 GPS 定位的被动式 Wi-Fi 侦察扫描器，用于捕获并解析周围无线网络的广播帧，在实时地图仪表盘上揭示加密弱点与设备隐私泄露问题。
Stars: 0 | Forks: 0
# wardriving 扫描器
这是一个用于带有 GPS 标记的被动 Wi-Fi 侦察的教育项目，是我在学习网络安全期间编写的。其核心完全在于**被动观察** —— 捕获设备已经通过空气广播的内容，对其进行解析，并揭示隐私/安全问题（弱加密、IoT 设备泄露已知 SSID 等），而不是执行任何主动攻击。
## 目录
- [使用的硬件](#hardware-used)
- [功能](#features)
- [技术栈](#stack)
- [项目结构](#project-structure)
- [安装说明](#installation)
- [硬件设置](#hardware-setup)
- [运行扫描器](#running-the-scanner)
- [运行仪表盘](#running-the-dashboard)
- [设备追踪模式](#device-tracking-mode)
- [用于 Wireshark 的数据包捕获](#packet-capture-for-wireshark)
- [负责任的使用](#responsible-use)
## 使用的硬件
| 组件 | 型号 | 备注 |
|---|---|---|
| Wi-Fi 适配器 | TP-Link TL-WN722N **v1** | Atheros AR9271 芯片，支持通过 `ath9k_htc` 驱动的监控模式 + 数据包注入。**v2/v3 使用不同的芯片，不支持监控模式** —— 版本非常重要。 |
| GPS 接收器 | 通用 USB "G-Mouse" | u-blox 7 芯片，通过 USB-CDC 虚拟串行端口输出标准 NMEA 0183 语句 |
| 计算 | Jetson Nano | 运行扫描器和仪表盘；任何 Ubuntu 机器也可以 |
## 功能
- 将外部 Wi-Fi 适配器置于监控模式，而不会禁用系统其余的网络功能（仅目标接口会与 NetworkManager 分离）
- 在 2.4 GHz 信道（1–13）之间进行信道跳频，从而捕获附近所有网络的 beacon，而不仅仅是一个信道
- 捕获 **beacon 帧**：SSID、BSSID、信道、RSSI、供应商（针对 IEEE OUI 数据库进行 OUI 查询）
- 直接从 RSN/WPA 信息元素中进行完整的加密解析：WEP / WPA / WPA2 / WPA3，PSK / Enterprise (802.1X) / SAE，以及特定的加密套件（TKIP, CCMP, GCMP...）
- 捕获来自客户端设备的 **probe request** 并标记隐私泄露 —— 设备广播其先前连接到的网络名称，同时带有非随机化（真实）的 MAC 地址
- 基于供应商 OUI（Espressif, Raspberry Pi Foundation, Sonoff, Tuya 等）的启发式 **IoT 设备分类**
- 在后台线程中读取 NMEA 语句，用 **GPS 坐标**实时标记每一次观察
- 将每次观察存储在 **SQLite** 中（WAL 模式，因此扫描器可以在仪表盘并发读取时进行写入）
- 实时 **Web 仪表盘**（FastAPI + Leaflet）显示：
- 附近网络的实时表格（SSID、供应商、信道、RSSI、加密方式）
- 带有 IoT 标识的 probe-request "泄露" 实时表格
- 自动居中并自动缩放以适应具有 GPS 定位的每个网络的地图
- 一个独立的 **设备追踪器**（`track.py`），它显示特定 MAC 地址的实时 RSSI 柱状图 —— 非常适合通过走动并观察信号强度变化来物理定位设备
- 一个独立的 **捕获工具**（`capture_for_wireshark.py`），它将来自/发往某个 MAC 地址的所有流量记录到 `.pcap` 文件中，以便在 Wireshark 中进行更深入的分析
## 技术栈
Python 3 · [scapy](https://scapy.net/) · pyserial · pynmea2 · FastAPI · Uvicorn · SQLite · [Leaflet.js](https://leafletjs.com/)（通过 CDN，无需构建步骤）
## 项目结构
```
wardriving-scanner/
├── main.py # scanner entry point (WiFi + GPS + DB, all together)
├── track.py # live RSSI tracker for locating one specific device
├── capture_for_wireshark.py # capture one MAC's traffic to a .pcap file
├── wifi/
│ ├── adapter.py # monitor mode, channel switching
│ ├── sniffer.py # beacon + probe request capture, channel hopping
│ ├── encryption.py # RSN/WPA Information Element parsing
│ └── vendor.py # OUI lookup + IoT heuristic
├── gps/
│ └── reader.py # background NMEA reader over serial
├── storage/
│ └── database.py # SQLite schema, inserts, queries
├── dashboard/
│ ├── server.py # FastAPI app (serves the API + static files)
│ └── static/
│ └── index.html # Leaflet map + live tables (vanilla JS, no build step)
├── ui/
│ └── console.py # colored console output helpers
├── utils/
│ └── prompts.py # check_root() and other CLI helpers
├── data/ # SQLite DB + cached OUI database (gitignored)
├── requirements.txt
└── .gitignore
```
## 安装说明
```
git clone https://github.com//wardriving-scanner.git
cd wardriving-scanner
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
如果 `pip install` 报错 "externally-managed-environment"，请确保虚拟环境已经**激活**（`source venv/bin/activate` —— 用 `which pip` 检查，它应该指向 `venv/` 内部）。
## 硬件设置
### Wi-Fi 适配器
插入 TL-WN722N 并确认系统已识别到它：
```
iw dev
```
你应该会看到一个以 `wlx...` 开头的接口。扫描器会自动检测它（`WifiAdapter.auto_detect()`），无需手动配置。
### GPS 接收器
插入 GPS 模块并检查它是否被识别：
```
lsusb
```
寻找类似 `U-Blox AG [u-blox 7]` 的条目。找到它的串行端口：
```
ls /dev/ttyUSB* /dev/ttyACM*
```
u-blox 7 接收器通常显示为 `/dev/ttyACM0`。如果端口没有出现，请检查：
```
dmesg | tail -20
```
由于扫描器在 `sudo` 下运行（监控模式所必需），它会自动拥有对 GPS 串行端口的访问权限 —— 主扫描器不需要额外的权限设置。如果你想**在无** `sudo` 的情况下独立测试 GPS 读取器，请将你的用户添加到 `dialout` 组：
```
sudo usermod -a -G dialout $USER
# 然后注销并重新登录，或者运行：newgrp dialout
```
如果你的 GPS 端口不是 `/dev/ttyACM0`，请在构造 `GpsReader(port=...)` 的 `main.py` 中更新该端口。
## 运行扫描器
扫描器需要 root 权限才能将 Wi-Fi 适配器置于监控模式：
```
sudo venv/bin/python3 main.py
```
**注意：**使用 `sudo venv/bin/python3`，而不是 `sudo python3` —— 单纯的 `sudo` 会使用系统 Python，而不是你虚拟环境中的 Python，这将导致找不到已安装的依赖。
你将看到检测到的每个网络和每个 probe request 泄露的实时输出：
```
[CH 6] MyHomeNetwork (ac:84:c6:81:53:f0) Vendor=TP-Link RSSI=-58 ENC=WPA2-PSK (CCMP) [48.53261, 35.83991]
[PROBE LEAK] [IoT?] 0c:dc:7e:c4:d4:34 (Espressif Inc.) RSSI=-66 is looking for: "SomeSSID"
```
按 `Ctrl+C` 停止 —— 适配器将自动恢复到 managed 模式，并且 GPS 读取器将被干净地关闭。
如果是首次运行，OUI 供应商数据库（约 10-15MB）将被下载并缓存在 `data/oui.csv` 中，以便后续运行能更快启动。
## 运行仪表盘
仪表盘是一个**独立的进程**，它只从同一个 SQLite 数据库读取数据 —— 它可以独立于扫描器启动/停止，并且不需要 root 权限：
```
venv/bin/uvicorn dashboard.server:app --reload --port 8000
```
在浏览器中打开 **http://127.0.0.1:8000**。你将看到：
- 检测到的网络的实时表格，每 2 秒更新一次
- probe request 泄露的实时表格，并为可能的 IoT 设备带有 "IoT?" 标识
- 一个地图，为每个具有 GPS 定位的网络显示标记，并在坐标第一次出现时自动适应数据
如果你遇到 `readonly database` 错误，这几乎总是因为扫描器（以 root 身份运行）和仪表盘（以你的普通用户身份运行）之间的文件权限不匹配：
```
sudo chown -R $USER:$USER data/
```
## 设备追踪模式
要通过带着适配器走动并实时观察信号强度来物理定位特定设备（由其 MAC 地址标识）：
```
sudo venv/bin/python3 track.py
```
这会在终端中显示一个实时更新的 RSSI 柱状图。你还可以随时按 Enter 键记录带有标签（例如“靠近窗户”）的当前读数，从而构建一个包含不同物理位置 RSSI 读数的小型 CSV（`rssi_log.csv`）—— 这对于粗略三角测量设备隐藏的位置很有用。
## 用于 Wireshark 的数据包捕获
要记录来自/发往特定设备的所有帧，以便在 Wireshark 中进行详细检查：
```
sudo venv/bin/python3 capture_for_wireshark.py
```
这将捕获 60 秒，并将所有内容保存到项目根目录的 `iot_capture.pcap` 中。在以普通用户身份打开它之前，请修复文件所有权：
```
sudo chown $USER:$USER iot_capture.pcap
```
用于隔离 probe request 的有用 Wireshark 过滤器：
```
wlan.fc.type_subtype == 0x04
```
## 负责任的使用
本项目完全出于教育目的而构建 —— 旨在了解 802.11 协议并练习**被动**网络侦察。它：
- **不**执行任何主动攻击（deauth 洪水、evil twin 接入点、密码暴力破解、WPS PIN 攻击等）
- 仅捕获已经公开广播的内容（beacon 和 probe request 帧）—— 它从不尝试解密任何人的流量
- 旨在用于研究**你自己的**网络，或你拥有明确测试许可的网络/场所
在大多数司法管辖区，使用此代码 —— 或其展示的技术 —— 未经授权访问你不拥有或没有测试许可的网络、设备或场所是违法的。作者对任何滥用此代码的行为概不负责。
标签：WiFi侦察, 信号监测, 教育项目, 网络安全, 防御绕过, 隐私保护