지역 이웃의 블루투스 활동을 모니터링하세요
# Bluehood
**Bluetooth Neighborhood** - 주변의 BLE 기기를 추적하고 트래픽 패턴을 분석합니다.
[](https://buymeacoffee.com/d3hkz6gwle)
---
> **경고: 알파 소프트웨어**
>
> 이 프로젝트는 초기 개발 단계에 있으며 **프로덕션 사용에 적합하지 않습니다**. 기능은 예고 없이 변경되거나, 작동이 중단되거나, 제거될 수 있습니다. 사용에 따른 책임은 사용자에게 있습니다. 수집된 데이터는 실험적인 것으로 취급해야 합니다.
---
## 스크린샷

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

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

*프로젝트 정보와 기능 개요가 담긴 Intel 페이지*
## 왜?
이 프로젝트는 Bluetooth 기기의 프라이버시 위험을 부각시킨 [WhisperPair 취약점](https://whisperpair.eu/) ([CVE-2025-36911](https://nvd.nist.gov/vuln/detail/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 이미지 자체에는 포함되어 있지 않습니다.
>
> ```bash
> # 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`
```bash
# 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)
```bash
# 시스템 종속성 설치 (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 스캔에는 상승된 권한이 필요합니다. 다음 중 하나를 선택하세요:
1. **root로 실행** (가장 간단):
```bash
sudo bluehood
```
2. **Python에 capability 부여**:
```bash
sudo setcap 'cap_net_admin,cap_net_raw+eip' $(readlink -f $(which python))
bluehood
```
3. **systemd 서비스 사용** (상시 가동에 권장):
```bash
sudo cp bluehood.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bluehood
```
### macOS
Bluehood는 Docker 없이 macOS에서 네이티브로 작동합니다. macOS는 BlueZ 대신 CoreBluetooth를 사용하며, 이는 `bleak` 라이브러리가 자동으로 처리합니다.
```bash
# 저장소 복제
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 접근을 허용하라는 메시지를 표시합니다. 스캔이 작동하려면 이 권한을 부여해야 합니다.
## 사용법
```bash
# 웹 대시보드와 함께 시작 (기본 포트 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 로테이션) 목록
- 근접 구역 표시기
- 운영자 노트 필드
- 그룹 할당
### 키보드 단축키
| Key | Action |
|-----|--------|
| `/` | 검색 바에 포커스 |
| `r` | 기기 목록 새로 고침 |
| `c` | 컴팩트 보기 전환 |
| `w` | 선택한 기기의 감시 전환 |
| `Esc` | 모달 닫기 |
| `?` | 키보드 단축키 표시 |
### 스크린샷 모드
스크린샷을 공유하기 전에 민감한 데이터를 난독화하려면 사이드바에서 스크린샷 모드를 활성화하세요:
- MAC 주소는 처음 2개 옥텟만 표시 (예: `AA:BB:XX:XX:XX:XX`)
- 친숙한 이름은 처음 2자만 표시 (예: `Da********`)
- CSV 내보내기도 스크린샷 모드를 따릅니다
## 푸시 알림
Bluehood는 무료 오픈 소스 알림 서비스인 [ntfy](https://ntfy.sh)를 통해 푸시 알림을 보낼 수 있습니다. 공용 ntfy.sh 서버 또는 자체 호스팅 인스턴스를 사용할 수 있습니다.
1. ntfy.sh(예: `bluehood-myname-alerts`) 또는 자체 ntfy 서버에서 토픽 생성
2. ntfy 앱을 사용하여 휴대폰에서 토픽 구독
3. Bluehood 설정에서 서버 URL(기본값 `https://ntfy.sh`), 토픽 이름, 서버에서 요구하는 경우 액세스 토큰을 입력한 후 알림 활성화
4. 알림을 트리거할 이벤트 구성:
- 새 기기 감지
- 감시 중인 기기 복귀 (부재 후)
- 감시 중인 기기 떠남 (X분 동안 목격되지 않음)
## 데이터 저장
데이터는 `~/.local/share/bluehood/bluehood.db` (SQLite)에 저장됩니다.
환경 변수로 위치 재정의:
- `BLUEHOOD_DATA_DIR` - 데이터 파일용 디렉터리
- `BLUEHOOD_DB_PATH` - 데이터베이스 파일의 직접 경로
> **참고**: 하트비트 및 정리 설정은 웹 UI(Settings > Operations) 또는 환경 변수를 통해 구성할 수 있습니다. GUI 값이 환경 변수보다 우선합니다.
## 작동 방식
### 기기 분류
Bluehood는 여러 신호를 사용하여 기기를 분류합니다 (우선순위 순):
1. **BLE 서비스 UUID** - 가장 정확함 (Heart Rate = 웨어러블, A2DP = 오디오 등)
2. **기기 이름 패턴** - "iPhone", "Galaxy", "AirPods" 등
3. **벤더 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 플래그를 설정하여 활성화하세요.
```bash
# 환경 변수를 통해
export BLUEHOOD_METRICS_PORT=9199
# CLI를 통해
bluehood --metrics-port 9199
```
메트릭은 `http://host:9199/metrics`에서 제공됩니다.
### 사용 가능한 메트릭
| Metric | Type | Description |
|--------|------|-------------|
| `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 | 버전 정보 |
### Grafana 대시보드
바로 가져올 수 있는 Grafana 대시보드가 [`grafana/bluehood-dashboard.json`](https://github.com/dannymcc/bluehood/blob/master/grafana/bluehood-dashboard.json)에 포함되어 있습니다. Grafana UI(Dashboards > Import) 또는 API를 통해 가져오세요:
```bash
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가 설치되어 있지 않거나 실행 중이 아닙니다. 해결:
```bash
sudo apt install bluez # Debian/Ubuntu
sudo systemctl enable --now bluetooth
docker compose restart
```
**일반 체크리스트:**
- **호스트**에 BlueZ가 설치되어 있는지 확인 (컨테이너 내부만이 아님)
- Bluetooth 서비스가 실행 중인지 확인: `systemctl status bluetooth`
- 어댑터가 표시되는지 확인: `bluetoothctl list`
## 기여
기여를 환영합니다! GitHub에서 이슈 또는 PR을 열어주세요.
### 기여자
- [@martinh2011](https://github.com/martinh2011) (Martin Hüser) - MAC 벤더 캐시 개선
- [@hatedabamboo](https://github.com/hatedabamboo) (Kirill Solovei) - 라이트 테마 지원
- [@krnltrp](https://github.com/krnltrp) - 웹 UI 개선
- [@jacobpretorius](https://github.com/jacobpretorius) (Jacob Pretorius) - CSV 내보내기 JS 수정 (#14), 클릭하여 설정 열기 (#16)
- [@unqualifiedkoala](https://github.com/unqualifiedkoala) - BLE 어댑터 요구 사항 문서화
- [@dazzag24](https://github.com/dazzag24) - macOS 주소 형식 문제 보고
- [@floese](https://github.com/floese) (W.A.Flozart) - Firefox 더블클릭 수정 (#29)
- [@GeiserX](https://github.com/GeiserX) (Sergio Fernández) - Prometheus 메트릭 익스포터 (#35), 비차단 벤더 DB 수정 (#37), 이중 어댑터 스캔 (#33), rfkill을 사용한 강력한 스캔 복구 (#40)
## 라이선스
MIT License - 자세한 내용은 [LICENSE](https://github.com/dannymcc/bluehood/blob/master/LICENSE)를 참조하세요.
## 면책 조항
이 도구는 교육 목적으로만 사용됩니다. Bluetooth 기기를 모니터링할 때 해당 관할 지역의 프라이버시 법률에 유의하세요. 작성자는 이 소프트웨어의 오용에 대해 책임지지 않습니다.
---
[Danny McClelland](https://github.com/dannymcc) 제작