Bluehood

Bluetooth Neighborhood - 주변의 BLE 기기를 추적하고 트래픽 패턴을 분석합니다.

경고: 알파 소프트웨어

이 프로젝트는 초기 개발 단계에 있으며 프로덕션 사용에 적합하지 않습니다. 기능은 예고 없이 변경되거나, 작동이 중단되거나, 제거될 수 있습니다. 사용에 따른 책임은 사용자에게 있습니다. 수집된 데이터는 실험적인 것으로 취급해야 합니다.

스크린샷

Dashboard 필터링, 검색, 실시간 통계가 포함된 기기 목록을 보여주는 메인 대시보드

Settings 탭으로 구성된 설정 페이지 — Alerts, Operations, Groups, Security

About 프로젝트 정보와 기능 개요가 담긴 Intel 페이지

왜?

이 프로젝트는 Bluetooth 기기의 프라이버시 위험을 부각시킨 WhisperPair 취약점 (CVE-2025-36911)에서 영감을 받았습니다.

수천 개의 Bluetooth 기기가 항상 우리 주변에 있습니다: 휴대폰, 자동차, TV, 헤드폰, 보청기, 배달 차량 등. Bluehood는 이러한 기기를 수동적으로 감지하고 그 존재 패턴을 관찰하는 것이 얼마나 간단한지 보여줍니다.

충분한 데이터가 있으면 잠재적으로 다음과 같은 것이 가능합니다:

누군가가 보통 몇 시에 개를 산책시키는지 파악
방문자가 집에 도착하는 시점 감지
기기 존재를 기반으로 일상 루틴의 패턴 식별

이러한 메타데이터는 기기와의 능동적인 상호작용 없이도 놀랍도록 사적인 정보를 드러낼 수 있습니다.

Bluehood는 Bluetooth 프라이버시에 대한 인식을 높이기 위한 교육용 도구입니다. 주말 프로젝트이지만, 그 시사점은 충분히 생각해볼 가치가 있습니다.

무엇?

Bluehood는 다음과 같은 Bluetooth 스캐너입니다:

주변 Bluetooth 기기(BLE 및 Classic 모두)를 지속적으로 스캔
MAC 주소 조회를 통한 벤더 식별 및 BLE 서비스 UUID로 기기 식별
기기를 카테고리(휴대폰, 오디오, 웨어러블, IoT, 차량 등)로 분류
시간별/일별 히트맵으로 시간 경과에 따른 존재 패턴 추적
무작위화된 MAC 주소(프라이버시 로테이션 기기)로 인한 노이즈 필터링
함께 나타나는 기기를 찾기 위한 기기 상관관계 분석
감시 중인 기기가 도착하거나 떠날 때 푸시 알림 전송
모니터링 및 분석을 위한 웹 대시보드 제공

기능

스캔

이중 모드 스캔: Bluetooth Low Energy (BLE) 및 Classic Bluetooth
MAC 주소 벤더 조회 (로컬 데이터베이스 + 온라인 API 폴백)
정확한 기기 분류를 위한 BLE 서비스 UUID 핑거프린팅
Classic Bluetooth 기기 클래스 파싱
무작위화된 MAC 필터링 (메인 뷰에서 숨김)

기기 관리

개인 기기 추적을 위해 기기를 "Watched"로 표시
기기를 사용자 정의 그룹으로 정리
기기에 사용자 정의 이름 지정 (광고되는 이름은 그 옆에 계속 표시됨)
모든 기기의 감지된 분류 재정의
모든 기기에 사용자 정의 노트/태그 추가
기기 유형 감지 (휴대폰, 오디오, 웨어러블, IoT, 차량 등)

분석

30일 존재 타임라인 시각화
7일 데이터가 포함된 신호 강도(RSSI) 기록 차트
기기가 언제 활성화되는지 보여주는 시간별 및 일별 활동 히트맵
패턴 분석 ("평일, 저녁 5PM-9PM")
기기가 범위 내에 머무는 총 시간을 보여주는 체류 시간 분석
함께 나타나는 기기를 찾기 위한 기기 상관관계 감지 (동시 존재 및 동기화된 도착/출발)
MAC 로테이션 연결 ("Likely same device") — 시간적으로 교대하고, 유사한 신호 강도를 공유하며, 유사한 주기로 핑을 보내는 무작위화된 식별자를 휴리스틱하게 연결
신호 강도에 기반한 근접 구역 (immediate, near, far, remote)
MAC, 벤더 또는 이름으로 검색
과거 조회를 위한 날짜 범위 검색

알림 (ntfy를 통해)

ntfy.sh 또는 자체 호스팅 ntfy 서버를 통해 휴대폰/데스크톱으로 푸시 알림 전송
새 기기가 감지될 때 알림
감시 중인 기기가 돌아올 때 알림
감시 중인 기기가 떠날 때 알림
도착/출발에 대한 구성 가능한 임계값

운영

하트비트 체크인 — 주기적으로 가동 시간 모니터링 서비스(예: Uptime Kuma, Healthchecks.io)에 상태를 POST
저장소 로테이션 — 구성 가능한 일수보다 오래된 목격 기록을 자동으로 정리; 선택적으로 최소 횟수 미만으로 관찰된 오래된 기기 전체를 정리하도록 제한 가능 (감시 중인 기기는 절대 정리되지 않음)
웹 UI 또는 환경 변수를 통해 모두 구성 가능

웹 인터페이스

다양한 표시 선호도를 위한 컴팩트/상세 보기 전환
안전한 공유를 위해 MAC과 이름을 난독화하는 스크린샷 모드
고급 사용자를 위한 키보드 단축키 (?를 눌러 확인)
상세 기기 데이터의 CSV 내보내기 (MAC, 벤더, 식별자, 유형, BT 유형, 기기 클래스, 감시/무시 플래그, 최초/최근 목격, 목격 횟수, 그룹, 서비스 UUID, 노트) — 현재 페이지만이 아닌 필터링된 전체 집합을 내보냄
관련 기기를 정리하기 위한 기기 그룹
접근 보안을 위한 선택적 인증

어떻게?

Docker로 빠른 시작 (권장)

사전 요구 사항 — Linux 호스트 전용

Bluehood는 Linux Bluetooth 스택인 BlueZ를 통해 Bluetooth 어댑터와 통신합니다. 컨테이너를 시작하기 전에 호스트에 BlueZ가 설치되어 실행 중이어야 합니다 — Docker 이미지 자체에는 포함되어 있지 않습니다.
# Debian / Ubuntu (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

# docker-compose.yml을 생성하거나 이 저장소에서 다운로드
# 그런 다음 Docker Compose로 시작
docker compose up -d

# 로그 보기
docker compose logs -f

Docker 이미지는 GitHub Container Registry에서 사용할 수 있습니다:

ghcr.io/dannymcc/bluehood:latest

웹 대시보드는 http://localhost:8080 에서 사용할 수 있습니다

Docker 요구 사항

Docker 및 Docker Compose
Central 역할을 지원하는 BLE 지원 Bluetooth 어댑터(Bluetooth 4.0+)가 있는 Linux 호스트
호스트에 BlueZ 설치 및 실행 중 (sudo apt install bluez && sudo systemctl enable --now bluetooth)

참고: 구형 어댑터(Bluetooth 2.x/3.x)는 BLE 스캔을 지원하지 않습니다. 어댑터가 BLE Central 역할 지원을 갖추지 못한 경우 다음과 같이 표시됩니다: No Bluetooth adapters with BLE 'central' role found.

참고: Docker는 Bluetooth 접근을 위해 호스트 네트워킹과 함께 권한 모드로 실행됩니다. 이는 BLE 스캔에 필요합니다.

Docker 환경 변수

Bluetooth 어댑터 요구 사항

Bluehood는 Central 역할 지원을 갖춘 BLE 지원 Bluetooth 어댑터(Bluetooth 4.0 이상)가 필요합니다. 구형 Bluetooth 2.x/3.x 어댑터는 BLE 스캔을 지원하지 않으며 작동하지 않습니다.

어댑터가 BLE Central 역할을 지원하지 않으면 Bluehood는 다음과 같이 종료됩니다:

No Bluetooth adapters with BLE 'central' role found

bluetoothctl show로 어댑터의 기능을 확인하고 지원되는 역할에서 central을 찾을 수 있습니다.

수동 설치 (Linux)

# 시스템 종속성 설치 (Arch Linux)
sudo pacman -S bluez bluez-utils python-pip

# 시스템 종속성 설치 (Debian/Ubuntu)
sudo apt install bluez python3-pip

# 복제 및 설치
git clone https://github.com/dannymcc/bluehood.git
cd bluehood
pip install -e .

Bluetooth 권한

Bluetooth 스캔에는 상승된 권한이 필요합니다. 다음 중 하나를 선택하세요:

root로 실행 (가장 간단):
```
sudo bluehood
```

Python에 capability 부여:

sudo setcap 'cap_net_admin,cap_net_raw+eip' $(readlink -f $(which python))
bluehood

systemd 서비스 사용 (상시 가동에 권장):

sudo cp bluehood.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bluehood

macOS

Bluehood는 Docker 없이 macOS에서 네이티브로 작동합니다. macOS는 BlueZ 대신 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가 Bluetooth 접근을 허용하라는 메시지를 표시합니다. 스캔이 작동하려면 이 권한을 부여해야 합니다.

사용법

# 웹 대시보드와 함께 시작 (기본 포트 8080)
bluehood

# 다른 포트 지정 (또는 BLUEHOOD_PORT 설정)
bluehood --port 9000

# 특정 Bluetooth 어댑터 사용
bluehood --adapter hci1

# BLE 및 Classic 스캔에 별도 어댑터 사용 (동시)
bluehood --adapter hci0 --classic-adapter hci1

# 사용 가능한 어댑터 나열
bluehood --list-adapters

# 웹 대시보드 비활성화 (스캔만)
bluehood --no-web

# 포트 9199에서 Prometheus 메트릭 익스포터 활성화
bluehood --metrics-port 9199

웹 대시보드

대시보드는 다음을 제공합니다:

유형 아이콘, 벤더, MAC, 이름, 목격 횟수, 최근 목격이 포함된 기기 목록
유형(휴대폰, 오디오, IoT 등) 및 감시 상태별 기기 필터
MAC, 벤더 또는 이름으로 검색
특정 시간 범위에서 목격된 기기를 찾는 날짜 범위 검색
탭으로 구성된 설정 페이지 — Alerts, Operations, Groups, Security (해시를 통한 직접 링크, 예: /settings#operations)
다음을 포함하는 기기 세부 정보 모달:
- BLE 서비스 핑거프린트
- 시간별/일별 활동 히트맵
- 30일 존재 타임라인
- 신호 강도(RSSI) 기록 차트
- 패턴 분석
- 체류 시간 통계
- 상관관계가 있는 기기 목록
- Likely same device (MAC 로테이션) 목록
- 근접 구역 표시기
- 운영자 노트 필드
- 그룹 할당

키보드 단축키

스크린샷 모드

스크린샷을 공유하기 전에 민감한 데이터를 난독화하려면 사이드바에서 스크린샷 모드를 활성화하세요:

MAC 주소는 처음 2개 옥텟만 표시 (예: AA:BB:XX:XX:XX:XX)
친숙한 이름은 처음 2자만 표시 (예: Da********)
CSV 내보내기도 스크린샷 모드를 따릅니다

푸시 알림

Bluehood는 무료 오픈 소스 알림 서비스인 ntfy를 통해 푸시 알림을 보낼 수 있습니다. 공용 ntfy.sh 서버 또는 자체 호스팅 인스턴스를 사용할 수 있습니다.

ntfy.sh(예: bluehood-myname-alerts) 또는 자체 ntfy 서버에서 토픽 생성
ntfy 앱을 사용하여 휴대폰에서 토픽 구독
Bluehood 설정에서 서버 URL(기본값 https://ntfy.sh), 토픽 이름, 서버에서 요구하는 경우 액세스 토큰을 입력한 후 알림 활성화
알림을 트리거할 이벤트 구성:
- 새 기기 감지
- 감시 중인 기기 복귀 (부재 후)
- 감시 중인 기기 떠남 (X분 동안 목격되지 않음)

데이터 저장

데이터는 ~/.local/share/bluehood/bluehood.db (SQLite)에 저장됩니다.

환경 변수로 위치 재정의:

BLUEHOOD_DATA_DIR - 데이터 파일용 디렉터리
BLUEHOOD_DB_PATH - 데이터베이스 파일의 직접 경로

참고: 하트비트 및 정리 설정은 웹 UI(Settings > Operations) 또는 환경 변수를 통해 구성할 수 있습니다. GUI 값이 환경 변수보다 우선합니다.

작동 방식

기기 분류

Bluehood는 여러 신호를 사용하여 기기를 분류합니다 (우선순위 순):

BLE 서비스 UUID - 가장 정확함 (Heart Rate = 웨어러블, A2DP = 오디오 등)
기기 이름 패턴 - "iPhone", "Galaxy", "AirPods" 등
벤더 OUI 조회 - Apple, Samsung, Bose 등

무작위화된 MAC

최신 기기는 프라이버시를 위해 MAC 주소를 무작위화합니다. Bluehood는:

무작위화된 MAC 감지 (locally administered 비트)
메인 기기 목록에서 숨김 (추적에 유용하지 않음)
숨겨진 무작위화 기기 수 표시

패턴 분석

Bluehood는 목격 타임스탬프를 분석하여 패턴을 감지합니다:

시간대: 아침, 오후, 저녁, 밤
요일: 평일, 주말
빈도: 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): 멀리, 감지 범위 가장자리

체류 시간 분석

목격 사이의 간격을 분석하여 기기가 범위 내에 머무는 시간을 추적합니다. 구성 가능한 간격 임계값(기본 15분)이 새로운 "세션"이 시작되는 시점을 결정합니다.

Prometheus 메트릭

Bluehood는 Prometheus 스크래핑을 위한 메트릭을 노출할 수 있습니다. BLUEHOOD_METRICS_PORT 환경 변수 또는 --metrics-port CLI 플래그를 설정하여 활성화하세요.

# 환경 변수를 통해
export BLUEHOOD_METRICS_PORT=9199

# CLI를 통해
bluehood --metrics-port 9199

메트릭은 http://host:9199/metrics에서 제공됩니다.

사용 가능한 메트릭

Grafana 대시보드

바로 가져올 수 있는 Grafana 대시보드가 grafana/bluehood-dashboard.json에 포함되어 있습니다. Grafana UI(Dashboards > Import) 또는 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}"

문제 해결

기기를 찾을 수 없음

어댑터가 Central 역할을 갖춘 BLE(Bluetooth 4.0+)를 지원하는지 확인 — 구형 어댑터는 작동하지 않음
Bluetooth 어댑터가 활성화되어 있는지 확인: bluetoothctl power on
어댑터가 감지되는지 확인: 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
어댑터가 표시되는지 확인: 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) - Firefox 더블클릭 수정 (#29)
@GeiserX (Sergio Fernández) - Prometheus 메트릭 익스포터 (#35), 비차단 벤더 DB 수정 (#37), 이중 어댑터 스캔 (#33), rfkill을 사용한 강력한 스캔 복구 (#40)

라이선스

MIT License - 자세한 내용은 LICENSE를 참조하세요.

면책 조항

이 도구는 교육 목적으로만 사용됩니다. Bluetooth 기기를 모니터링할 때 해당 관할 지역의 프라이버시 법률에 유의하세요. 작성자는 이 소프트웨어의 오용에 대해 책임지지 않습니다.

Danny McClelland 제작

`PUID`	`1000`	컨테이너 사용자의 UID — 바인드 마운트 사용 시 호스트 사용자(`id -u`)와 일치하도록 설정
`PGID`	`1000`	컨테이너 사용자의 GID — 바인드 마운트 사용 시 호스트 그룹(`id -g`)과 일치하도록 설정
`TZ`	UTC	컨테이너 시간대 (예: `Europe/London`)
`BLUEHOOD_ADAPTER`	auto	BLE 스캔용 Bluetooth 어댑터 (예: `hci0`)
`BLUEHOOD_CLASSIC_ADAPTER`	`BLUEHOOD_ADAPTER`와 동일	Classic Bluetooth 스캔용 별도 어댑터 (예: `hci1`). 다른 어댑터로 설정하면 BLE와 Classic 스캔이 동시에 실행됩니다.
`BLUEHOOD_DATA_DIR`	`/data`	데이터베이스 저장 디렉터리
`BLUEHOOD_PORT`	`8080`	웹 대시보드 포트. 컨테이너는 호스트 네트워킹을 사용하므로 8080이 사용 중이면 포트 매핑 대신 이 값을 변경하세요
`BLUEHOOD_NTFY_SERVER`	`https://ntfy.sh`	푸시 알림용 ntfy 서버의 기본 URL; 자체 호스팅 인스턴스를 가리키도록 설정. Settings 페이지에 저장된 값이 우선합니다
`BLUEHOOD_METRICS_PORT`	disabled	Prometheus 메트릭 포트 (예: `9199`)
`BLUEHOOD_HEARTBEAT_URL`	disabled	하트비트 체크인을 POST할 URL (예: healthchecks.io 또는 uptime-kuma 푸시 URL)
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	하트비트 체크인 간격(초)
`BLUEHOOD_PRUNE_DAYS`	`0` (disabled)	저장 공간 확보를 위해 N일보다 오래된 목격 기록 자동 삭제
`BLUEHOOD_PRUNE_MIN_SIGHTINGS`	`0` (disabled)	0보다 클 때, 오래된 목격 행만 정리하는 대신 오래된 기기 전체(`BLUEHOOD_PRUNE_DAYS`보다 오래되고 총 목격 횟수가 N 미만)를 정리; 감시 중인 기기는 절대 정리되지 않음

`/`	검색 바에 포커스
`r`	기기 목록 새로 고침
`c`	컴팩트 보기 전환
`w`	선택한 기기의 감시 전환
`Esc`	모달 닫기
`?`	키보드 단축키 표시

`bluehood_scans_total`	Counter	완료된 총 스캔 주기
`bluehood_scan_errors_total`	Counter	스캔 오류 (레이블: `scan_type`)
`bluehood_sightings_total`	Counter	기록된 총 기기 목격 횟수
`bluehood_new_devices_total`	Counter	발견된 새로운 고유 기기
`bluehood_last_scan_devices`	Gauge	마지막 스캔의 기기 (레이블: `scan_type`)
`bluehood_devices_total`	Gauge	DB의 고유 기기 (레이블: `bt_type`)
`bluehood_devices_active`	Gauge	지난 5분 동안 목격된 기기
`bluehood_devices_watched`	Gauge	감시 중인 기기 수
`bluehood_devices_ignored`	Gauge	무시된 기기 수
`bluehood_scan_duration_seconds`	Histogram	스캔 주기 지속 시간
`bluehood_device_rssi_dbm`	Histogram	BLE 기기의 RSSI 분포
`bluehood_build_info`	Info	버전 정보

인기

bluehood