ब्लूहुड

ब्लूटूथ नेबरहुड - अपने क्षेत्र में BLE उपकरणों को ट्रैक करें और ट्रैफ़िक पैटर्न का विश्लेषण करें।

चेतावनी: अल्फा सॉफ्टवेयर

यह प्रोजेक्ट प्रारंभिक विकास में है और उत्पादन उपयोग के लिए तैयार नहीं है। सुविधाएँ बिना सूचना के बदल सकती हैं, टूट सकती हैं या हटाई जा सकती हैं। अपने जोखिम पर उपयोग करें। एकत्रित डेटा को प्रयोगात्मक माना जाना चाहिए।

स्क्रीनशॉट

फ़िल्टरिंग, खोज और रीयल-टाइम सांख्यिकी के साथ उपकरण सूची दर्शाने वाला मुख्य डैशबोर्ड

टैब वाला कॉन्फ़िगरेशन पृष्ठ — अलर्ट, संचालन, समूह और सुरक्षा

प्रोजेक्ट जानकारी और क्षमता अवलोकन वाला इंटेल पृष्ठ

क्यों?

यह प्रोजेक्ट WhisperPair भेद्यता (CVE-2025-36911) से प्रेरित था, जिसने ब्लूटूथ उपकरणों में गोपनीयता जोखिमों को उजागर किया।

हज़ारों ब्लूटूथ उपकरण हमारे चारों ओर हर समय मौजूद रहते हैं: फ़ोन, कार, टीवी, हेडफ़ोन, श्रवण यंत्र, डिलीवरी वाहन, और भी बहुत कुछ। ब्लूहुड दर्शाता है कि इन उपकरणों को निष्क्रिय रूप से पहचानना और उनकी उपस्थिति में पैटर्न देखना कितना सरल है।

पर्याप्त डेटा के साथ, आप संभावित रूप से यह कर सकते हैं:

• समझ सकते हैं कि कोई व्यक्ति आमतौर पर अपने कुत्ते को किस समय टहलाता है
• पता लगा सकते हैं कि कोई आगंतुक कब घर पर आता है
• उपकरणों की उपस्थिति के आधार पर दैनिक दिनचर्या में पैटर्न की पहचान कर सकते हैं

यह मेटाडेटा उपकरणों के साथ किसी भी सक्रिय इंटरैक्शन के बिना आश्चर्यजनक रूप से व्यक्तिगत जानकारी प्रकट कर सकता है।

ब्लूहुड ब्लूटूथ गोपनीयता के बारे में जागरूकता बढ़ाने के लिए एक शैक्षिक उपकरण है। यह एक वीकेंड प्रोजेक्ट है, लेकिन इसके निहितार्थों पर विचार करने लायक हैं।

क्या?

ब्लूहुड एक ब्लूटूथ स्कैनर है जो:

• लगातार स्कैन करता है आस-पास के ब्लूटूथ उपकरणों को (BLE और क्लासिक दोनों)
• उपकरणों की पहचान करता है विक्रेता (MAC पता लुकअप) और BLE सेवा UUID द्वारा
• उपकरणों को वर्गीकृत करता है श्रेणियों में (फ़ोन, ऑडियो, पहनने योग्य, IoT, वाहन, आदि)
• उपस्थिति पैटर्न को ट्रैक करता है समय के साथ घंटे/दैनिक हीटमैप के साथ
• रैंडमाइज़्ड MAC पतों से शोर को फ़िल्टर करता है (गोपनीयता-घूर्णित उपकरण)
• उपकरण सहसंबंध का विश्लेषण करता है ताकि एक साथ दिखाई देने वाले उपकरण मिल सकें
• पुश सूचनाएँ भेजता है जब देखे गए उपकरण आते या जाते हैं
• निगरानी और विश्लेषण के लिए एक वेब डैशबोर्ड प्रदान करता है

सुविधाएँ

स्कैनिंग

• दोहरी-मोड स्कैनिंग: ब्लूटूथ लो एनर्जी (BLE) और क्लासिक ब्लूटूथ
• MAC पता विक्रेता लुकअप (स्थानीय डेटाबेस + ऑनलाइन API फ़ॉलबैक)
• सटीक उपकरण वर्गीकरण के लिए BLE सेवा UUID फ़िंगरप्रिंटिंग
• क्लासिक ब्लूटूथ उपकरण वर्ग पार्सिंग
• रैंडमाइज़्ड MAC फ़िल्टरिंग (मुख्य दृश्य से छिपा हुआ)

उपकरण प्रबंधन

• व्यक्तिगत उपकरणों को ट्रैक करने के लिए "देखे गए" के रूप में चिह्नित करें
• उपकरणों को कस्टम समूहों में व्यवस्थित करें
• ज्ञात उपकरणों के लिए मैत्रीपूर्ण नाम सेट करें
• किसी भी उपकरण में कस्टम नोट/टैग जोड़ें
• उपकरण प्रकार पहचान (फ़ोन, ऑडियो, पहनने योग्य, IoT, वाहन, आदि)

विश्लेषण

• 30-दिन उपस्थिति समयरेखा विज़ुअलाइज़ेशन
• सिग्नल स्ट्रेंथ (RSSI) इतिहास चार्ट 7-दिन के डेटा के साथ
• घंटे और दैनिक गतिविधि हीटमैप दर्शाते हैं कि उपकरण कब सक्रिय हैं
• पैटर्न विश्लेषण ("कार्यदिवस, शाम 5PM-9PM")
• ठहराव समय विश्लेषण उपकरणों द्वारा सीमा में बिताए गए कुल समय को दर्शाता है
• उपकरण सहसंबंध पहचान ताकि एक साथ दिखाई देने वाले उपकरण मिल सकें
• निकटता क्षेत्र (तत्काल, निकट, दूर, दूरस्थ) सिग्नल स्ट्रेंथ पर आधारित
• MAC, विक्रेता या नाम द्वारा खोज
• ऐतिहासिक क्वेरी के लिए दिनांक सीमा खोज

सूचनाएँ (ntfy.sh के माध्यम से)

• आपके फ़ोन/डेस्कटॉप पर पुश सूचनाएँ
• जब नए उपकरण का पता चले तो सूचित करें
• जब देखे गए उपकरण वापस आएँ तो सूचित करें
• जब देखे गए उपकरण चले जाएँ तो सूचित करें
• आगमन/प्रस्थान के लिए कॉन्फ़िगरेबल थ्रेशोल्ड

संचालन

• हार्टबीट चेक-इन — समय-समय पर एक अपटाइम मॉनिटरिंग सेवा (जैसे, अपटाइम कुमा, हेल्थचेक्स.आईओ) पर स्थिति POST करता है
• स्टोरेज रोटेशन — कॉन्फ़िगरेबल दिनों से पुराने दर्शन को स्वचालित रूप से हटाता है
• दोनों वेब UI या पर्यावरण चर के माध्यम से कॉन्फ़िगर करने योग्य

वेब इंटरफ़ेस

• विभिन्न प्रदर्शन प्राथमिकताओं के लिए कॉम्पैक्ट/विस्तृत दृश्य टॉगल
• सुरक्षित साझाकरण के लिए MAC और नामों को अस्पष्ट करने के लिए स्क्रीनशॉट मोड
• पावर उपयोगकर्ताओं के लिए कीबोर्ड शॉर्टकट (देखने के लिए ? दबाएँ)
• उपकरण डेटा का CSV निर्यात
• संबंधित उपकरणों को व्यवस्थित करने के लिए उपकरण समूह
• पहुँच सुरक्षित करने के लिए वैकल्पिक प्रमाणीकरण

कैसे?

डॉकर के साथ त्वरित प्रारंभ (अनुशंसित)

पूर्वापेक्षाएँ — केवल Linux होस्ट

ब्लूहुड ब्लूज़ (Linux ब्लूटूथ स्टैक) के माध्यम से आपके ब्लूटूथ एडाप्टर से संचार करता है। कंटेनर शुरू करने से पहले होस्ट पर ब्लूज़ स्थापित और चल रहा होना चाहिए — डॉकर इमेज में स्वयं यह शामिल नहीं है।

root@kitploit:~

# डेबियन / उबंटू (उबंटू सर्वर सहित)
sudo apt install bluez
sudo systemctl enable --now bluetooth

# आर्क लिनक्स
sudo pacman -S bluez bluez-utils
sudo systemctl enable --now bluetooth

होस्ट पर ब्लूज़ के बिना आपको इस तरह की त्रुटि दिखाई देगी: BLE scan error: [org.freedesktop.DBus.Error.ServiceUnknown] The name org.bluez was not provided by any .service files

# एक docker-compose.yml बनाएँ या इस रेपो से डाउनलोड करें
# फिर डॉकर कंपोज़ के साथ प्रारंभ करें
docker compose up -d

# लॉग देखें
docker compose logs -f

डॉकर इमेज GitHub कंटेनर रजिस्ट्री पर उपलब्ध है:

ghcr.io/dannymcc/bluehood:latest

वेब डैशबोर्ड http://localhost:8080 पर उपलब्ध होगा।

डॉकर आवश्यकताएँ

• डॉकर और डॉकर कंपोज़
• Linux होस्ट जिसमें BLE-सक्षम ब्लूटूथ एडाप्टर (ब्लूटूथ 4.0+) हो जो केंद्रीय भूमिका का समर्थन करता हो
• होस्ट पर ब्लूज़ स्थापित और चल रहा हो (sudo apt install bluez && sudo systemctl enable --now bluetooth)

नोट: पुराने एडाप्टर (ब्लूटूथ 2.x/3.x) BLE स्कैनिंग का समर्थन नहीं करते। यदि आपके एडाप्टर में BLE केंद्रीय भूमिका समर्थन नहीं है, तो आप देखेंगे: No Bluetooth adapters with BLE 'central' role found।

नोट: डॉकर ब्लूटूथ पहुँच के लिए विशेषाधिकार प्राप्त मोड और होस्ट नेटवर्किंग में चलता है। BLE स्कैनिंग के लिए यह आवश्यक है।

डॉकर पर्यावरण चर

ब्लूटूथ एडाप्टर आवश्यकताएँ

ब्लूहुड को BLE-सक्षम ब्लूटूथ एडाप्टर (ब्लूटूथ 4.0 या बाद का) चाहिए जिसमें केंद्रीय भूमिका समर्थन हो। पुराने ब्लूटूथ 2.x/3.x एडाप्टर BLE स्कैनिंग का समर्थन नहीं करते और काम नहीं करेंगे।

यदि आपका एडाप्टर BLE केंद्रीय भूमिका का समर्थन नहीं करता है, तो ब्लूहुड इस त्रुटि के साथ बाहर निकल जाएगा:

No Bluetooth adapters with BLE 'central' role found

आप bluetoothctl show के साथ अपने एडाप्टर की क्षमताओं की जाँच कर सकते हैं और समर्थित भूमिकाओं में central देख सकते हैं।

मैन्युअल स्थापना (Linux)

# सिस्टम निर्भरताएँ स्थापित करें (आर्क लिनक्स)
sudo pacman -S bluez bluez-utils python-pip

# सिस्टम निर्भरताएँ स्थापित करें (डेबियन/उबंटू)
sudo apt install bluez python3-pip

# क्लोन और स्थापित करें
git clone https://github.com/dannymcc/bluehood.git
cd bluehood
pip install -e .

ब्लूटूथ अनुमतियाँ

ब्लूटूथ स्कैनिंग के लिए उन्नत विशेषाधिकारों की आवश्यकता होती है। कोई एक चुनें:

1. रूट के रूप में चलाएँ (सबसे सरल):

   root@kitploit:~

   sudo bluehood
   

2. पायथन को क्षमताएँ प्रदान करें:

   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

ब्लूहुड डॉकर के बिना मूल रूप से macOS पर काम करता है। macOS ब्लूज़ के बजाय CoreBluetooth का उपयोग करता है, जो bleak लाइब्रेरी द्वारा स्वचालित रूप से संभाला जाता है।

# रिपॉजिटरी क्लोन करें
git clone https://github.com/dannymcc/bluehood.git
cd bluehood

# एक वर्चुअल वातावरण बनाएँ
python3 -m venv .venv
source .venv/bin/activate

# स्थापित करें
pip install -e .

# चलाएँ
python -m bluehood.daemon

वेब डैशबोर्ड http://localhost:8080 पर उपलब्ध होगा।

नोट: पहली बार चलाने पर, macOS आपको ब्लूटूथ पहुँच की अनुमति देने का संकेत देगा। स्कैनिंग के काम करने के लिए आपको यह अनुमति देनी होगी।

उपयोग

# वेब डैशबोर्ड के साथ प्रारंभ करें (डिफ़ॉल्ट पोर्ट 8080)
bluehood

# एक अलग पोर्ट निर्दिष्ट करें
bluehood --port 9000

# एक विशिष्ट ब्लूटूथ एडाप्टर का उपयोग करें
bluehood --adapter hci1

# BLE और क्लासिक स्कैनिंग के लिए अलग-अलग एडाप्टर का उपयोग करें (साथ-साथ)
bluehood --adapter hci0 --classic-adapter hci1

# उपलब्ध एडाप्टर सूचीबद्ध करें
bluehood --list-adapters

# वेब डैशबोर्ड अक्षम करें (केवल स्कैनिंग)
bluehood --no-web

# पोर्ट 9199 पर प्रोमेथियस मीट्रिक्स निर्यातक सक्षम करें
bluehood --metrics-port 9199

वेब डैशबोर्ड

डैशबोर्ड प्रदान करता है:

• उपकरण सूची प्रकार आइकन, विक्रेता, MAC, नाम, दर्शन, अंतिम बार देखा गया
• उपकरण फ़िल्टर प्रकार (फ़ोन, ऑडियो, IoT, आदि) और देखी गई स्थिति द्वारा
• खोज MAC, विक्रेता या नाम द्वारा
• दिनांक सीमा खोज एक विशिष्ट समय विंडो में देखे गए उपकरणों को खोजने के लिए
• टैब वाला सेटिंग पृष्ठ — अलर्ट, संचालन, समूह और सुरक्षा (हैश के माध्यम से सीधा-लिंक, जैसे, /settings#operations)
• उपकरण विवरण मोडल जिसमें शामिल हैं:
  • BLE सेवा फ़िंगरप्रिंट
  • घंटे/दैनिक गतिविधि हीटमैप
  • 30-दिन उपस्थिति समयरेखा
  • सिग्नल स्ट्रेंथ (RSSI) इतिहास चार्ट
  • पैटर्न विश्लेषण
  • ठहराव समय आँकड़े
  • सहसंबंधित उपकरण सूची
  • निकटता क्षेत्र संकेतक
  • ऑपरेटर नोट्स फ़ील्ड
  • समूह असाइनमेंट

कीबोर्ड शॉर्टकट

स्क्रीनशॉट मोड

स्क्रीनशॉट साझा करने से पहले संवेदनशील डेटा को अस्पष्ट करने के लिए साइडबार से स्क्रीनशॉट मोड सक्षम करें:

• MAC पते केवल पहले 2 ऑक्टेट दिखाते हैं (जैसे, AA:BB:XX:XX:XX:XX)
• मैत्रीपूर्ण नाम केवल पहले 2 वर्ण दिखाते हैं (जैसे, Da********)
• CSV निर्यात भी स्क्रीनशॉट मोड का सम्मान करता है

पुश सूचनाएँ

ब्लूहुड ntfy.sh के माध्यम से पुश सूचनाएँ भेज सकता है, जो एक मुफ़्त, ओपन-सोर्स सूचना सेवा है।

1. ntfy.sh पर एक विषय बनाएँ (जैसे, bluehood-myname-alerts)
2. ntfy ऐप का उपयोग करके अपने फ़ोन पर विषय की सदस्यता लें
3. ब्लूहुड सेटिंग में, अपना विषय नाम दर्ज करें और सूचनाएँ सक्षम करें
4. कॉन्फ़िगर करें कि कौन सी घटनाएँ सूचनाएँ ट्रिगर करें:
   • नया उपकरण पाया गया
   • देखा गया उपकरण वापस आता है (अनुपस्थित रहने के बाद)
   • देखा गया उपकरण जाता है (X मिनट तक नहीं दिखता)

डेटा संग्रहण

डेटा ~/.local/share/bluehood/bluehood.db (SQLite) में संग्रहीत किया जाता है।

पर्यावरण चर के साथ स्थान को ओवरराइड करें:

• BLUEHOOD_DATA_DIR - डेटा फ़ाइलों के लिए निर्देशिका
• BLUEHOOD_DB_PATH - डेटाबेस फ़ाइल का सीधा पथ

नोट: हार्टबीट और प्रूनिंग सेटिंग्स को वेब UI (सेटिंग्स > संचालन) या पर्यावरण चर के माध्यम से कॉन्फ़िगर किया जा सकता है। GUI मान env vars पर प्राथमिकता लेते हैं।

यह कैसे काम करता है

उपकरण वर्गीकरण

ब्लूहुड कई संकेतों का उपयोग करके उपकरणों को वर्गीकृत करता है (प्राथमिकता क्रम में):

1. BLE सेवा UUIDs - सबसे सटीक (हृदय गति = पहनने योग्य, A2DP = ऑडियो, आदि)
2. उपकरण नाम पैटर्न - "iPhone", "Galaxy", "AirPods", आदि।
3. विक्रेता OUI लुकअप - Apple, Samsung, Bose, आदि।

रैंडमाइज़्ड MACs

आधुनिक उपकरण गोपनीयता के लिए अपने MAC पतों को रैंडमाइज़ करते हैं। ब्लूहुड:

• रैंडमाइज़्ड MACs का पता लगाता है (स्थानीय रूप से प्रशासित बिट)
• उन्हें मुख्य उपकरण सूची से छिपाता है (ट्रैकिंग के लिए उपयोगी नहीं)
• छिपे हुए रैंडमाइज़्ड उपकरणों की संख्या दिखाता है

पैटर्न विश्लेषण

ब्लूहुड पैटर्न का पता लगाने के लिए दर्शन टाइमस्टैम्प का विश्लेषण करता है:

• दिन का समय: सुबह, दोपहर, शाम, रात
• सप्ताह का दिन: कार्यदिवस, सप्ताहांत
• आवृत्ति: स्थिर, दैनिक, नियमित, सामयिक, दुर्लभ

उदाहरण पैटर्न: "दैनिक, शाम (5PM-9PM)", "कार्यदिवस, सुबह (8AM-12PM)"

उपकरण सहसंबंध

ब्लूहुड उन उपकरणों का पता लगाता है जो एक कॉन्फ़िगरेबल समय विंडो के भीतर अक्सर एक साथ दिखाई देते हैं। यह प्रकट कर सकता है:

• एक ही व्यक्ति के स्वामित्व वाले उपकरण (फ़ोन + स्मार्टवॉच)
• एक साथ यात्रा करने वाले लोग
• एक शेड्यूल साझा करने वाले उपकरण

निकटता क्षेत्र

RSSI सिग्नल स्ट्रेंथ के आधार पर, उपकरणों को निकटता क्षेत्रों में वर्गीकृत किया जाता है:

• तत्काल (> -50 dBm): बहुत करीब, कुछ मीटर के भीतर
• निकट (-50 से -60 dBm): पास में, एक ही कमरे में
• दूर (-60 से -70 dBm): और दूर, आस-पास के कमरे
• दूरस्थ (< -70 dBm): दूर, पहचान सीमा के किनारे पर

ठहराव समय विश्लेषण

दर्शनों के बीच अंतराल का विश्लेषण करके ट्रैक करता है कि उपकरण सीमा में कितना समय बिताते हैं। एक कॉन्फ़िगरेबल अंतराल थ्रेशोल्ड (डिफ़ॉल्ट 15 मिनट) यह निर्धारित करता है कि एक नया "सत्र" कब शुरू होता है।

प्रोमेथियस मीट्रिक्स

ब्लूहुड प्रोमेथियस स्क्रैपिंग के लिए मीट्रिक्स को उजागर कर सकता है। BLUEHOOD_METRICS_PORT पर्यावरण चर या --metrics-port CLI फ़्लैग सेट करके सक्षम करें।

# पर्यावरण चर के माध्यम से
export BLUEHOOD_METRICS_PORT=9199

# CLI के माध्यम से
bluehood --metrics-port 9199

मीट्रिक्स http://host:9199/metrics पर उपलब्ध हैं।

उपलब्ध मीट्रिक्स

ग्राफ़ाना डैशबोर्ड

आयात के लिए तैयार ग्राफ़ाना डैशबोर्ड grafana/bluehood-dashboard.json पर शामिल है। इसे ग्राफ़ाना UI (डैशबोर्ड > आयात) या API के माध्यम से आयात करें:

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 (ब्लूटूथ 4.0+) का समर्थन करता है — पुराने एडाप्टर काम नहीं करेंगे
• सुनिश्चित करें कि ब्लूटूथ एडाप्टर सक्षम है: bluetoothctl power on
• जाँचें कि एडाप्टर का पता चला है: bluehood --list-adapters
• यदि अनुमति से वंचित है तो sudo के साथ चलाएँ

डॉकर समस्याएँ

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

ब्लूज़ स्थापित नहीं है या होस्ट पर नहीं चल रहा है। समाधान:

sudo apt install bluez          # डेबियन/उबंटू
sudo systemctl enable --now bluetooth
docker compose restart

सामान्य जाँच सूची:

• सुनिश्चित करें कि ब्लूज़ होस्ट पर स्थापित है (केवल कंटेनर में नहीं)
• सत्यापित करें कि ब्लूटूथ सेवा चल रही है: systemctl status bluetooth
• पुष्टि करें कि आपका एडाप्टर दिखाई दे रहा है: bluetoothctl list

योगदान

योगदान का स्वागत है! कृपया GitHub पर एक मुद्दा या PR खोलें।

योगदानकर्ता

• @martinh2011 (Martin Hüser) - MAC विक्रेता कैश सुधार
• @hatedabamboo (Kirill Solovei) - हल्की थीम समर्थन
• @krnltrp - वेब UI संवर्द्धन
• @jacobpretorius (Jacob Pretorius) - CSV निर्यात JS फिक्स (#14), सेटिंग खोलने के लिए क्लिक (#16)
• @unqualifiedkoala - BLE एडाप्टर आवश्यकताओं का दस्तावेज़ीकरण
• @dazzag24 - macOS पता प्रारूप समस्या की रिपोर्ट
• @floese (W.A.Flozart) - फ़ायरफ़ॉक्स डबलक्लिक फिक्स (#29)
• @GeiserX (Sergio Fernández) - प्रोमेथियस मीट्रिक्स निर्यातक (#35), गैर-अवरुद्ध विक्रेता DB फिक्स (#37), दोहरी-एडाप्टर स्कैनिंग (#33), rfkill के साथ मजबूत स्कैन रिकवरी (#40)

लाइसेंस

MIT लाइसेंस - विवरण के लिए LICENSE देखें।

अस्वीकरण

यह उपकरण केवल शैक्षिक उद्देश्यों के लिए है। ब्लूटूथ उपकरणों की निगरानी करते समय अपने क्षेत्राधिकार में गोपनीयता कानूनों का ध्यान रखें। लेखक इस सॉफ्टवेयर के किसी भी दुरुपयोग के लिए जिम्मेदार नहीं है।

Danny McClelland द्वारा निर्मित