btrpa-scan

고급 RPA(Resolvable Private Address) 해석 기능을 갖춘 BLE(Bluetooth Low Energy) 스캐너입니다. 주변 BLE 기기를 탐지하고, MAC 주소로 특정 기기를 추적하거나, IRK(Identity Resolving Key)를 사용하여 개인정보 보호를 위해 무작위화된 주소를 해석할 수 있습니다.

제작: David Kennedy (@HackingDave) 회사: TrustedSec

기능

• 모든 기기 탐지 - 범위 내에서 브로드캐스팅 중인 모든 BLE 기기를 신호 강도, 예상 거리, 제조업체 데이터, 서비스 UUID와 함께 스캔합니다.
• 대상 검색 - MAC 주소로 특정 기기를 검색하고 모든 탐지를 모니터링합니다.
• IRK 해석 - 하나 이상의 IRK(Identity Resolving Key)에 대해 RPA(Resolvable Private Address)를 해석하여 개인정보 보호를 위해 무작위 주소를 사용하는 기기를 식별합니다.
• 다중 IRK - 파일에서 여러 IRK를 로드하여 단일 스캔으로 여러 기기의 주소를 해석합니다.
• RSSI 필터링 - 최소 RSSI 임계값으로 약한 신호를 걸러냅니다.
• RSSI 평균화 - 슬라이딩 윈도우 평균으로 노이즈가 많은 BLE RSSI 판독값을 평활화하여 보다 안정적인 거리 추정을 제공합니다.
• 이름 필터링 - 대소문자를 구분하지 않는 부분 문자열 일치로 기기 이름을 필터링합니다.
• 액티브 스캐닝 - SCAN_REQ를 전송하여 패시브 스캐닝이 놓치는 추가 서비스 UUID와 기기 이름이 포함된 SCAN_RSP를 수신합니다.
• 환경 프리셋 - 보다 정확한 거리 추정을 위한 실내, 실외, 자유 공간 경로 손실 모델.
• 근접 알림 - 기기가 설정 가능한 거리 내에 있는 것으로 추정되면 청각/시각 알림.
• 웹 GUI - 애니메이션 스윕, 거리 시각화, GPS 지도, 신호 강도 기반 기기 목록(고정/고정 해제), 호버 툴팁을 갖춘 브라우저 기반 레이더 인터페이스.
• 라이브 TUI - 신호 강도로 정렬된 curses 기반 실시간 업데이트 테이블.
• 실시간 CSV 로그 - 각 탐지를 발생 즉시 CSV 파일로 스트리밍.
• 일괄 내보내기 - 스캔 종료 시 결과를 CSV, JSON 또는 JSONL로 내보냅니다(-o -로 stdout 지원).
• GPS 위치 스탬핑 - gpsd를 통해 각 탐지에 GPS 좌표를 태깅하며, 기기별 최적 위치(가장 강한 RSSI = 가장 가까운 근접)를 추적합니다. 기본적으로 활성화되며, gpsd를 사용할 수 없으면 정상적으로 기능이 제한됩니다.
• 멀티 어댑터 - 여러 블루투스 어댑터로 동시에 스캔(Linux).
• 상세/조용 모드 - 상세 모드는 추가 세부 정보를 표시하고(예: IRK 모드에서 일치하지 않는 RPA), 조용 모드는 기기별 출력을 억제하고 요약만 표시합니다.

요구 사항

• Python 3.9+
• 블루투스 하드웨어
• 지원 OS: macOS, Linux, Windows
• gpsd(선택) — GPS 위치 스탬핑에 필요

gpsd 설치

GPS 위치 스탬핑에는 GPS 수신기가 연결된 상태에서 gpsd 데몬이 실행되고 있어야 합니다. 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
Windows	WSL 또는 MSYS2를 통해 gpsd 사용	위의 WSL 지침 참조

gpsd가 작동하는지 확인하려면:

# Check that gpsd is listening
gpspipe -w -n 5
# Or use the curses monitor
cgps

플랫폼 참고 사항

플랫폼	참고 사항
macOS	CoreBluetooth를 사용합니다. IRK 모드는 UUID 대신 실제 블루투스 주소를 얻기 위해 문서화되지 않은 API를 활용합니다. --active는 효과가 없습니다 — CoreBluetooth는 항상 액티브 스캔을 수행합니다.
Linux	스캔하려면 root 또는 CAP_NET_ADMIN 권한이 필요할 수 있습니다.
Windows	네이티브 WinRT Bluetooth API — 실제 MAC 주소를 기본적으로 사용할 수 있습니다. TUI에는 pip install windows-curses가 필요합니다.

설치

이 프로젝트는 최신 Python 패키징 표준인 pyproject.toml(PEP 621)을 사용합니다. 등록된 CLI 명령어가 있는 설치 가능한 패키지로 프로젝트를 정의하므로 .py 파일을 직접 실행할 필요가 없습니다.

빠른 실행(설치 불필요)

uvx btrpa-scan --all

GitHub에서 실행(설치 불필요)

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로 설치

pip install btrpa-scan

GUI 지원(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)

모드 1: 모든 기기 탐지

브로드캐스팅 중인 모든 BLE 기기를 스캔합니다(기본 30초 제한 시간):

btrpa-scan --all

사용자 지정 제한 시간 사용:

btrpa-scan --all -t 60

모드 2: 대상 검색

MAC 주소로 특정 기기를 검색합니다:

btrpa-scan AA:BB:CC:DD:EE:FF

모드 3: IRK 해석

IRK(Identity Resolving Key)를 사용하여 RPA(Resolvable Private Address)를 해석합니다. 이 모드는 기본적으로 Ctrl+C로 중지할 때까지 무기한 실행됩니다:

btrpa-scan --irk 0123456789ABCDEF0123456789ABCDEF

IRK는 여러 형식으로 제공할 수 있습니다:

형식	예시
일반 16진수	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를 로드합니다. 각 줄에는 지원되는 16진수 형식의 IRK 하나가 포함되어야 합니다. #로 시작하는 줄은 주석으로 처리됩니다:

btrpa-scan --irk-file keys.txt

keys.txt 예시:

# Alice's phone
0123456789ABCDEF0123456789ABCDEF
# Bob's watch
FEDCBA9876543210FEDCBA9876543210

여러 IRK가 로드되면 감지된 각 RPA가 모든 키에 대해 검사됩니다. 요약에는 모든 키에 걸친 총 일치 횟수가 표시됩니다.

환경 변수에서 IRK 로드

명령줄에 키를 전달하지 않으려면 BTRPA_IRK 환경 변수를 설정하세요:

export BTRPA_IRK=0123456789ABCDEF0123456789ABCDEF
btrpa-scan

우선순위: --irk > --irk-file > BTRPA_IRK

RSSI 필터링

신호 강도가 임계값 이상인 기기만 표시:

btrpa-scan --all --min-rssi -70

RSSI 평균화

BLE RSSI는 본질적으로 노이즈가 많습니다. 슬라이딩 윈도우 평균을 사용하면 더 안정적인 거리 추정과 허위 약한 탐지 필터링이 가능합니다:

btrpa-scan --all --rssi-window 5

윈도우링이 활성화되면 디스플레이에 원시 RSSI와 평균 RSSI가 모두 표시되며(예: RSSI: -65 dBm (avg: -62 dBm over 5 readings)), 거리 추정에는 평균 값이 사용됩니다. --min-rssi 필터도 평균 RSSI에 적용되므로 단일 노이즈 스파이크로 인해 기기가 목록에서 제외되지 않습니다.

이름 필터링

대소문자를 구분하지 않는 부분 문자열 일치로 기기 이름을 필터링합니다:

btrpa-scan --all --name-filter "AirPods"

광고된 이름에 지정된 패턴이 포함된 기기만 표시됩니다. 이름 필터가 활성화되면 이름이 없는 기기는 제외됩니다.

액티브 스캐닝

패시브 스캐닝(기본값)은 광고 패킷만 볼 수 있습니다. 액티브 스캐닝은 SCAN_REQ를 전송하고 SCAN_RSP를 받아 패시브 스캐닝이 놓치는 추가 서비스 UUID와 기기 이름을 확인할 수 있습니다:

btrpa-scan --all --active