Sparrow-WiFi 是一个用于 Linux 的 2.4 GHz 和 5 GHz WiFi 及蓝牙频谱感知工具。它集成了 WiFi 扫描、蓝牙低功耗（BLE）和经典蓝牙发现、软件定义无线电频谱分析（HackRF、Ubertooth）、GPS 追踪、FAA RemoteID 无人机检测、无人机/漫游车远程操作，以及将 ECS 8.17 索引到 Elasticsearch 或 OpenSearch，统一在一个平台上。完全使用 Python 3 编写。
该项目包含四个可独立或协同工作的组件：
| 组件 | 界面 | 用途 |
|---|---|---|
| Sparrow-WiFi | PyQt5 桌面 GUI | WiFi/BT 扫描、频谱分析、源追踪、战争驾驶 |
| Sparrow Agent | 无头 HTTP 服务器 | 远程扫描、无人机/漫游车部署、第三方集成 |
| Sparrow DroneID | 基于 Web（浏览器） | 通过 WiFi 和蓝牙低功耗进行 FAA RemoteID 无人机检测 |
| Sparrow Elastic Bridge | 无头 CLI 服务 | 将 WiFi/BT 观测数据以 ECS 8.17 索引到 Elasticsearch / OpenSearch |
Sparrow Agent 和 Sparrow DroneID 暴露 JSON REST API，允许其他应用程序查询扫描结果、触发扫描、获取无人机检测信息，并将无线/无人机感知集成到自己的工作流程中。Elastic Bridge 消耗代理的 REST API，并发送带有捆绑 Kibana 仪表板的 ECS 8.17 文档。
此版本相较于先前版本包含三项重大改进：
/wireless/networks/<iface> 时，代理先前会启动 N 个冗余的 iw scan 调用，这些调用在接口锁上串行化，导致扫描延迟随客户端数量倍增。现在第一个请求成为实际扫描的“领导者”；并发请求等待 threading.Event 并共享领导者的结果。还包含锁创建时的 TOCTOU 修复以及接口锁的异常安全性。droneid.* 命名空间），以及多设备响应式 Web UI。请参见下面的 Sparrow DroneID 部分。sparrow-elastic.py 桥接已被重写，现在生成 ECS 8.17 文档（之前为 ECS 1.5），同时支持 Elasticsearch 8.x 和 OpenSearch 2.x，自动引导可组合索引模板（含 ILM/ISM 生命周期策略和滚动写入别名），执行 OUI 供应商丰富和基于规则的设备分类（可选 Fingerbank 指纹识别），并打包四个捆绑的 Kibana 仪表板以及六个保留的旧版可视化。旧版 ECS 1.5 桥接保留在 legacy/sparrow-elastic.py。请参见 Elasticsearch / OpenSearch 集成。原始的 Sparrow 应用程序提供了一个全面的基于 GUI 的替代工具，如 inSSIDer 和 LinSSID，其功能远超基本扫描：
sparrowwifiagent.py），用于分布式扫描、无人机/漫游车操作以及 Raspberry Pi 部署iw scan 输出
一个独立的基于 Web 的无人机检测与追踪系统，能够解码 FAA 强制要求的远程识别（RemoteID）广播。作为 Python HTTP 服务器运行，带有基于浏览器的 UI，可从网络上的任何设备访问。
启动后 Web UI 运行在 http://localhost:8097。请参阅下面的 安装 了解设置，以及 API 参考 了解编程接口。
除了 Slack webhook，Sparrow DroneID 还可将每次触发的告警 POST 到 一个通用的外部告警接收端点。该通道默认禁用； 请在“设置” → “告警” → “基于 API 的告警”中配置：
http://MY_API_HOST:PORT/API_ROOTAuthorization: Bearer ... 头中发送；存储后在 UI 中隐藏rule.category: "test"，序列号 TEST-0000），以便端到端测试接收方，无需等待真实无人机Sparrow DroneID 向配置的根 URL 发起两个调用：
| 动词 | 路径 | 用途 |
|---|---|---|
POST | {root}/v1/alerts/verify | 凭据检查 — 请求体 {"domain": "<配置的>"}。接收方应在成功时回复 200 {"status":"ok"}，令牌错误时回复 401。 |
POST | {root}/v1/alerts | 触发告警 — 请求体为下方 JSON。接收方应在成功时回复 201 {"alert_id":"..."}。503 响应将使用指数退避重试（最多 3 次）；4xx 则中止不重试。200 {"status":"dropped"} 表示该域在上游被禁用。 |
两个调用都发送 Authorization: Bearer <token> 和 Content-Type: application/json。
{ "domain": "", "alert": { "message": "", "observer": { "name": "<operator_name or 'Sparrow DroneID'>", "type": "drone-sensor", "geo": {"location": {"lat": 0.0, "lon": 0.0}} }, "rule": {"name": "", "category": "drone_detection"}, "event": { "severity": 40, "category": "network", "action": "new_drone" }, "labels": { "serial": "", "vendor": "", "ua_type": "", "alert_type": "new_drone | altitude_max | speed_max | signal_lost" }, "source": {"geo": {"location": {"lat": 0.0, "lon": 0.0}}}, "details": { "operator_id": "...", "registration_id": "...", "self_id_text": "...", "mac_address": "...", "protocol": "...", "rssi": -68, "range_m": 1234.5, "bearing_deg": 215.0, "bearing_cardinal": "SW", "speed_mps": 5.2, "direction_deg": 240.0, "altitude_m_agl": 42.0, "detail": "..." } } }
`observer.geo.location` 在接收器获得GPS定位时包含；`source.geo.location` 在无人机广播位置时包含。严重性遵循ECS约定（数值越低越紧急）：警告（`new_drone`、`altitude_max`、`speed_max`）为 `40`，信息性事件（`signal_lost`）为 `70`。当操作员侧的"对友方无人机发出警报"开关关闭时，标记为友方的无人机不会触发警报，因此它们也不会到达此端点。
由**发送测试消息**按钮发出的合成测试警报使用 `rule.category: "test"`、`event.action: "test"`、`event.severity: 70` 以及序列号 `TEST-0000`，以便接收器能够识别并将其从运营仪表板中排除。
---
## 系统要求
| 要求 | Sparrow-WiFi (GUI) | Sparrow DroneID (Web) |
|-------------|-------------------|----------------------|
| **操作系统** | Ubuntu 20.04+、Kali 2020.3+、Debian 11+ | Ubuntu 20.04+、Kali、Debian 11+、Raspberry Pi OS |
| **Python** | 3.8+ | 3.8+ |
| **Root** | 必需（iw scan） | 必需（monitor mode, BLE） |
| **WiFi适配器** | 任何支持 `iw` 的适配器 | 支持监听模式（例如 rtl8812au、Intel AX200） |
| **蓝牙** | 可选（hci 适配器、Ubertooth） | 可选（任何支持 BLE 的适配器用于 RemoteID） |
| **GPS** | 可选（gpsd） | 可选（gpsd 或静态坐标） |
| **显示** | X11/Wayland 桌面 | 无头模式可用（任何设备上的网页浏览器） |
---
## 安装
### Sparrow-WiFi (桌面GUI)```bash
git clone https://github.com/ghostop14/sparrow-wifi
cd sparrow-wifi
系统包 (Ubuntu 22.04+ / Debian 12+ / Kali rolling):```bash
sudo apt install python3-pip python3-pyqt5 python3-pyqt5.qtchart
gpsd gpsd-clients python3-tk python3-setuptools
> **Kali 用户：** PyQt5、PyQtChart 和 aircrack-ng（用于 Falcon 插件）通常已预装。你主要只需要 `gpsd`、`gpsd-clients` 以及下面的 Python 依赖项。
Python 依赖项 — 选择以下任一方式：