Bluehood

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

경고: 알파 소프트웨어

이 프로젝트는 초기 개발 단계에 있으며 프로덕션 사용 준비가 되지 않았습니다. 기능은 예고 없이 변경, 중단 또는 제거될 수 있습니다. 사용에 따른 책임은 본인에게 있습니다. 수집된 데이터는 실험적인 것으로 간주되어야 합니다.

스크린샷

Dashboard 필터링, 검색 및 실시간 통계를 보여주는 메인 대시보드

Settings 탭으로 구성된 설정 페이지 — 알림, 운영, 그룹 및 보안

About 프로젝트 정보와 기능 개요를 제공하는 인텔 페이지

이유?

이 프로젝트는 블루투스 기기의 개인정보 보호 위험을 강조한 WhisperPair 취약점 (CVE-2025-36911)에서 영감을 받았습니다.

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

충분한 데이터가 있으면 잠재적으로 다음을 할 수 있습니다:

특정인이 언제 개를 산책시키는지 이해
방문자가 집에 도착하는 시점 감지
기기 존재에 기반한 일상 패턴 식별

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

Bluehood는 블루투스 개인정보 보호에 대한 인식을 높이기 위한 교육 도구입니다. 주말 프로젝트이지만, 그 의미는 생각해 볼 가치가 있습니다.

무엇?

Bluehood는 블루투스 스캐너로서 다음을 수행합니다:

지속적으로 스캔하여 주변 블루투스 기기 (BLE 및 클래식 모두) 탐지
벤더 식별 (MAC 주소 조회) 및 BLE 서비스 UUID를 통해 기기 식별
기기 분류 (전화, 오디오, 웨어러블, IoT, 차량 등)
시간 경과에 따른 존재 패턴 추적 (시간별/일별 히트맵)
무작위 MAC 주소 (개인정보 보호 회전 기기) 노이즈 필터링
기기 상관관계 분석하여 함께 나타나는 기기 찾기
푸시 알림 전송 (감시 중인 기기의 도착/이탈 시)
웹 대시보드 제공 (모니터링 및 분석용)

기능

스캔

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

기기 관리

기기를 "감시"로 표시하여 개인 기기 추적
기기를 맞춤 그룹으로 구성
알려진 기기에 친근한 이름 설정
모든 기기에 메모/태그 추가
기기 유형 감지 (전화, 오디오, 웨어러블, IoT, 차량 등)

분석

30일 존재 타임라인 시각화
신호 강도 (RSSI) 히스토리 차트 (7일 데이터)
시간별 및 일별 활동 히트맵 (기기가 활동하는 시간 표시)
패턴 분석 ("주중, 저녁 5PM-9PM")
체류 시간 분석 (기기가 범위 내에 머무는 총 시간)
기기 상관관계 감지 (함께 나타나는 기기 찾기)
근접 영역 (즉시, 가까움, 멀음, 원격) 신호 강도 기반
MAC, 벤더 또는 이름으로 검색
날짜 범위 검색으로 과거 조회

알림 (ntfy.sh 사용)

휴대폰/데스크탑으로 푸시 알림 전송
새 기기 감지 시 알림
감시 중인 기기 복귀 시 알림
감시 중인 기기 이탈 시 알림
도착/이탈 임계값 설정 가능

운영

하트비트 체크인 — 주기적으로 상태를 업타임 모니터링 서비스 (예: Uptime Kuma, Healthchecks.io)에 POST
저장소 로테이션 — 설정 가능한 일수보다 오래된 감지 기록 자동 삭제
둘 다 웹 UI 또는 환경 변수로 설정 가능

웹 인터페이스

간결/상세 보기 전환 (다양한 표시 선호도)
스크린샷 모드 (MAC 및 이름 난독화로 안전한 공유)
키보드 단축키 (파워 유저용, ? 눌러 확인)
CSV 내보내기 (기기 데이터)
기기 그룹 (관련 기기 구성)
선택적 인증 (보안 접근)

어떻게?

Docker로 빠른 시작 (권장)

전제 조건 — Linux 호스트 전용

Bluehood는 블루투스 어댑터와 통신하기 위해 Linux 블루투스 스택인 BlueZ를 사용합니다. 컨테이너를 시작하기 전에 호스트에 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
BLE 지원 블루투스 어댑터 (블루투스 4.0+)가 있는 Linux 호스트 (Central 역할 지원)
호스트에 BlueZ 설치 및 실행 (sudo apt install bluez && sudo systemctl enable --now bluetooth)

참고: 구형 어댑터 (블루투스 2.x/3.x)는 BLE 스캔을 지원하지 않습니다. 어댑터에 BLE Central 역할이 없으면 다음과 같은 오류가 표시됩니다: No Bluetooth adapters with BLE 'central' role found.

참고: Docker는 블루투스 액세스를 위해 호스트 네트워킹과 함께 특권 모드로 실행됩니다. 이는 BLE 스캔에 필요합니다.

Docker 환경 변수

블루투스 어댑터 요구 사항

Bluehood에는 BLE 지원 블루투스 어댑터 (블루투스 4.0 이상)와 Central 역할 지원이 필요합니다. 구형 블루투스 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 .

블루투스 권한

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

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

Python에 역량 부여:

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에서 블루투스 액세스를 허용하라는 메시지가 표시됩니다. 스캔이 작동하려면 이 권한을 부여해야 합니다.

사용법

# 웹 대시보드로 시작 (기본 포트 8080)
bluehood

# 다른 포트 지정
bluehood --port 9000

# 특정 블루투스 어댑터 사용
bluehood --adapter hci1

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

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

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

# 포트 9199에서 Prometheus 메트릭 내보내기 활성화
bluehood --metrics-port 9199

웹 대시보드

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

기기 목록 (유형 아이콘, 벤더, MAC, 이름, 감지 횟수, 마지막 감지 시간)
기기 필터 (유형: 전화, 오디오, IoT 등 및 감시 상태)
검색 (MAC, 벤더 또는 이름으로)
날짜 범위 검색 (특정 시간 창에 감지된 기기 찾기)
탭 설정 페이지 (알림, 운영, 그룹 및 보안 — 해시로 직접 링크, 예: /settings#operations)
기기 세부 정보 모달:
- BLE 서비스 핑거프린트
- 시간별/일별 활동 히트맵
- 30일 존재 타임라인
- 신호 강도 (RSSI) 히스토리 차트
- 패턴 분석
- 체류 시간 통계
- 상관 기기 목록
- 근접 영역 표시기
- 운영자 메모 필드
- 그룹 할당

키보드 단축키

스크린샷 모드

사이드바에서 스크린샷 모드를 활성화하여 스크린샷을 공유하기 전에 민감한 데이터를 난독화합니다:

MAC 주소는 처음 2옥텟만 표시 (예: AA:BB:XX:XX:XX:XX)
친근한 이름은 처음 2문자만 표시 (예: Da********)
CSV 내보내기도 스크린샷 모드 존중

푸시 알림

Bluehood는 무료 오픈소스 알림 서비스인 ntfy.sh를 통해 푸시 알림을 보낼 수 있습니다.

ntfy.sh에서 주제 생성 (예: bluehood-myname-alerts)
ntfy 앱을 사용하여 휴대폰에서 주제 구독
Bluehood 설정에서 주제 이름을 입력하고 알림 활성화
알림을 트리거할 이벤트 구성:
- 새 기기 감지
- 감시 중인 기기 복귀 (부재 후)
- 감시 중인 기기 이탈 (X분 동안 보이지 않음)

데이터 저장

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

환경 변수로 위치 재정의:

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

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

작동 방식

기기 분류

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

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

무작위 MAC

최신 기기는 개인정보 보호를 위해 MAC 주소를 무작위화합니다. Bluehood:

무작위 MAC 감지 (로컬 관리 비트)
메인 기기 목록에서 숨김 (추적에 유용하지 않음)
숨겨진 무작위 기기 수 표시

패턴 분석

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

시간대: 아침, 오후, 저녁, 밤
요일: 주중, 주말
빈도: 항상, 매일, 정기적, 가끔, 드물게

예시 패턴: "매일, 저녁 (5PM-9PM)", "주중, 아침 (8AM-12PM)"

기기 상관관계

Bluehood는 설정 가능한 시간 창 내에서 자주 함께 나타나는 기기를 감지합니다. 이는 다음을 드러낼 수 있습니다:

같은 사람이 소유한 기기 (전화 + 스마트워치)
함께 이동하는 사람들
일정을 공유하는 기기

근접 영역

RSSI 신호 강도에 따라 기기는 근접 영역으로 분류됩니다:

즉시 (> -50 dBm): 매우 가까움, 수 미터 이내
가까움 (-50 ~ -60 dBm): 근처, 같은 방
멀음 (-60 ~ -70 dBm): 더 멀리, 인접 방
원격 (< -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 (대시보드 > 가져오기) 또는 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 (블루투스 4.0+)를 지원하는지 확인하세요 — 구형 어댑터는 작동하지 않습니다
블루투스 어댑터가 활성화되어 있는지 확인: 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가 호스트에 설치되어 있는지 확인 (컨테이너 내부가 아님)
블루투스 서비스가 실행 중인지 확인: 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를 참조하세요.

면책 조항

이 도구는 교육 목적으로만 제공됩니다. 블루투스 기기를 모니터링할 때 해당 관할권의 개인정보 보호법을 준수하세요. 저자는 이 소프트웨어의 오용에 대해 책임을 지지 않습니다.

Danny McClelland 제작

`PUID`	`1000`	컨테이너 사용자의 UID — 바인드 마운트를 사용할 때 호스트 사용자와 일치하도록 설정 (`id -u`)
`PGID`	`1000`	컨테이너 사용자의 GID — 바인드 마운트를 사용할 때 호스트 그룹과 일치하도록 설정 (`id -g`)
`TZ`	UTC	컨테이너 시간대 (예: `Europe/London`)
`BLUEHOOD_ADAPTER`	auto	BLE 스캔용 블루투스 어댑터 (예: `hci0`)
`BLUEHOOD_CLASSIC_ADAPTER`	`BLUEHOOD_ADAPTER`와 동일	클래식 블루투스 스캔용 별도 어댑터 (예: `hci1`). 다른 어댑터로 설정하면 BLE와 클래식 스캔이 동시에 실행됩니다.
`BLUEHOOD_DATA_DIR`	`/data`	데이터베이스 저장 디렉터리
`BLUEHOOD_METRICS_PORT`	비활성화	Prometheus 메트릭 포트 (예: `9199`)
`BLUEHOOD_HEARTBEAT_URL`	비활성화	하트비트 체크인을 POST할 URL (예: healthchecks.io 또는 uptime-kuma 푸시 URL)
`BLUEHOOD_HEARTBEAT_INTERVAL`	`300`	하트비트 체크인 간격 (초)
`BLUEHOOD_PRUNE_DAYS`	`0` (비활성화)	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