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 환경 변수

Variable	Default	Description
`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 미만)를 정리; 감시 중인 기기는 절대 정리되지 않음

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