hackingdave/btrpa-scanماسح Bluetooth Low Energy (BLE) مع حل Resolvable Private Address (RPA) باستخدام Identity Resolving Keys (IRKs)
ماسح ضوئي لتقنية البلوتوث منخفض الطاقة (BLE) مع حل متقدم للعناوين الخاصة القابلة للحل (RPA). اكتشف أجهزة BLE القريبة، وتتبع جهازًا محددًا عبر عنوان MAC، أو حل العناوين العشوائية للخصوصية باستخدام مفتاح حل الهوية (IRK).
كتبه: David Kennedy (@HackingDave) الشركة: TrustedSec
-o -)يتطلب ختم موقع GPS تشغيل برنامج الخدمة gpsd مع مستقبل GPS متصل. إذا لم يكن gpsd قيد التشغيل، يستمر btrpa-scan بشكل طبيعي بدون GPS.
| المنصة | التثبيت | التشغيل |
|---|---|---|
| macOS | brew install gpsd | gpsd -n /dev/tty.usbserial-* |
| Debian/Ubuntu | sudo apt install gpsd gpsd-clients | sudo systemctl start gpsd |
| Fedora/RHEL | sudo dnf install gpsd gpsd-clients | sudo systemctl start gpsd |
| Arch | sudo pacman -S gpsd | sudo systemctl start gpsd |
| ويندوز | استخدم gpsd عبر WSL أو MSYS2 | راجع تعليمات WSL أعلاه |
للتحقق من أن gpsd يعمل:
# Check that gpsd is listening
gpspipe -w -n 5
# Or use the curses monitor
cgps
| المنصة | ملاحظات |
|---|---|
| macOS | يستخدم CoreBluetooth. يستفيد وضع IRK من واجهة برمجة تطبيقات غير موثقة لاسترجاع عناوين البلوتوث الحقيقية بدلاً من UUIDs. --active ليس له أي تأثير — يقوم CoreBluetooth دائمًا بالمسح النشط. |
| لينكس | قد يتطلب صلاحيات root أو خاصية CAP_NET_ADMIN للمسح. |
| ويندوز | واجهة WinRT Bluetooth الأصلية — عناوين MAC الحقيقية متاحة أصلاً. يتطلب TUI تثبيت pip install windows-curses. |
يستخدم هذا المشروع pyproject.toml (PEP 621)، معيار التغليف الحديث في بايثون. يعرّف المشروع كحزمة قابلة للتثبيت مع أمر CLI مسجل — لا حاجة لتشغيل ملفات .py مباشرة.
uvx btrpa-scan --all
uvx --from git+https://github.com/hackingdave/btrpa-scan.git btrpa-scan --all
uv tool install btrpa-scan
أو مباشرة من GitHub:
uv tool install git+https://github.com/hackingdave/btrpa-scan.git
pip install btrpa-scan
لدعم الواجهة الرسومية (واجهة الرادار القائمة على Flask):
pip install btrpa-scan[gui]
git clone https://github.com/hackingdave/btrpa-scan.git
cd btrpa-scan
pip install .
usage: btrpa-scan [-h] [-a] [--irk HEX] [--irk-file PATH] [-t TIMEOUT]
[--output {csv,json,jsonl}] [-o FILE] [--log FILE]
[-v | -q] [--min-rssi DBM] [--rssi-window N] [--active]
[--environment {free_space,indoor,outdoor}]
[--ref-rssi DBM] [--name-filter PATTERN]
[--alert-within METERS] [--tui] [--gui] [--gui-port PORT]
[--no-gps] [--adapters LIST] [mac]
BLE Scanner — discover all devices or hunt for a specific one
positional arguments:
mac Target MAC address to search for (omit to scan all)
optional arguments:
-h, --help show this help message and exit
-a, --all Scan for all broadcasting devices
--irk HEX Resolve RPAs using this Identity Resolving Key (32 hex chars)
--irk-file PATH Read IRK(s) from a file (one per line, hex format)
-t, --timeout TIMEOUT Scan timeout in seconds (default: 30, or infinite for --irk)
--output {csv,json,jsonl}
Batch output format written at end of scan
-o, --output-file FILE
Output file path (default: btrpa-scan-results.<format>;
use - for stdout)
--log FILE Stream detections to a CSV file in real time
-v, --verbose Verbose mode — show additional details
-q, --quiet Quiet mode — suppress per-device output, show summary only
--min-rssi DBM Minimum RSSI threshold (e.g. -70) — ignore weaker signals
--rssi-window N RSSI sliding window size for averaging (default: 1 = no averaging)
--active Use active scanning (sends SCAN_REQ for additional data)
--environment {free_space,indoor,outdoor}
Distance estimation path-loss model (default: free_space)
--ref-rssi DBM Calibrated RSSI at 1 metre for distance estimation
--name-filter PATTERN Filter devices by name (case-insensitive substring match)
--alert-within METERS Proximity alert when device is within this distance
--tui Live-updating terminal table instead of scrolling output
--gui Launch web-based radar interface in the browser
--gui-port PORT Port for GUI web server (default: 5000)
--no-gps Disable GPS location stamping (GPS is on by default via gpsd)
--adapters LIST Comma-separated Bluetooth adapter names (e.g. hci0,hci1)
قم بفحص جميع أجهزة BLE التي تبث (المهلة الافتراضية 30 ثانية):
btrpa-scan --all
بمهلة مخصصة:
btrpa-scan --all -t 60
ابحث عن جهاز محدد عبر عنوان MAC:
btrpa-scan AA:BB:CC:DD:EE:FF
حل العناوين الخاصة القابلة للحل (RPA) باستخدام مفتاح حل الهوية. يعمل هذا الوضع إلى أجل غير مسمى افتراضيًا حتى يتم إيقافه بـ Ctrl+C:
btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF
يمكن توفير IRK بعدة صيغ:
| الصيغة | مثال |
|---|---|
| Hex عادي | 0123456789ABCDEF0123456789ABCDEF |
| مفصول بنقطتين | 01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF |
| مفصول بشرطة | 01-23-45-67-89-AB-CD-EF-01-23-45-67-89-AB-CD-EF |
| مسبوق بـ 0x | 0x0123456789ABCDEF0123456789ABCDEF |
قم بتحميل مفتاح IRK واحد أو أكثر من ملف. يجب أن يحتوي كل سطر على IRK واحد بأي صيغة hex مدعومة. الأسطر التي تبدأ بـ # تُعامل كتعليقات:
btrpa-scan --irk-file keys.txt
مثال keys.txt:
# Alice's phone
0123456789ABCDEF0123456789ABCDEF
# Bob's watch
FEDCBA9876543210FEDCBA9876543210