Vibeleaderboard
← Back to Tools
Index / tool

btrpa-scan

github.com/hackingdave/btrpa-scan
Visit github.com
Category
Cybersecurity
Rank
No. 1517Tools index

Previous survey · No. 1413 ·

Pricing
Open Source
Platform
cli · web
Type
TOOL
Builder
@HackingDave
GitHub
373 stars
Date

About

A Bluetooth Low Energy (BLE) scanner that can discover nearby devices, track specific devices by MAC address, and resolve privacy-randomized addresses using Identity Resolving Keys (IRKs). Features multiple scanning modes, RSSI filtering, distance estimation, and both terminal and web GUI interfaces.

What it does

It turns nearby BLE advertisements into a searchable, filterable observation stream. Operators can smooth signal readings, estimate proximity under different path-loss assumptions, attach GPS coordinates, inspect advertisement details, and compare changing private addresses against supplied identity keys.

Why it's ranked here

The tool combines practical field output, careful key handling, cross-platform scanning, and tested cryptographic matching in one installable command. The verdict is tempered by approximate ranging, platform-specific privileges, an undocumented macOS dependency, and contradictory license declarations that should be resolved before redistribution.

What's good

Long scans can stream records without unbounded memory growth. Identity keys can come from files or an environment variable and are masked in output. Sliding-window filtering reduces noisy readings, while CSV, JSON, JSONL, terminal, and browser views support both live investigation and later analysis. Tests cover key parsing, address resolution, distance calculations, and averaging behavior.

Tradeoffs

Useful operation requires Bluetooth hardware, and Linux scanning may need elevated capability. macOS address access relies on an undocumented API, while its active-scan switch changes nothing. GPS needs a separate daemon and receiver. Distance remains a path-loss estimate, requires advertised transmit power or manual calibration, and can vary with walls and interference. Windows terminal mode needs an extra curses package.

How to use it well

Use it for BLE field surveys, repeated device hunts, and collecting observations for downstream analysis. Start with signal averaging and the matching environment preset, then calibrate reference signal strength when proximity matters. Prefer key files or environment input over command-line secrets. Treat the output as evidence for investigation, not precision ranging or a replacement for GPS hardware.

Technical notes+

pyproject.toml uses Hatchling, requires Python 3.9+, registers btrpa-scan = "btrpa_scan.cli:main", and keeps Flask plus Flask-SocketIO in the gui extra. Core scanning uses Bleak and RPA matching uses cryptography AES primitives in btrpa_scan/cli.py. That file embeds the Flask interface and its HTML, CSS, and JavaScript rather than separating frontend assets. btrpa-scan.py substantially duplicates the packaged CLI implementation, while test_btrpa_scan.py imports the legacy hyphenated module rather than the registered package entry point. Packaging metadata declares MIT, but LICENSE contains Apache License 2.0 terms, creating a concrete licensing inconsistency.

Observed

Primary language
Python
License
Conflicting declarations: pyproject.toml says MIT, while LICENSE contains Apache License 2.0.
Packaging
PEP 621 package built with Hatchling; installable through pip, uv tool, or uvx.
Interfaces
Registered CLI with scrolling output, curses TUI, optional Flask web GUI, and CSV, JSON, or JSONL export.
Platform support
README lists macOS, Linux, and Windows with platform-specific Bluetooth behavior.
Testing structure
A root-level pytest file covers IRK parsing, RPA resolution, distance estimation, RSSI averaging, timestamps, masking, and GUI parameters.

Read from README.md, pyproject.toml, requirements.txt, btrpa-scan.py, test_btrpa_scan.py, btrpa_scan/cli.py, btrpa_scan/__init__.py, btrpa_scan/__main__.py, LICENSE, CHANGELOG.md.

What it can do

  • Discover nearby Bluetooth Low Energy devices

    BLE scanning parameters and filters → List of discovered BLE devices with metadata

  • Track specific devices by MAC address

    Target MAC address and scanning duration → Device tracking data and location history

  • Resolve privacy-randomized addresses

    Randomized BLE addresses and Identity Resolving Keys (IRKs) → Resolved true device identities

  • Filter devices by signal strength

    RSSI threshold values and scanning data → Filtered list of devices meeting signal strength criteria

  • Estimate distance to BLE devices

    RSSI values and device transmission power → Estimated distance measurements to devices

  • Stamp GPS coordinates on device discoveries

    GPS location data and BLE scan results → Geographically tagged device discovery records

Tags

bluetoothblescannerprivacyirkrssiclisecurity

Tech Stack

Python

Comments (0)

No comments yet

Editorially curated, with community endorsements as a secondary signal. Corrections welcome.