Sparrow-WiFi

Sparrow-WiFi は、Linux 向けの 2.4 GHz および 5 GHz の WiFi および Bluetooth スペクトル認識ツールです。これは、WiFi スキャン、Bluetooth Low Energy および Classic の発見、ソフトウェア定義無線スペクトル分析 (HackRF, Ubertooth)、GPS 追跡、FAA RemoteID ドローン検出、ドローン/ローバー搭載のリモート操作、および Elasticsearch または OpenSearch への ECS 8.17 インデックス作成を単一のプラットフォームに統合します。完全に Python 3 で書かれています。

このプロジェクトには、単独または連携して動作する 4 つのコンポーネントが含まれています:

コンポーネント	インターフェース	目的
Sparrow-WiFi	PyQt5 デスクトップ GUI	WiFi/BT スキャン、スペクトル分析、ソース追跡、ワードライビング
Sparrow Agent	ヘッドレス HTTP サーバー	リモートスキャン、ドローン/ローバー展開、サードパーティ統合
Sparrow DroneID	Web ベース (ブラウザ)	WiFi および Bluetooth LE を介した FAA RemoteID ドローン検出
Sparrow Elastic Bridge	ヘッドレス CLI サービス	WiFi/BT 観測の Elasticsearch / OpenSearch への ECS 8.17 インデックス作成

Sparrow Agent と Sparrow DroneID は、他のアプリケーションがスキャン結果を照会し、スキャンをトリガーし、ドローン検出を取得し、ワイヤレス/ドローン認識を独自のワークフローに統合できるようにする JSON REST API を公開します。Elastic Bridge はエージェントの REST API を利用し、バンドルされた Kibana ダッシュボードとともに ECS 8.17 ドキュメントを転送します。

新機能 (2026年4月)

このリリースは、以前のバージョンからの 3 つの重要な改善点をカバーしています:

Sparrow Agent: シングルフライト WiFi スキャン合体処理。 複数の HTTP クライアント (DroneID アプリ、Elasticsearch ブリッジ、GUI) が同時に /wireless/networks/<iface> にアクセスすると、エージェントは以前、インターフェースごとのロックで直列化される N 個の冗長な iw scan 呼び出しを開始し、スキャン待ち時間をクライアント数倍にしていました。最初のリクエストが実際にスキャンを行う「リーダー」になり、同時リクエストは threading.Event で待機し、リーダーの結果を共有します。また、ロック作成の TOCTOU 修正とインターフェースごとのロックの例外安全性も含まれています。
Sparrow DroneID — WiFi (ASTM F3411 NAN、ビーコンベンダー IE、DJI 独自の DroneID プロトコル) および Bluetooth LE (BT4/BT5 Legacy アドバタイジング) を介した FAA RemoteID 検出のための新しい Web ベースのアプリケーション。ジオゾーンオーバーレイ、Slack 統合によるマルチステートアラート、KML エクスポート、Cursor-on-Target 出力、Elasticsearch / OpenSearch へのオプションの ECS 8.17 インデックス作成 (カスタム droneid.* 名前空間)、およびマルチデバイス対応のレスポンシブ Web UI が含まれています。以下の Sparrow DroneID セクションを参照してください。
近代化された Elasticsearch / OpenSearch ブリッジ — sparrow-elastic.py ブリッジは ECS 8.17 ドキュメント (以前は ECS 1.5) を生成するように書き直され、Elasticsearch 8.x および OpenSearch 2.x の両方をサポートし、ILM/ISM ライフサイクルポリシーとロールオーバー書き込みエイリアスを使用して合成可能なインデックステンプレートを自動的にブートストラップし、OUI ベンダーエンリッチメントとルールベースのデバイス分類 (オプションの Fingerbank フィンガープリンティング) を実行し、4 つのバンドルされた Kibana ダッシュボードと 6 つのレガシー保存ビジュアライゼーションを提供します。レガシー ECS 1.5 ブリッジは legacy/sparrow-elastic.py に保存されています。Elasticsearch / OpenSearch 統合を参照してください。

Sparrow-WiFi (デスクトップ GUI)

元の Sparrow アプリケーションは、inSSIDer や LinSSID などのツールに代わる包括的な GUI ベースの代替手段を提供し、基本的なスキャンをはるかに超える機能を備えています:

WiFi スキャン — 2.4 GHz および 5 GHz の SSID 検出、信号強度、チャネル使用率
ソース追跡 — 高いサンプルレートとテレメトリウィンドウを使用したハントモードで、WiFi および Bluetooth ソースを特定
スペクトル分析 — Ubertooth One または HackRF One によるリアルタイム 2.4/5 GHz スペクトルオーバーレイ
Bluetooth — BLE アドバタイジングスキャン、iBeacon 検出/アドバタイジング、Classic + LE 用の Ubertooth プロミスキャスモード
リモートエージェント — 分散スキャン、ドローン/ローバー搭載運用、Raspberry Pi 展開用のヘッドレスエージェント (sparrowwifiagent.py)
GPS 統合 — gpsd、静的座標、または MAVLink (ドローン GPS)
マッピング — GPS トラック付きスキャン結果の Google Maps / OpenStreetMap 可視化
インポート/エクスポート — CSV、JSON、および raw iw scan 出力
Elasticsearch / OpenSearch — ILM/ISM ライフサイクル管理、デバイス分類、オプションの Fingerbank フィンガープリンティング、バンドルされた Kibana ダッシュボードを備えた WiFi および Bluetooth スキャンデータの ECS 8.17 準拠インデックス作成
Falcon プラグイン — ペネトレーションテスト用の Aircrack-ng 統合 (モニターモード、隠し SSID 検出、Deauth、WEP/WPA キャプチャ)

スクリーンショット

Sparrow DroneID (Web アプリケーション)

FAA が義務付ける遠隔識別 (RemoteID) ブロードキャストをデコードするスタンドアロンの Web ベースのドローン検出および追跡システム。ネットワーク上の任意のデバイスからアクセス可能なブラウザベースの UI を備えた Python HTTP サーバーとして実行されます。

機能

WiFi キャプチャ — ASTM F3411 NAN アクションフレーム、ビーコンベンダー IE、DJI 独自の DroneID をデコード
Bluetooth LE キャプチャ — ASTM F3411 BT4/BT5 Legacy アドバタイジング (UUID 0xFFFA) をデコード
リアルタイムマップ — クアッドコプターアイコン、方位インジケーター、オペレーター位置マーカー、ドローン-オペレーター線を備えた Leaflet ベースのマップ
一目でわかるラベル — マップ上の各ドローンアイコンの下にオペレーター ID と AGL 高度を表示
詳細ポップアップ — ドローンをクリックすると、シリアル、登録 ID、オペレーター ID、タイプ、速度、方位、高度、受信機からの方位/距離、BVLOS ステータスを表示
アラートシステム — 新しいドローン、高度違反、速度違反、信号喪失のための設定可能なアラート。オーディオトーン、ビジュアルトースト、Slack webhook 通知、および汎用外部アラート取り込み API へのオプションのベアラートークン JSON POST (以下の API ベースのアラート通知を参照) を含む
アラート確認 — オペレーター ID を持つ 3 状態ワークフロー (アクティブ/確認済み/解決済み)。接続されているすべてのデバイス間で共有
空港ジオゾーン — 近くの空港 (OurAirports データ) と FAA 禁止/制限空域ポリゴンの自動ダウンロードと表示。オフライン運用のためにローカルにキャッシュ
GPS — gpsd 統合または設定可能な静的座標
履歴とリプレイ — タイムラインリプレイと KML エクスポートを備えた SQLite ベースの検出履歴
Cursor-on-Target (CoT) — SA 統合用のマルチキャスト CoT 出力
マルチデバイス — Web UI はデスクトップ、タブレット、スマートフォンで同時に動作
メートル法/ヤードポンド法 — UI とアラート全体で完全な単位設定サポート

Web UI は起動後に http://localhost:8097 で実行されます。セットアップについては以下のインストールを、プログラムによるアクセスについてはAPI リファレンスを参照してください。

API ベースのアラート通知

Slack webhook に加えて、Sparrow DroneID は発火された各アラートを汎用外部アラート取り込みエンドポイントに POST できます。このチャンネルはデフォルトで無効になっています。設定 → アラート → API ベースのアラート通知で設定します:

有効 — オン/オフトグル
API エンドポイントルート — 任意のパスプレフィックスを含む完全なルート URL。例: http://MY_API_HOST:PORT/API_ROOT
ドメイン — 受信 API がアラートをルーティングするために使用する不透明なテナント文字列
ベアラートークン — Authorization: Bearer ... ヘッダーで送信。保存されると UI でマスク
TLS 確認 — 自己署名またはプライベート CA エンドポイントの場合はチェックを外す
認証テスト — 受信側の確認エンドポイントを呼び出し、合格/不合格を明確に報告
テストメッセージ送信 — 合成アラート (rule.category: "test", serial TEST-0000) を POST して、実際のドローンを待たずに受信側をエンドツーエンドでテスト

エンドポイント契約

Sparrow DroneID は設定されたルート URL に対して 2 つの呼び出しを行います:

動詞	パス	目的
`POST`	`{root}/v1/alerts/verify`	認証情報チェック — ボディ `{"domain": "<configured>"}`。受信側は成功時に `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 を送信します。

ペイロード形状```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

人気