Sparrow-WiFi

Sparrow-WiFi هي أداة للوعي الطيفي لشبكات WiFi والبلوتوث بترددات 2.4 GHz و5 GHz لنظام Linux. تدمج مسح WiFi، واكتشاف Bluetooth Low Energy و Classic، وتحليل الطيف بواسطة الراديو المعرّف بالبرمجيات (HackRF، Ubertooth)، وتتبع GPS، وكشف طائرات FAA RemoteID بدون طيار، والعمليات عن بُعد عبر طائرات بدون طيار/عربات، وفهرسة ECS 8.17 في Elasticsearch أو OpenSearch ضمن منصة واحدة. مكتوبة بالكامل بلغة Python 3.

يتضمن المشروع أربعة مكونات تعمل بشكل مستقل أو معًا:

يُظهر Sparrow Agent و Sparrow DroneID واجهات برمجة تطبيقات REST بتنسيق JSON تسمح للتطبيقات الأخرى بالاستعلام عن نتائج المسح، وتشغيل عمليات المسح، واسترداد كشف الطائرات بدون طيار، ودمج الوعي اللاسلكي والطائرات بدون طيار في سير العمل الخاص بها. يستهلك Elastic Bridge واجهة REST الخاصة بالوكيل ويُرسل مستندات ECS 8.17 مع لوحات معلومات Kibana المرفقة.

ما الجديد (أبريل 2026)

يغطي هذا الإصدار ثلاثة تحسينات كبيرة مقارنة بالإصدار السابق:

• Sparrow Agent: دمج مسح WiFi للرحلات الفردية. عندما يضرب عدة عملاء HTTP (تطبيق DroneID، جسر Elasticsearch، الواجهة الرسومية) /wireless/networks/<iface> في وقت واحد، كان الوكيل سابقًا يُشغّل N من استدعاءات iw scan المتكررة التي تتسلسل على قفل الواجهة الواحدة، مما يضاعف زمن المسح بعدد العملاء. الآن، الطلب الأول هو "القائد" الذي يقوم بالمسح فعليًا؛ تنتظر الطلبات المتزامنة على threading.Event وتشارك نتيجة القائد. يتضمن أيضًا إصلاح TOCTOU لإنشاء الأقفال وأمان الاستثناءات بالنسبة لأقفال الواجهات.
• Sparrow DroneID — تطبيق ويب جديد لكشف FAA RemoteID عبر WiFi (ASTM F3411 NAN، عناصر البائع في المنارة، بروتوكول DroneID الخاص بـ DJI) وBluetooth LE (إعلانات BT4/BT5 القديمة). يتضمن تراكبات المناطق الجغرافية، تنبيهات متعددة الحالات مع تكامل Slack، تصدير KML، إخراج Cursor-on-Target، فهرسة اختيارية لـ ECS 8.17 في Elasticsearch / OpenSearch (بمساحة اسم مخصصة droneid.*)، وواجهة ويب مستجيبة متعددة الأجهزة. انظر قسم Sparrow DroneID أدناه.
• جسر Elasticsearch / OpenSearch مُحَدَّث — تمت إعادة كتابة جسر 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-WiFi (واجهة رسومية لسطح المكتب)

يوفر تطبيق Sparrow الأصلي واجهة رسومية شاملة كبديل لأدوات مثل inSSIDer و LinSSID، مع إمكانيات تتجاوز المسح الأساسي بكثير:

• مسح WiFi — اكتشاف شبكات SSID بترددات 2.4 GHz و5 GHz، قوة الإشارة، استخدام القناة
• تتبع المصادر — وضع الصيد بمعدلات عينة عالية ونوافذ قياس عن بُعد لتحديد مواقع مصادر WiFi والبلوتوث
• تحليل الطيف — تراكبات طيفية فورية بترددات 2.4/5 GHz عبر Ubertooth One أو HackRF One
• البلوتوث — مسح إعلانات BLE، كشف/إعلان iBeacon، وضع الاختراق Ubertooth للكلاسيكي + LE
• وكيل عن بُعد — وكيل بدون واجهة رسومية (sparrowwifiagent.py) للمسح الموزع، العمليات على متن طائرة بدون طيار/عربة، ونشر Raspberry Pi
• تكامل GPS — gpsd، إحداثيات ثابتة، أو MAVLink (GPS الطائرة بدون طيار)
• الخرائط — عرض خرائط Google Maps / OpenStreetMap لنتائج المسح مع مسارات GPS
• استيراد/تصدير — CSV، JSON، وإخراج iw scan الخام
• Elasticsearch / OpenSearch — فهرسة متوافقة مع ECS 8.17 لبيانات مسح WiFi والبلوتوث مع إدارة دورة حياة ILM/ISM، تصنيف الأجهزة، بصمة Fingerbank اختيارية، ولوحات معلومات Kibana المرفقة
• إضافة Falcon — تكامل Aircrack-ng لاختبار الاختراق (وضع المراقبة، اكتشاف SSID المخفي، deauth، التقاط WEP/WPA)

لقطات الشاشة

Sparrow DroneID (تطبيق ويب)

نظام مستقل لكشف وتتبع الطائرات بدون طيار قائم على الويب يفك تشفير بثوث التعريف عن بُعد الإلزامية من FAA (RemoteID). يعمل كخادم HTTP بلغة Python مع واجهة مستخدم عبر المتصفح يمكن الوصول إليها من أي جهاز على الشبكة.

الإمكانيات

• التقاط WiFi — يفك تشفير إطارات عمل ASTM F3411 NAN، عناصر بائع المنارة، وDroneID الخاص بـ DJI
• التقاط Bluetooth LE — يفك تشفير إعلانات ASTM F3411 BT4/BT5 القديمة (UUID 0xFFFA)
• خريطة فورية — خريطة قائمة على Leaflet مع أيقونات كوادكوبتر، مؤشرات اتجاه، علامات موقع المشغل، وخطوط المشغل إلى الطائرة
• علامات سريعة — معرف المشغل والارتفاع فوق سطح الأرض معروضين تحت كل أيقونة طائرة على الخريطة
• نوافذ منبثقة تفصيلية — انقر على طائرة للحصول على الرقم التسلسلي، معرف التسجيل، معرف المشغل، النوع، السرعة، الاتجاه، الارتفاع، المسافة/الاتجاه من جهاز الاستقبال، وحالة BVLOS
• نظام التنبيهات — تنبيهات قابلة للتخصيص للطائرات الجديدة، انتهاكات الارتفاع، انتهاكات السرعة، وفقدان الإشارة مع نغمات صوتية، إشعارات مرئية، إشعارات Slack webhook، وإرسال اختياري JSON مع رمز مميز (bearer token) لواجهة برمجة تطبيقات خارجية عامة لاستيعاب التنبيهات (انظر التنبيهات المستندة إلى API أدناه)
• إقرار التنبيهات — سير عمل ثلاثي الحالات (نشط/مقر/محلول) مع هوية المشغل، مشترك عبر جميع الأجهزة المتصلة
• المناطق الجغرافية للمطارات — تنزيل وعرض تلقائي للمطارات القريبة (بيانات OurAirports) ومضلعات المجال الجوي المحظور/المقيد من FAA، مخزنة محليًا للعمل دون اتصال
• GPS — تكامل gpsd أو إحداثيات ثابتة قابلة للتكوين
• السجل وإعادة التشغيل — سجل كشف مدعوم بـ SQLite مع إعادة تشغيل زمني وتصدير KML
• Cursor-on-Target (CoT) — إخراج CoT متعدد الإرسال لتكامل SA
• متعدد الأجهزة — واجهة الويب تعمل على سطح المكتب، الجهاز اللوحي، والهاتف في وقت واحد
• متري / إمبراطوري — دعم كامل لتفضيلات الوحدات في جميع أنحاء الواجهة والتنبيهات

تعمل واجهة الويب على http://localhost:8097 بمجرد بدء التشغيل. انظر التثبيت أدناه للإعداد، ومرجع API للوصول البرمجي.

التنبيهات المستندة إلى API

بالإضافة إلى webhooks الخاصة بـ Slack، يمكن لـ Sparrow Droneid إرسال كل تنبيه مفعل إلى نقطة نهاية خارجية عامة لاستيعاب التنبيهات. القناة معطلة افتراضيًا؛ قم بتكوينها في الإعدادات ← التنبيهات ← التنبيهات المستندة إلى API:

• تمكين — تشغيل/إيقاف
• جذر نقطة النهاية API — عنوان URL الجذر الكامل بما في ذلك أي بادئة مسار، مثلاً http://MY_API_HOST:PORT/API_ROOT
• المجال — سلسلة مستأجر غير شفافة تستخدمها واجهة API المستقبلة لتوجيه التنبيهات
• رمز الحامل (Bearer Token) — يُرسل في رأس Authorization: Bearer ...؛ مخفي في الواجهة بعد التخزين
• التحقق من TLS — قم بإلغاء التحديد لنقاط النهاية ذات الشهادة الذاتية أو CA الخاصة
• اختبار المصادقة — يستدعي نقطة التحقق من المستقبل ويبلغ بنجاح أو فشل واضح
• إرسال رسالة اختبارية — يُرسل تنبيهًا اصطناعيًا (rule.category: "test"، تسلسلي TEST-0000) حتى يمكن اختبار المستقبل من البداية إلى النهاية دون انتظار طائرة حقيقية

اتفاقية نقطة النهاية

يقوم Sparrow Droneid بإجراء مكالمتين ضد عنوان URL الجذر المُكوّن:

كلا المكالمتين تُرسلان 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 (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+ |
| **الوصول الجذري** | مطلوب (مسح iw) | مطلوب (وضع المراقبة، BLE) |
| **محول WiFi** | أي محول يدعم `iw` | يدعم وضع المراقبة (مثل rtl8812au, Intel AX200) |
| **Bluetooth** | اختياري (محول hci, Ubertooth) | اختياري (أي محول يدعم BLE لـ RemoteID) |
| **GPS** | اختياري (gpsd) | اختياري (gpsd أو إحداثيات ثابتة) |
| **الشاشة** | سطح مكتب X11/Wayland | يعمل بدون شاشة (متصفح ويب على أي جهاز) |

---

## التثبيت

### Sparrow-WiFi (واجهة سطح المكتب)```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 — اختر أحد الأسلوبين:

**الخيار أ: تثبيت على مستوى النظام باستخدام `--break-system-packages`** — الأبسط، يتناسب مع طريقة إطلاق الواجهة الرسومية/الوكيل (نصوص مملوكة للجذر):```bash
# Modern systems (Ubuntu 24.04+, Kali rolling 2023+, Debian 12+) require this
# flag because Python is marked externally-managed (PEP 668). Sparrow runs as
# root anyway, so system-wide install is consistent with how it executes.
sudo pip3 install --break-system-packages -r requirements.txt

الخيار ب: البيئة الافتراضية — معزولة، لا تحذيرات pip للنظام، مفضلة لدى بعض المشغلين:```bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

Run with sudo using the venv interpreter:

sudo venv/bin/python3 ./sparrow-wifi.py

بأي حال، قم بتشغيل:```bash
sudo ./sparrow-wifi.py

Sparrow DroneID (تطبيق ويب)```bash

cd sparrow-droneid

System tools — tcpdump for WiFi monitor mode, bluez for BLE RemoteID

sudo apt install tcpdump bluez

Python dependencies — pick one of:

sudo pip3 install --break-system-packages -r sparrow_droneid/requirements.txt

or:

python3 -m venv venv && source venv/bin/activate && pip install -r sparrow_droneid/requirements.txt

Run (either entry point works):

sudo python3 sparrow_droneid/app.py

or: sudo python3 -m sparrow_droneid

افتح `http://localhost:8097` في المتصفح. قم بتكوين واجهة المراقبة ونظام تحديد المواقع (GPS) في الإعدادات، ثم انقر على بدء.

### Elasticsearch / OpenSearch Bridge (اختياري)```bash
sudo pip3 install --break-system-packages -r requirements-elastic.txt
# or via venv as above

أنظر تكامل Elasticsearch / OpenSearch أدناه.

ملاحظات حول محول WiFi

معظم محولات WiFi تعمل للمسح الأساسي. يدعم Sparrow-WiFi خلفيات متعددة لتعداد الواجهات (iw، iwconfig، nmcli) لذا يعمل على الأنظمة التي قد لا تحتوي على iw مثبتًا (مثل RHEL/Fedora مع NetworkManager فقط).

بالنسبة لوضع المراقبة (مطلوب من Sparrow DroneID وإضافة Falcon)، يختلف دعم المحول وبرنامج التشغيل:

• موصى به: Alfa AWUS036ACH (rtl8812au)، Alfa AWUS036AXML (mt7921au)
• يعمل بشكل جيد: Intel AX200/AX210 (iwlwifi) للمسح؛ يختلف تسليم إطارات وضع المراقبة حسب إصدار البرنامج الثابت
• اختبر أولاً: iw phy <phy> info | grep monitor أو iwconfig <iface> للتحقق من القدرات

بالنسبة لـ Sparrow DroneID تحديدًا، يجب على المحول تسليم إطارات 802.11 الخام في وضع المراقبة. بعض محولات Intel تبلغ عن دعم وضع المراقبة ولكنها تتجاهل الإطارات بصمت على مستوى البرنامج الثابت. يكتشف التطبيق هذا ويحذرك.

Bluetooth

يدعم Sparrow-WiFi عدة أوضاع لمسح Bluetooth:

محول Bluetooth مدمج قياسي أو USB يكفي لمسح إعلانات BLE واكتشاف طائرات RemoteID. اختبر محولك باستخدام bluetoothctl scan on.

للاكتشاف التجسسي الكامل لكل من أجهزة Classic و BLE، ستحتاج إلى Ubertooth One و Blue Hydra مثبتين في /opt/bluetooth/blue_hydra. هذا اختياري وغير مطلوب لمسح BLE الأساسي أو RemoteID.

تحليل الطيف

تراكبات طيفية فورية فوق عروض قنوات WiFi:

Ubertooth One

• 2.4 GHz فقط، دقة 1 MHz
• اختبر باستخدام: ubertooth-specan-ui

HackRF One

• 2.4 GHz (دقة 0.5 MHz) و 5 GHz (دقة 2 MHz)
• نطاق واحد في كل مرة؛ ادمج مع Ubertooth للمزدوج المتزامن
• استخدم هوائي مزدوج النطاق مناسب (هوائي HackRF القياسي مصنف حتى 1 GHz فقط)
• ملاحظة: محول RP-SMA إلى SMA مطلوب لمعظم هوائيات WiFi
• اختبر باستخدام: hackrf_sweep

GPS

كلا التطبيقين يستخدمان gpsd لنظام تحديد المواقع. الإعداد السريع:```bash

Install

sudo apt install gpsd gpsd-clients

Test with a USB GPS receiver

sudo gpsd -D 2 -N /dev/ttyUSB0

Verify

xgps # or: cgps -s

للاستخدام الإنتاجي، قم بتكوين `/etc/default/gpsd` بمسار جهازك وأعد تشغيل الخدمة.

يدعم Sparrow DroneID أيضًا الإحداثيات الثابتة (التي يتم تكوينها في الإعدادات) للمواقع المثبتة بشكل ثابت بدون جهاز استقبال GPS.

---

## الوكيل البعيد وتكامل API

وكيل Sparrow (`sparrowwifiagent.py`) هو خادم HTTP بدون واجهة رسومية يعرض جميع قدرات مسح WiFi و Bluetooth الخاصة بـ Sparrow كـ REST API قائم على JSON. هذه هي الطريقة التي يتواصل بها واجهة Sparrow-WiFi الرسومية مع أجهزة الاستشعار البعيدة، لكن API مفتوح لأي تطبيق لاستخدامه.

**حالات الاستخدام:**
- نشره على Raspberry Pi أو طائرة بدون طيار أو عربة متنقلة للمسح عن بعد/المتنقل
- دمج الوعي الظرفي لشبكات WiFi و Bluetooth في تطبيقاتك الخاصة
- تغذية بيانات المسح إلى SIEM ولوحات المعلومات أو خطوط الإنذار
- أتمتة المسح باستخدام البرامج النصية (تشغيل المسح، سحب النتائج عبر curl/Python/إلخ)

يمتلك Sparrow DroneID أيضًا REST API خاص به ([مرجع API](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow-droneid/sparrow_drone_id_api.md))، مما يوفر وصولًا برمجيًا إلى اكتشافات الطائرات بدون طيار، وإدارة التنبيهات، والمناطق الجغرافية، وتكوين النظام.

### تشغيل الوكيل```bash
sudo ./sparrowwifiagent.py

يستمع على المنفذ 8020 افتراضيًا. الخيارات الرئيسية:

انظر --help للحصول على القائمة الكاملة.

مثال على استدعاءات API```bash

List wireless interfaces the agent can scan

curl http://sensor:8020/wireless/interfaces

Trigger a WiFi scan and pull results (multiple concurrent callers

get coalesced into a single iw scan; first caller is the leader)

curl http://sensor:8020/wireless/networks/wlan0

Filter to specific frequencies

curl "http://sensor:8020/wireless/networks/wlan0?frequencies=2412,2437,2462"

Query GPS status

curl http://sensor:8020/gps/status

Start a Bluetooth Low Energy advertisement scan

curl http://sensor:8020/bluetooth/discoverystarta

Pull current BT discovery results

curl http://sensor:8020/bluetooth/discoverystatus

بالنسبة لـ Sparrow DroneID، راجع [مرجع API](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow-droneid/sparrow_drone_id_api.md).

> **ملاحظة إنتاجية:** يستمع الوكيل على جميع الواجهات افتراضيًا. بالنسبة للنشر خارج شبكة موثوقة، استخدم `--allowedips` لتقييد المتصلين، أو قم بتشغيله خلف وكيل عكسي مع TLS، أو ربطه بواجهة خاصة فقط.

---

## إضافة Falcon / Aircrack-ng

تكامل متقدم لاختبار الاختراق اللاسلكي. يوفر وصولًا بنقرة واحدة إلى:

- اكتشاف SSID المخفي عبر airodump-ng
- تعداد محطات العميل (AP متصل، SSIDs تم فحصها)
- إلغاء المصادقة المستهدف والبث
- التقاط WEP IV
- التقاط مصافحة WPA مع استخراج التجزئة تلقائيًا (يتطلب JTR `wpapcap2john`)

### المتطلبات الأساسية```bash
# Kali users: aircrack-ng + JTR are usually pre-installed.
# Ubuntu / Debian / Raspberry Pi OS:
sudo apt install aircrack-ng john

تحقق من أن airmon-ng و airodump-ng و wpapcap2john موجودة في PATH الخاص بك بعد التثبيت.

إخلاء مسؤولية

الاختراق النشط يخضع للوائح قانونية. من مسؤوليتك الحصول على التصريح المناسب قبل استخدام هذه الأدوات.

تكامل Elasticsearch / OpenSearch

توفر حزمة sparrow_elastic جسر ECS 8.17 الذي يستطلع وكيل Sparrow WiFi ويقوم بفهرسة جماعية لملاحظات WiFi و Bluetooth في Elasticsearch 8.x أو OpenSearch 2.x. تقوم الحزمة تلقائياً بتهيئة قوالب الفهرسة القابلة للتكوين، وسياسات دورة حياة ILM/ISM، وأسماء مستعارة للكتابة التلقائية؛ وتقوم بإثراء بيانات البائع OUI وتصنيف الأجهزة بناءً على قواعد (مع خيار التعرف على البصمات Fingerbank)؛ وتوفر لوحات معلومات Kibana مُعدة مسبقاً.

بداية سريعة```bash

1. Start the remote agent (it provides scan data via HTTP)

sudo ./sparrowwifiagent.py

2. Install bridge dependencies

sudo pip3 install --break-system-packages -r requirements-elastic.txt

3. Run the bridge

./sparrow-elastic.py --elasticserver http://user:pass@host:9200 --wifiinterface wlan1

4. (Optional) Import the bundled Kibana dashboards

python3 install_dashboards.py --kibana-url http://kibana:5601
--username elastic --password ''

> **نظافة بيانات الاعتماد:** تضمين `user:pass@` في `--elasticserver` أمر مريح لكن عنوان URL يظهر في `ps` و`journalctl` وسجل الأوامر. للإنتاج، استخدم علامات `--username`/`--password`، أو متغيرات البيئة (`SPARROW_ES_USERNAME`, `SPARROW_ES_PASSWORD`)، أو نمط `EnvironmentFile=` في مثال وحدة systemd المرفقة.

### ما يوفره الجسر

- **5 لوحات تحكم Kibana** — الوعي الظرفي، نمط الحياة، كشف الأجهزة الجديدة، تخطيط الطيف (مع خريطة حرارية لقوة الإشارة SSID × القناة)، والوعي الظرفي للبلوتوث (مع لوحة Vega للأجهزة الجديدة حقًا وجدول تقريبي للمدى القريب)
- **6 رسومات بيانية محفوظة قديمة** — نسخ مُعاد تسمية الحقول من رسوم `Sparrow*` الأصلية لتبقى الذاكرة القديمة تعمل
- **مصنف الأجهزة** — جدول بذور يحتوي على 64 قاعدة يغطي وحدات تحكم الطائرات بدون طيار (DJI/Autel/Skydio/Parrot/Yuneec)، وفئة جهاز BT، ومظهر GAP، وأنواع فرعية لاستمرارية Apple، وإرشادات البائع OUI
- **تحديث البيانات المرجعية** — جداول Wireshark `manuf` المرفقة، ومعرفات شركات BT SIG، ومعرفات الخدمة UUID، وقيم مظهر GAP، وجداول الأنواع الفرعية لاستمرارية Apple، مع خيط خلفية للتحديث الذاتي كل 30/90 يومًا
- **فحص التوافق المسبق** — يرفض الكتابة في فهارس ECS 1.5 القديمة ويطبع خطوات تصحيح واضحة بدلاً من إتلاف البيانات بصمت

للحصول على وثائق المشغل الكاملة (اختيار المحرك، أوضاع المصادقة، استيراد لوحات التحكم، البيانات المرجعية، مرجع CLI الكامل) راجع [sparrow_elastic/README.md](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow_elastic/README.md).

ملفات التكوين النموذجية موجودة في جذر المستودع و `init.d_scripts/`:

- `sparrow-elastic.conf.example` — تكوين بصيغة INI يحتوي على جميع المفاتيح المدعومة
- `sparrow-elastic.env.example` — ملف بيئة بصيغة shell لنشر systemd
- `init.d_scripts/sparrow-elastic.service.example` — قالب وحدة systemd

### الترحيل من جسر ECS 1.5 القديم

كان الجسر القديم (ما قبل 2026) يكتب مستندات ECS 1.5 إلى فهارس مسماة من قبل المشغل عبر `--wifiindex` / `--btindex`. الجسر الجديد يكتب مستندات ECS 8.17 إلى أسماء مستعارة للكتابة تحت إدارة التبديل التلقائي (افتراضيًا `sparrow-wifi` / `sparrow-bt`).

**البرنامج النصي القديم محفوظ في `legacy/sparrow-elastic.py`** إلى جانب قالب `.txt` وملفات سياسة ILM الخاصة به. تشغيله لا يزال يتطلب البيئة القديمة (إعداد القالب اليدوي + ILM).

**تغييرات العلامات (مع التوافق العكسي):**

| العلامة القديمة     | العلامة الجديدة     | ملاحظات                                                  |
|---------------------|--------------------|--------------------------------------------------------|
| `--wifiindex NAME`  | `--wifi-alias NAME`| التهجئة القديمة لا تزال مقبولة كاسم مستعار مهمل.      |
| `--btindex NAME`    | `--bt-alias NAME`  | التهجئة القديمة لا تزال مقبولة كاسم مستعار مهمل.      |
| `--dont-create-indices` | بدون تغيير       | يتجاوز التمهيد.                                       |
| `--elasticserver`, `--sparrowagent`, `--sparrowport`, `--wifiinterface`, `--scandelay` | بدون تغيير | |

استدعاء قديم مثل:```bash
./sparrow-elastic.py --elasticserver=http://user:pass@host:9200 \
                     --wifiinterface=wlan1 \
                     --wifiindex=sparrowwifi-home \
                     --btindex=sparrowbt-home

لا يزال يحلل ويعمل — لكن الجسر يرفض الآن الكتابة في فهرس موجود مسبقًا لا يحمل تخطيطه علامة مخطط ECS 8.17، ويخرج مع ثلاثة خيارات للمعالجة (استخدام اسم مستعار مختلف، أو مسح وإعادة التمهيد، أو تشغيل الجسر القديم). للتثبيت النظيف، ما عليك سوى حذف --wifiindex / --btindex وقبول الإعدادات الافتراضية الجديدة.

عمليات الطائرات بدون طيار / المركبات الجوالة

يمكن نشر الوكيل البعيد على Raspberry Pi مثبت على طائرة بدون طيار أو مركبة جوالة للمسح اللاسلكي المتنقل. تم اختباره على طائرة بدون طيار Solo 3DR مع تكامل GPS عبر MAVLink.

التسجيل الذاتي```bash

On the Pi: auto-start, pull drone GPS, record to local files

sudo python3 ./sparrowwifiagent.py --userpileds --sendannounce --mavlinkgps 3dr --recordinterface wlan0

مؤشرات LED (راسبيري باي):
1. كلاهما مطفأ — التهيئة
2. نبض أحمر — GPS موجود، غير متزامن
3. أحمر ثابت — GPS متزامن
4. أخضر ثابت — الوكيل جاهز، يخدم الطلبات

يمكن استرداد التسجيلات عبر واجهة إدارة الوكيل في واجهة Sparrow-WiFi الرسومية.

### ملاحظات إعداد Pi

- استخدم نظام Raspberry Pi OS (Bookworm أو أحدث) مع Python 3.8+
- قم بتعطيل WiFi المدمج لتمكين المسح بتردد 5 جيجاهرتز باستخدام محولات USB: أضف `dtoverlay=disable-wifi` إلى `/boot/firmware/config.txt` على Bookworm والأحدث، أو `/boot/config.txt` على الإصدارات الأقدم
- تثبيت المتطلبات الأساسية: `sudo pip3 install --break-system-packages -r requirements.txt` (أو استخدم بيئة افتراضية كما في قسم [التثبيت](#installation))

---

## هيكل المشروع```
sparrow-wifi/
  sparrow-wifi.py            # Desktop GUI entry point
  sparrowwifiagent.py        # Headless remote agent
  sparrow-elastic.py         # Elasticsearch / OpenSearch bridge (ECS 8.17)
  install_dashboards.py      # One-shot Kibana dashboard installer
  requirements.txt           # Python dependencies (GUI)
  requirements-elastic.txt   # Python dependencies (Elasticsearch bridge)
  wirelessengine.py          # WiFi scan engine (iw)
  sparrowbluetooth.py        # Bluetooth scan engine
  sparrowhackrf.py           # HackRF spectrum engine
  sparrowmap.py              # Map generation
  plugins/                   # Falcon and other plugins
  sparrow_elastic/           # ES/OS bridge package
    *.py                     # Client abstraction, document builder, classifier...
    templates/               # Composable index templates (ES + OS variants)
    policies/                # ILM (ES) and ISM (OS) lifecycle policy JSON
    dashboards/              # Kibana NDJSON: 5 dashboards + legacy-preserved
    data/                    # Bundled reference data (manuf, BT SIG, classifier rules)
    README.md                # Full bridge operator documentation
  legacy/                    # Pre-2026 ECS 1.5 bridge, frozen for reference
    sparrow-elastic.py       # Legacy bridge (still runnable)
    sparrow_elastic_*.txt    # Legacy index templates and ILM policy
  sparrow-droneid/           # DroneID web application
    sparrow_droneid/
      app.py                 # Entry point (sudo python3 app.py)
      __main__.py            # Allows: sudo python3 -m sparrow_droneid
      requirements.txt       # Python dependencies (DroneID)
      backend/               # API server, capture engine, database
      frontend/              # HTML, JS, CSS (served by backend)
    sparrow_drone_id_api.md  # REST API reference

الترخيص

هذا المشروع مرخص بموجب الشروط المضمنة في المستودع. راجع ملف LICENSE للحصول على التفاصيل.