Bluehood

جوار البلوتوث - تتبّع أجهزة BLE في منطقتك وحلّل أنماط حركة المرور.

تحذير: برنامج في مرحلة ألفا

هذا المشروع في مرحلة تطوير مبكرة وغير جاهز للاستخدام الإنتاجي. قد تتغير الميزات أو تتعطل أو تُزال دون إشعار. استخدمه على مسؤوليتك الخاصة. يجب التعامل مع البيانات المجمّعة على أنها تجريبية.

لقطات الشاشة

لوحة التحكم الرئيسية تعرض قائمة الأجهزة مع التصفية والبحث والإحصاءات الفورية

صفحة الإعدادات بتبويبات — التنبيهات، العمليات، المجموعات، والأمان

صفحة المعلومات مع تفاصيل المشروع ونظرة عامة على الإمكانات

لماذا؟

استُلهم هذا المشروع من ثغرة WhisperPair (CVE-2025-36911)، التي أبرزت مخاطر الخصوصية في أجهزة البلوتوث.

تحيط بنا آلاف أجهزة البلوتوث في كل الأوقات: الهواتف، السيارات، أجهزة التلفاز، السماعات، المعينات السمعية، مركبات التوصيل، وغيرها. يوضّح Bluehood مدى سهولة الكشف السلبي عن هذه الأجهزة وملاحظة الأنماط في حضورها.

مع بيانات كافية، يمكنك نظريًا:

• معرفة الوقت الذي يمشي فيه شخص ما مع كلبه عادةً
• كشف وصول زائر إلى منزل
• تحديد أنماط الروتين اليومي بناءً على حضور الأجهزة

يمكن لهذه البيانات الوصفية أن تكشف معلومات شخصية بشكل مفاجئ دون أي تفاعل نشط مع الأجهزة.

Bluehood أداة تعليمية لرفع الوعي حول خصوصية البلوتوث. إنه مشروع نهاية أسبوع، لكن آثاره تستحق التفكير.

ما هو؟

Bluehood هو ماسح بلوتوث يقوم بـ:

• المسح المستمر بحثًا عن أجهزة البلوتوث القريبة (سواء BLE و Classic)
• التعرّف على الأجهزة حسب الشركة المصنّعة (البحث بعنوان MAC) ومعرّفات خدمة BLE
• تصنيف الأجهزة إلى فئات (هواتف، صوتيات، أجهزة قابلة للارتداء، إنترنت الأشياء، مركبات، إلخ)
• تتبّع أنماط الحضور عبر الزمن مع خرائط حرارية بالساعة/اليوم
• تصفية الضوضاء الناتجة عن عناوين MAC العشوائية (الأجهزة التي تدوّر عنوانها لأغراض الخصوصية)
• تحليل ارتباطات الأجهزة للعثور على الأجهزة التي تظهر معًا
• إرسال إشعارات فورية عند وصول أو مغادرة الأجهزة المراقَبة
• توفير لوحة تحكم ويب للمراقبة والتحليل

الميزات

المسح

• مسح ثنائي الوضع: Bluetooth Low Energy (BLE) و Classic Bluetooth
• البحث عن الشركة المصنّعة بعنوان MAC (قاعدة بيانات محلية + واجهة برمجية عبر الإنترنت كبديل)
• بصمة معرّف خدمة BLE لتصنيف دقيق للأجهزة
• تحليل فئة أجهزة Classic Bluetooth
• تصفية عناوين MAC العشوائية (مخفية من العرض الرئيسي)

إدارة الأجهزة

• وضع علامة "مراقَب" على الأجهزة لتتبّع الأجهزة الشخصية
• تنظيم الأجهزة في مجموعات مخصصة
• إعطاء الأجهزة اسمًا مخصصًا (يبقى الاسم المُعلن ظاهرًا بجانبه)
• تجاوز التصنيف المكتشف لأي جهاز
• إضافة ملاحظات/وسوم مخصصة لأي جهاز
• كشف نوع الجهاز (هواتف، صوتيات، أجهزة قابلة للارتداء، إنترنت الأشياء، مركبات، إلخ)

التحليلات

• تصوّر الخط الزمني للحضور لمدة 30 يومًا
• مخطط سجل قوة الإشارة (RSSI) مع بيانات 7 أيام
• خرائط حرارية للنشاط بالساعة واليوم تُظهر متى تكون الأجهزة نشطة
• تحليل الأنماط ("أيام الأسبوع، المساء 5PM-9PM")
• تحليل مدة البقاء يُظهر إجمالي الوقت الذي تقضيه الأجهزة في النطاق
• كشف ارتباط الأجهزة للعثور على الأجهزة التي تظهر معًا (الحضور المشترك بالإضافة إلى الوصول/المغادرة المتزامنة)
• ربط تدوير MAC ("على الأرجح نفس الجهاز") — يربط استكشافيًا المعرّفات العشوائية التي تتناوب زمنيًا، وتشترك في قوة إشارة مشابهة، وتُرسل إشارات بإيقاع مشابه
• مناطق القرب (فوري، قريب، بعيد، نائي) بناءً على قوة الإشارة
• البحث بعنوان MAC أو الشركة المصنّعة أو الاسم
• البحث بنطاق تاريخ للاستعلامات التاريخية

الإشعارات (عبر ntfy)

• إشعارات فورية إلى هاتفك/سطح مكتبك عبر ntfy.sh أو خادم ntfy مستضاف ذاتيًا
• الإشعار عند كشف أجهزة جديدة
• الإشعار عند عودة الأجهزة المراقَبة
• الإشعار عند مغادرة الأجهزة المراقَبة
• حدود قابلة للتهيئة للوصول/المغادرة

العمليات

• نبضة التحقق — إرسال حالة POST دوريًا إلى خدمة مراقبة وقت التشغيل (مثل Uptime Kuma، Healthchecks.io)
• تدوير التخزين — تقليم تلقائي للمشاهدات الأقدم من عدد أيام قابل للتهيئة؛ ويمكن اختياريًا قصر التقليم على الأجهزة القديمة بالكامل التي شوهدت أقل من حد أدنى معيّن من المرات (الأجهزة المراقَبة لا تُقلَّم أبدًا)
• كلاهما قابل للتهيئة من واجهة الويب أو عبر متغيرات البيئة

واجهة الويب

• تبديل العرض المضغوط/المفصّل لتفضيلات عرض مختلفة
• وضع لقطة الشاشة لإخفاء عناوين MAC والأسماء للمشاركة الآمنة
• اختصارات لوحة المفاتيح للمستخدمين المتقدمين (اضغط ? للعرض)
• تصدير CSV لبيانات الأجهزة التفصيلية (MAC، الشركة المصنّعة، المعرّف، النوع، نوع BT، فئة الجهاز، علامات المراقَبة/المتجاهَلة، أول/آخر ظهور، المشاهدات، المجموعة، معرّفات الخدمة، والملاحظات) — يصدّر المجموعة المصفّاة بالكامل، وليس الصفحة الحالية فقط
• مجموعات الأجهزة لتنظيم الأجهزة ذات الصلة
• مصادقة اختيارية لتأمين الوصول

كيف؟

البدء السريع مع Docker (موصى به)

المتطلبات المسبقة — مضيفات Linux فقط

يتواصل Bluehood مع محوّل البلوتوث لديك عبر BlueZ، حزمة البلوتوث في Linux. يجب تثبيت BlueZ وتشغيله على المضيف قبل بدء الحاوية — صورة Docker نفسها لا تتضمنه.

root@kitploit:~

# Debian / Ubuntu (including Ubuntu Server)
sudo apt install bluez
sudo systemctl enable --now bluetooth

# Arch Linux
sudo pacman -S bluez bluez-utils
sudo systemctl enable --now bluetooth

بدون BlueZ على المضيف سترى خطأً مثل: BLE scan error: [org.freedesktop.DBus.Error.ServiceUnknown] The name org.bluez was not provided by any .service files

# Create a docker-compose.yml or download the one from this repo
# Then start with Docker Compose
docker compose up -d

# View logs
docker compose logs -f

صورة Docker متاحة على GitHub Container Registry:

ghcr.io/dannymcc/bluehood:latest

ستكون لوحة تحكم الويب متاحة على http://localhost:8080

متطلبات Docker

• Docker و Docker Compose
• مضيف Linux مع محوّل بلوتوث يدعم BLE (Bluetooth 4.0+) ويدعم دور Central
• BlueZ مثبّت ويعمل على المضيف (sudo apt install bluez && sudo systemctl enable --now bluetooth)

ملاحظة: المحوّلات الأقدم (Bluetooth 2.x/3.x) لا تدعم مسح BLE. إذا كان محوّلك يفتقر إلى دعم دور BLE Central، سترى: No Bluetooth adapters with BLE 'central' role found.

ملاحظة: يعمل Docker في الوضع المميّز مع شبكات المضيف للوصول إلى البلوتوث. هذا مطلوب لمسح BLE.

متغيرات بيئة Docker

متطلبات محوّل البلوتوث

يتطلب Bluehood محوّل بلوتوث يدعم BLE (Bluetooth 4.0 أو أحدث) مع دعم دور Central. محوّلات Bluetooth 2.x/3.x الأقدم لا تدعم مسح BLE ولن تعمل.

إذا كان محوّلك لا يدعم دور BLE Central، سيخرج Bluehood مع:

No Bluetooth adapters with BLE 'central' role found

يمكنك التحقق من إمكانات محوّلك باستخدام bluetoothctl show والبحث عن central في الأدوار المدعومة.

التثبيت اليدوي (Linux)

# Install system dependencies (Arch Linux)
sudo pacman -S bluez bluez-utils python-pip

# Install system dependencies (Debian/Ubuntu)
sudo apt install bluez python3-pip

# Clone and install
git clone https://github.com/dannymcc/bluehood.git
cd bluehood
pip install -e .

أذونات البلوتوث

يتطلب مسح البلوتوث صلاحيات مرتفعة. اختر أحد الخيارات:

1. التشغيل كـ root (الأبسط):

   root@kitploit:~

   sudo bluehood
   

2. منح الصلاحيات لـ Python:

   root@kitploit:~

   sudo setcap 'cap_net_admin,cap_net_raw+eip' $(readlink -f $(which python))
   bluehood
   

3. استخدام خدمة systemd (موصى به للتشغيل الدائم):

   root@kitploit:~

   sudo cp bluehood.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now bluehood
   

macOS

يعمل Bluehood أصليًا على macOS دون Docker. يستخدم macOS مكتبة CoreBluetooth بدلًا من BlueZ، وهو ما تتعامل معه مكتبة bleak تلقائيًا.

# Clone the repository
git clone https://github.com/dannymcc/bluehood.git
cd bluehood

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install
pip install -e .

# Run
python -m bluehood.daemon

ستكون لوحة تحكم الويب متاحة على http://localhost:8080

ملاحظة: عند التشغيل الأول، سيطالبك macOS بالسماح بالوصول إلى البلوتوث. يجب منح هذا الإذن ليعمل المسح.

الاستخدام

# Start with web dashboard (default port 8080)
bluehood

# Specify a different port (or set BLUEHOOD_PORT)
bluehood --port 9000

# Use a specific Bluetooth adapter
bluehood --adapter hci1

# Use separate adapters for BLE and classic scanning (concurrent)
bluehood --adapter hci0 --classic-adapter hci1

# List available adapters
bluehood --list-adapters

# Disable web dashboard (scanning only)
bluehood --no-web

# Enable Prometheus metrics exporter on port 9199
bluehood --metrics-port 9199

لوحة تحكم الويب

توفّر لوحة التحكم:

• قائمة الأجهزة مع أيقونات النوع، الشركة المصنّعة، MAC، الاسم، المشاهدات، آخر ظهور
• مرشّحات الأجهزة حسب النوع (هواتف، صوتيات، إنترنت الأشياء، إلخ) وحالة المراقبة
• البحث بعنوان MAC أو الشركة المصنّعة أو الاسم
• البحث بنطاق تاريخ للعثور على الأجهزة التي ظهرت في نافذة زمنية محددة
• صفحة إعدادات بتبويبات — التنبيهات، العمليات، المجموعات، والأمان (رابط مباشر عبر hash، مثل /settings#operations)
• نافذة تفاصيل الجهاز مع:
  • بصمات خدمة BLE
  • خرائط حرارية للنشاط بالساعة/اليوم
  • الخط الزمني للحضور لمدة 30 يومًا
  • مخطط سجل قوة الإشارة (RSSI)
  • تحليل الأنماط
  • إحصاءات مدة البقاء
  • قائمة الأجهزة المرتبطة
  • قائمة على الأرجح نفس الجهاز (تدوير MAC)
  • مؤشر منطقة القرب
  • حقل ملاحظات المشغّل
  • تعيين المجموعة

اختصارات لوحة المفاتيح

وضع لقطة الشاشة

فعّل وضع لقطة الشاشة من الشريط الجانبي لإخفاء البيانات الحساسة قبل مشاركة لقطات الشاشة:

• تُظهر عناوين MAC أول مقطعين فقط (مثل AA:BB:XX:XX:XX:XX)
• تُظهر الأسماء المألوفة أول حرفين فقط (مثل Da********)
• تصديرات CSV تحترم أيضًا وضع لقطة الشاشة

الإشعارات الفورية

يمكن لـ Bluehood إرسال إشعارات فورية عبر ntfy، وهي خدمة إشعارات مجانية ومفتوحة المصدر. يمكنك استخدام خادم ntfy.sh العام أو نسختك المستضافة ذاتيًا.

1. أنشئ موضوعًا (topic) على ntfy.sh (مثل bluehood-myname-alerts)، أو على خادم ntfy الخاص بك
2. اشترك في الموضوع على هاتفك باستخدام تطبيق ntfy
3. في إعدادات Bluehood، أدخل عنوان URL للخادم (الافتراضي https://ntfy.sh)، واسم الموضوع، ورمز وصول إذا كان خادمك يتطلبه، ثم فعّل الإشعارات
4. هيّئ الأحداث التي تُطلق الإشعارات:
   • كشف جهاز جديد
   • عودة جهاز مراقَب (بعد غيابه)
   • مغادرة جهاز مراقَب (لم يُشاهد لمدة X دقيقة)

تخزين البيانات

تُخزَّن البيانات في ~/.local/share/bluehood/bluehood.db (SQLite).

تجاوز الموقع بمتغيرات البيئة:

• BLUEHOOD_DATA_DIR - دليل ملفات البيانات
• BLUEHOOD_DB_PATH - مسار مباشر لملف قاعدة البيانات

ملاحظة: يمكن تهيئة إعدادات نبضة التحقق والتقليم من واجهة الويب (Settings > Operations) أو عبر متغيرات البيئة. قيم الواجهة الرسومية لها الأولوية على متغيرات البيئة.

كيف يعمل

تصنيف الأجهزة

يصنّف Bluehood الأجهزة باستخدام إشارات متعددة (بترتيب الأولوية):

1. معرّفات خدمة BLE - الأكثر دقة (معدل ضربات القلب = جهاز قابل للارتداء، A2DP = صوتيات، إلخ)
2. أنماط اسم الجهاز - "iPhone"، "Galaxy"، "AirPods"، إلخ
3. البحث عن الشركة المصنّعة عبر OUI - Apple، Samsung، Bose، إلخ

عناوين MAC العشوائية

تقوم الأجهزة الحديثة بتعشويم عناوين MAC لأغراض الخصوصية. يقوم Bluehood بـ:

• كشف عناوين MAC العشوائية (بتة الإدارة المحلية)
• إخفائها من قائمة الأجهزة الرئيسية (غير مفيدة للتتبّع)
• عرض عدد الأجهزة العشوائية المخفية

تحليل الأنماط

يحلّل Bluehood الطوابع الزمنية للمشاهدات لكشف الأنماط:

• وقت اليوم: صباح، بعد الظهر، مساء، ليل
• يوم الأسبوع: أيام الأسبوع، عطلة نهاية الأسبوع
• التكرار: مستمر، يومي، منتظم، متقطع، نادر

أمثلة على الأنماط: "يومي، مساءً (5PM-9PM)"، "أيام الأسبوع، صباحًا (8AM-12PM)"

ارتباط الأجهزة

يكشف Bluehood الأجهزة التي تظهر معًا بشكل متكرر ضمن نافذة زمنية قابلة للتهيئة. يمكن أن يكشف هذا عن:

• أجهزة يملكها نفس الشخص (هاتف + ساعة ذكية)
• أشخاص يسافرون معًا
• أجهزة تشترك في جدول زمني

مناطق القرب

بناءً على قوة إشارة RSSI، تُصنَّف الأجهزة إلى مناطق قرب:

• فوري (> -50 dBm): قريب جدًا، ضمن بضعة أمتار
• قريب (-50 إلى -60 dBm): قريب، نفس الغرفة
• بعيد (-60 إلى -70 dBm): أبعد، غرف مجاورة
• نائي (< -70 dBm): بعيد، عند حدود نطاق الكشف

تحليل مدة البقاء

يتتبّع المدة التي تقضيها الأجهزة في النطاق من خلال تحليل الفجوات بين المشاهدات. يحدد عتبة فجوة قابلة للتهيئة (الافتراضي 15 دقيقة) متى تبدأ "جلسة" جديدة.

مقاييس Prometheus

يمكن لـ Bluehood كشف المقاييس لجمع Prometheus. فعّلها بضبط متغير البيئة BLUEHOOD_METRICS_PORT أو علامة CLI --metrics-port.

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

تُقدَّم المقاييس على http://host:9199/metrics.

المقاييس المتاحة

لوحة تحكم Grafana

تتضمن لوحة تحكم Grafana جاهزة للاستيراد في grafana/bluehood-dashboard.json. استوردها عبر واجهة Grafana (Dashboards > Import) أو الواجهة البرمجية:

curl -X POST "http://localhost:3000/api/dashboards/db" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d "{\"dashboard\": $(cat grafana/bluehood-dashboard.json), \"overwrite\": true}"

استكشاف الأخطاء وإصلاحها

لم يتم العثور على أجهزة

• تأكد من أن محوّلك يدعم BLE (Bluetooth 4.0+) مع دور Central — المحوّلات الأقدم لن تعمل
• تأكد من تمكين محوّل البلوتوث: bluetoothctl power on
• تحقق من كشف المحوّل: bluehood --list-adapters
• شغّله باستخدام sudo إذا رُفض الإذن

مشكلات Docker

BLE scan error: org.freedesktop.DBus.Error.ServiceUnknown / The name org.bluez was not provided

BlueZ غير مثبّت أو لا يعمل على المضيف. الإصلاح:

sudo apt install bluez          # Debian/Ubuntu
sudo systemctl enable --now bluetooth
docker compose restart

قائمة التحقق العامة:

• تأكد من تثبيت BlueZ على المضيف (وليس فقط في الحاوية)
• تحقق من تشغيل خدمة البلوتوث: systemctl status bluetooth
• تأكد من ظهور محوّلك: bluetoothctl list

المساهمة

المساهمات مرحّب بها! يرجى فتح issue أو PR على GitHub.

المساهمون

• @martinh2011 (Martin Hüser) - تحسينات ذاكرة التخزين المؤقت لشركات MAC
• @hatedabamboo (Kirill Solovei) - دعم السمة الفاتحة
• @krnltrp - تحسينات واجهة الويب
• @jacobpretorius (Jacob Pretorius) - إصلاح JS لتصدير CSV (#14)، النقر لفتح الإعدادات (#16)
• @unqualifiedkoala - توثيق متطلبات محوّل BLE
• @dazzag24 - الإبلاغ عن مشكلة تنسيق عنوان macOS
• @floese (W.A.Flozart) - إصلاح النقر المزدوج في Firefox (#29)
• @GeiserX (Sergio Fernández) - مُصدِّر مقاييس Prometheus (#35)، إصلاح قاعدة بيانات الشركات غير الحاجب (#37)، المسح بمحوّلين (#33)، استرداد المسح القوي مع rfkill (#40)

الترخيص

رخصة MIT - راجع LICENSE للتفاصيل.

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

هذه الأداة لأغراض تعليمية فقط. كن مراعيًا لقوانين الخصوصية في نطاق اختصاصك عند مراقبة أجهزة البلوتوث. المؤلف غير مسؤول عن أي إساءة استخدام لهذا البرنامج.

أنشأه Danny McClelland