Bluehood

Bluetooth Neighborhood - अपने क्षेत्र में BLE उपकरणों को ट्रैक करें और ट्रैफ़िक पैटर्न का विश्लेषण करें।

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

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

स्क्रीनशॉट

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

टैब्ड कॉन्फ़िगरेशन पृष्ठ — Alerts, Operations, Groups, और Security

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

क्यों?

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

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

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

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

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

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

क्या?

Bluehood एक Bluetooth स्कैनर है जो:

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

विशेषताएँ

स्कैनिंग

• दोहरे मोड की स्कैनिंग: Bluetooth Low Energy (BLE) और Classic Bluetooth
• MAC address विक्रेता lookup (स्थानीय डेटाबेस + ऑनलाइन API fallback)
• सटीक उपकरण वर्गीकरण के लिए BLE service UUID fingerprinting
• Classic Bluetooth device class parsing
• रैंडमाइज़्ड MAC फ़िल्टरिंग (मुख्य दृश्य से छिपा हुआ)

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

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

विश्लेषिकी

• 30-दिन की उपस्थिति टाइमलाइन विज़ुअलाइज़ेशन
• सिग्नल स्ट्रेंथ (RSSI) इतिहास चार्ट 7-दिन के डेटा के साथ
• प्रति घंटा और दैनिक गतिविधि हीटमैप दिखाते हुए कि उपकरण कब सक्रिय हैं
• पैटर्न विश्लेषण ("Weekdays, evenings 5PM-9PM")
• Dwell time विश्लेषण दिखाते हुए कि उपकरण कुल कितना समय रेंज में बिताते हैं
• उपकरण सहसंबंध पता लगाना साथ दिखने वाले उपकरणों को खोजने के लिए (co-presence और synchronized arrival/departure)
• MAC-rotation linkage ("Likely same device") — समय में हैंडऑफ़ करने वाले, समान सिग्नल स्ट्रेंथ साझा करने वाले, और समान कैडेंस पर पिंग करने वाले रैंडमाइज़्ड identifiers को heuristic रूप से जोड़ता है
• निकटता क्षेत्र (immediate, near, far, remote) सिग्नल स्ट्रेंथ के आधार पर
• MAC, विक्रेता, या नाम से खोजें
• ऐतिहासिक क्वेरी के लिए दिनांक सीमा खोज

नोटिफ़िकेशन (ntfy के माध्यम से)

• ntfy.sh या self-hosted ntfy सर्वर के माध्यम से अपने फ़ोन/डेस्कटॉप पर पुश नोटिफ़िकेशन
• नए उपकरणों का पता चलने पर सूचित करें
• watched उपकरणों के वापस आने पर सूचित करें
• watched उपकरणों के जाने पर सूचित करें
• आगमन/प्रस्थान के लिए कॉन्फ़िगर करने योग्य थ्रेशोल्ड

संचालन

• Heartbeat check-in — समय-समय पर uptime monitoring सेवा (जैसे, Uptime Kuma, Healthchecks.io) पर status POST करें
• Storage rotation — कॉन्फ़िगर करने योग्य दिनों से पुरानी sightings को स्वचालित रूप से prune करें; वैकल्पिक रूप से pruning को उन पूरे stale उपकरणों तक सीमित करें जो न्यूनतम संख्या से कम बार देखे गए हों (watched उपकरण कभी prune नहीं होते)
• दोनों वेब UI से या environment variables के माध्यम से कॉन्फ़िगर करने योग्य

वेब इंटरफ़ेस

• Compact/Detailed view toggle विभिन्न प्रदर्शन प्राथमिकताओं के लिए
• Screenshot mode सुरक्षित साझा करने के लिए MACs और नामों को अस्पष्ट करने के लिए
• कीबोर्ड शॉर्टकट पावर उपयोगकर्ताओं के लिए (? दबाकर देखें)
• CSV export विस्तृत उपकरण डेटा का (MAC, विक्रेता, identifier, प्रकार, BT प्रकार, device class, watched/ignored flags, first/last seen, sightings, समूह, service UUIDs, और नोट्स) — पूरे फ़िल्टर किए गए सेट को export करता है, केवल वर्तमान पृष्ठ को नहीं
• उपकरण समूह संबंधित उपकरणों को व्यवस्थित करने के लिए
• वैकल्पिक प्रमाणीकरण पहुँच सुरक्षित करने के लिए

कैसे?

Docker के साथ त्वरित शुरुआत (अनुशंसित)

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

Bluehood BlueZ, Linux Bluetooth स्टैक के माध्यम से आपके Bluetooth adapter के साथ संचार करता है। कंटेनर शुरू करने से पहले होस्ट पर BlueZ इंस्टॉल और चालू होना चाहिए — Docker image में स्वयं यह शामिल नहीं है।

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 image GitHub Container Registry पर उपलब्ध है:

ghcr.io/dannymcc/bluehood:latest

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

Docker आवश्यकताएँ

• Docker और Docker Compose
• BLE-सक्षम Bluetooth adapter (Bluetooth 4.0+) वाला Linux होस्ट जो Central role का समर्थन करता हो
• होस्ट पर BlueZ इंस्टॉल और चालू (sudo apt install bluez && sudo systemctl enable --now bluetooth)

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

नोट: Docker Bluetooth पहुँच के लिए privileged mode में host networking के साथ चलता है। यह BLE स्कैनिंग के लिए आवश्यक है।

Docker Environment Variables

Bluetooth Adapter आवश्यकताएँ

Bluehood को Central role समर्थन वाले BLE-सक्षम Bluetooth adapter (Bluetooth 4.0 या बाद का) की आवश्यकता है। पुराने Bluetooth 2.x/3.x adapters BLE स्कैनिंग का समर्थन नहीं करते और काम नहीं करेंगे।

यदि आपका adapter BLE Central role का समर्थन नहीं करता, तो Bluehood इस संदेश के साथ बाहर निकल जाएगा:

No Bluetooth adapters with BLE 'central' role found

आप bluetoothctl show के साथ अपने adapter की क्षमताओं की जाँच कर सकते हैं और समर्थित roles में 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 .

Bluetooth अनुमतियाँ

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

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

   root@kitploit:~

   sudo bluehood
   

2. Python को capabilities दें:

   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 BlueZ के बजाय CoreBluetooth का उपयोग करता है, जिसे 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 आपको Bluetooth पहुँच की अनुमति देने के लिए प्रेरित करेगा। स्कैनिंग काम करने के लिए आपको यह अनुमति देनी होगी।

उपयोग

# 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, नाम, sightings, last seen के साथ
• उपकरण फ़िल्टर प्रकार (फ़ोन, ऑडियो, IoT, आदि) और watched स्थिति के अनुसार
• खोज MAC, विक्रेता, या नाम से
• दिनांक सीमा खोज किसी विशिष्ट समय विंडो में देखे गए उपकरणों को खोजने के लिए
• टैब्ड settings पृष्ठ — Alerts, Operations, Groups, और Security (hash के माध्यम से direct-link, जैसे /settings#operations)
• उपकरण विवरण modal के साथ:
  • BLE service fingerprints
  • प्रति घंटा/दैनिक गतिविधि हीटमैप
  • 30-दिन की उपस्थिति टाइमलाइन
  • सिग्नल स्ट्रेंथ (RSSI) इतिहास चार्ट
  • पैटर्न विश्लेषण
  • Dwell time आँकड़े
  • सहसंबंधित उपकरण सूची
  • Likely same device (MAC rotation) सूची
  • निकटता क्षेत्र संकेतक
  • Operator notes फ़ील्ड
  • समूह असाइनमेंट

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

Screenshot Mode

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

• MAC addresses केवल पहले 2 octets दिखाते हैं (जैसे, AA:BB:XX:XX:XX:XX)
• Friendly names केवल पहले 2 अक्षर दिखाते हैं (जैसे, Da********)
• CSV exports भी screenshot mode का पालन करते हैं

पुश नोटिफ़िकेशन

Bluehood ntfy के माध्यम से पुश नोटिफ़िकेशन भेज सकता है, जो एक मुफ़्त, ओपन-सोर्स नोटिफ़िकेशन सेवा है। आप सार्वजनिक ntfy.sh सर्वर या अपने स्वयं के self-hosted instance का उपयोग कर सकते हैं।

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

डेटा संग्रहण

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

environment variables के साथ स्थान ओवरराइड करें:

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

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

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

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

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

1. BLE Service UUIDs - सबसे सटीक (Heart Rate = wearable, A2DP = audio, आदि)
2. उपकरण नाम पैटर्न - "iPhone", "Galaxy", "AirPods", आदि
3. विक्रेता OUI lookup - Apple, Samsung, Bose, आदि

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

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

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

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

Bluehood पैटर्न का पता लगाने के लिए sighting timestamps का विश्लेषण करता है:

• दिन का समय: सुबह, दोपहर, शाम, रात
• सप्ताह का दिन: Weekdays, Weekends
• आवृत्ति: Constant, Daily, Regular, Occasional, Rare

उदाहरण पैटर्न: "Daily, evenings (5PM-9PM)", "Weekdays, morning (8AM-12PM)"

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

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

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

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

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

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

Dwell Time विश्लेषण

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

Prometheus Metrics

Bluehood Prometheus scraping के लिए metrics उजागर कर सकता है। BLUEHOOD_METRICS_PORT environment variable या --metrics-port CLI flag सेट करके सक्षम करें।

# Via environment variable
export BLUEHOOD_METRICS_PORT=9199

# Via CLI
bluehood --metrics-port 9199

Metrics http://host:9199/metrics पर प्रदान किए जाते हैं।

उपलब्ध Metrics

Grafana डैशबोर्ड

एक ready-to-import Grafana डैशबोर्ड grafana/bluehood-dashboard.json पर शामिल है। इसे Grafana UI (Dashboards > Import) या API के माध्यम से 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}"

समस्या निवारण

कोई उपकरण नहीं मिला

• सुनिश्चित करें कि आपका adapter Central role के साथ BLE (Bluetooth 4.0+) का समर्थन करता है — पुराने adapters काम नहीं करेंगे
• सुनिश्चित करें कि Bluetooth adapter सक्षम है: bluetoothctl power on
• जाँचें कि adapter पता चला है: 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 होस्ट पर इंस्टॉल है (केवल कंटेनर में नहीं)
• सत्यापित करें कि Bluetooth सेवा चल रही है: systemctl status bluetooth
• पुष्टि करें कि आपका adapter दिखाई दे रहा है: bluetoothctl list

योगदान

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

योगदानकर्ता

• @martinh2011 (Martin Hüser) - MAC vendor cache improvements
• @hatedabamboo (Kirill Solovei) - Light theme support
• @krnltrp - Web UI enhancements
• @jacobpretorius (Jacob Pretorius) - CSV export JS