BT-gotchi

Behavioral Bluetooth Analytics Engine for Device Tracking, Pattern Recognition, and Surveillance Detection

Documentation Contents
What is BT-gotchi?

BT-gotchi is an AI-powered Bluetooth behavioral analytics system designed to study, learn, and evaluate every Bluetooth device in your environment. Inspired by Pwnagotchi, it goes beyond simple device listing to provide deep analysis of device behavior patterns, manufacturer identification via an 85,000-entry OUI database, and most critically - detection of devices that may be following or tracking you.

The system maintains a persistent memory of every device ever seen, tracks their appearances over time and location, and uses neural network classification to identify device types and detect anomalies that may indicate surveillance.

System Overview

85,905
OUI Entries
401+
Devices Learned
71K+
Total Sightings
24/7
Continuous Monitoring

Core Capabilities

  • Device Discovery: Continuously scans for Bluetooth Classic and BLE devices via Kismet integration
  • Manufacturer Identification: Cross-references every MAC address against 85,905 OUI entries to identify device manufacturers
  • Behavioral Tracking: Records when, where, and how often each device appears to build behavioral profiles
  • Anomaly Detection: Identifies unusual patterns that deviate from normal Bluetooth behavior
  • Tracker Detection: Specifically identifies Apple AirTags, Tile, Samsung SmartTags, and other tracking devices
  • Following Detection: Detects if the same device appears repeatedly across different locations/times (potential stalking)
  • Neural Network Classification: AI-powered device type classification based on characteristics and behavior
  • Persistent Memory: Never forgets a device - builds comprehensive historical database for analysis

Architecture & Data Flow

Bluetooth Adapter
hci0 / BLE Scanner
→
Kismet
Packet Capture
→
BT-gotchi API
Data Processing
↓
OUI Lookup
85K MAC Database
→
Neural Network
Classification
→
Anomaly Engine
Threat Detection
↓
SQLite Database
ble_memory.db
→
Web Dashboard
:5002

Data Flow Process

1️⃣ Capture
The Bluetooth adapter (hci0) in scanning mode captures BLE advertisements and Bluetooth Classic inquiry responses. Kismet handles the low-level capture and exposes devices via its REST API.
2️⃣ Enrichment
Each device MAC is cross-referenced against the 85,905-entry OUI database to identify the manufacturer. This immediately tells us if a device is from Apple, Samsung, Tile, or an unknown/spoofed manufacturer.
3️⃣ Classification
The neural network analyzes device characteristics (name patterns, manufacturer, signal behavior, service UUIDs) to classify devices into categories: Phone, Laptop, Headphones, Speaker, Tracker, Fitness Band, etc.
4️⃣ Analysis
The anomaly engine checks for following patterns (same device seen repeatedly), tracker signatures, unusual behavior, and devices that don't match their claimed identity.
5️⃣ Storage
Every sighting is logged to SQLite with timestamp, signal strength, GPS coordinates (if available), and classification. Historical data enables pattern analysis across days, weeks, or months.

OUI Database - 85,905 Manufacturer Entries

The Organizationally Unique Identifier (OUI) database is fundamental to device identification. Every Bluetooth MAC address contains a 3-byte prefix assigned to the manufacturer by IEEE. BT-gotchi maintains a comprehensive database of 85,905 OUI entries for instant manufacturer lookup.

Why OUI Matters for Security

🏭
Manufacturer ID
Instantly know if a device is from Apple, Google, Samsung, or a suspicious unknown manufacturer.
🎭
Spoofing Detection
Devices claiming to be iPhones but with non-Apple OUIs are immediately flagged as anomalies.
🏷️
Tracker Identification
Known tracker manufacturers (Tile, Chipolo, etc.) are flagged for extra scrutiny.
📊
Statistical Analysis
Understand the device ecosystem around you - what percentage Apple vs Android, etc.

OUI Lookup Process

# Example MAC: A4:C1:38:XX:XX:XX # OUI Prefix: A4:C1:38 def lookup_oui(mac_address): prefix = mac_address[:8].upper().replace(":", "") # Query 85,905 entry database result = oui_database.get(prefix) if result: return { "manufacturer": result.company_name, "country": result.country, "is_known": True } else: # Unknown OUI - potential custom/spoofed device return { "manufacturer": "UNKNOWN", "is_known": False, "anomaly": True } # Result: "Apple, Inc." - Legitimate iPhone # Result: "UNKNOWN" - Flag for investigation

Known Tracker OUI Prefixes

Manufacturer Product OUI Prefix Threat Level
Apple AirTag Multiple Apple OUIs High Scrutiny
Tile, Inc. Tile Tracker Tile-specific OUIs High Scrutiny
Samsung SmartTag Samsung OUIs High Scrutiny
Chipolo Chipolo ONE Chipolo OUIs High Scrutiny
Unknown Unregistered Not in database Critical Alert

Behavioral Analytics Engine

BT-gotchi doesn't just list devices - it studies their behavior over time. Every device builds a behavioral profile that reveals patterns invisible to simple scanners.

Behavioral Metrics Tracked

⏱️
Temporal Patterns
When does this device appear? Same time every day? Only on weekdays? Random intervals?
📍
Location Correlation
Where is this device seen? Does it follow you across multiple locations?
📶
Signal Behavior
How does signal strength vary? Is the device getting closer or maintaining distance?
🔄
Presence Duration
How long does the device stay? Quick passes or extended presence?

Behavioral Profile Example

# Device Behavioral Profile { "mac": "A4:C1:38:XX:XX:XX", "manufacturer": "Apple, Inc.", "classification": "iPhone", # Temporal Analysis "first_seen": "2024-12-01 08:32:15", "last_seen": "2024-12-13 22:15:43", "total_sightings": 847, "avg_daily_sightings": 65, # Pattern Analysis "most_active_hours": [8, 9, 17, 18, 19], # Commute times "weekend_activity": "low", "pattern_type": "REGULAR_COMMUTER", # Location Data "locations_seen": 1, # Only at home = neighbor "follows_user": False, # Threat Assessment "threat_level": "LOW", "is_tracker": False, "behavioral_anomalies": [] }

Tracker Detection System

⚠️ Critical Security Feature

BT-gotchi actively scans for known tracking devices that could be used for stalking or surveillance. This includes commercial trackers (AirTags, Tiles) and suspicious unknown devices exhibiting tracker-like behavior.

Known Tracker Signatures

🍎 Apple AirTag Detection
AirTags broadcast specific BLE advertisements with identifiable characteristics:
  • Apple manufacturer data in advertisement
  • Rotating public keys (changes every 15 minutes)
  • Specific service UUIDs
  • Characteristic signal pattern

Detection: BT-gotchi identifies AirTags even when they rotate addresses by recognizing the advertisement structure.

🔷 Tile Tracker Detection
Tile devices have distinct Bluetooth signatures:
  • Tile-specific OUI prefixes
  • Characteristic device names ("Tile" prefix)
  • Specific BLE service advertisements
🔘 Samsung SmartTag Detection
Samsung Galaxy SmartTags identified by:
  • Samsung manufacturer OUI
  • SmartThings Find network signatures
  • Specific advertisement data
❓ Unknown Tracker Detection
Devices exhibiting tracker behavior without known signatures:
  • Unknown/missing OUI (not in 85K database)
  • No device name or generic name
  • Persistent presence across locations
  • Low signal variation (hidden/stationary)
  • Minimal BLE services (tracker-like simplicity)

High Alert: Unknown devices following you are the most suspicious.

Following Detection Algorithm

🚨 Are You Being Followed?

The most critical feature of BT-gotchi is detecting if a Bluetooth device is following you across different locations and times. This is the primary indicator of stalking or surveillance.

Detection Criteria

Indicator Threshold Weight
Seen at multiple locations ≥ 2 distinct GPS locations Critical
Persistent over time Appears on ≥ 3 different days High
Matches your movement Appears within 30 min of your arrival Critical
Unknown manufacturer OUI not in 85K database High
No device name Empty or generic BLE name Medium
Tracker signature Matches known tracker pattern Critical
Consistent signal strength Maintains distance (not random passerby) Medium

Following Detection Algorithm

def detect_following(device): score = 0 alerts = [] # Check location correlation if device.unique_locations >= 2: score += 40 alerts.append("MULTI_LOCATION") # Check temporal persistence if device.days_seen >= 3: score += 25 alerts.append("PERSISTENT") # Check OUI against 85K database if not oui_database.is_known(device.mac): score += 20 alerts.append("UNKNOWN_MANUFACTURER") # Check for tracker signatures if is_tracker_signature(device): score += 30 alerts.append("TRACKER_DETECTED") # Check movement correlation if correlates_with_user_movement(device): score += 35 alerts.append("MOVEMENT_CORRELATION") # Determine threat level if score >= 70: return "CRITICAL - LIKELY FOLLOWING" elif score >= 40: return "WARNING - SUSPICIOUS" else: return "NORMAL"

Alert Levels

🚨
CRITICAL
Device exhibits multiple following indicators. Appears at different locations matching your movement. Immediate investigation recommended.
⚠️
WARNING
Device shows suspicious patterns but not definitive following. Monitor closely for additional indicators.
✓
NORMAL
Device behavior consistent with normal environment (neighbors, coworkers, regular commuters).

Neural Network Classification

BT-gotchi employs a neural network trained on device characteristics to automatically classify unknown devices into categories. This enables intelligent filtering and priority alerting.

Classification Categories

Category Indicators Priority
📱 Smartphone Apple/Samsung/Google OUI, multiple services, strong signal variation Normal
💻 Laptop Intel/Broadcom OUI, computer-class device, intermittent presence Normal
🎧 Headphones Audio device name, A2DP service, paired behavior Low
⌚ Wearable Fitness OUI, health services, consistent presence with phone Low
🔊 Speaker Audio OUI, speaker in name, stationary signal Low
🏷️ Tracker Tracker OUI, minimal services, persistent unknown presence HIGH
❓ Unknown Unrecognized OUI, no name, suspicious behavior HIGH

Neural Network Architecture

# BT-gotchi Neural Network Model # Input Features → Hidden Layers → Classification Output Input Features (12): ├── oui_category # Encoded manufacturer type ├── has_name # Boolean: device broadcasts name ├── name_length # Length of device name ├── name_pattern # Encoded name pattern match ├── signal_variance # How much RSSI varies ├── presence_duration # Average time device is visible ├── sighting_frequency # How often device appears ├── service_count # Number of BLE services ├── has_audio_service # Boolean: A2DP/audio present ├── has_hid_service # Boolean: keyboard/mouse service ├── location_variance # Seen at multiple locations? └── time_pattern # Regular vs random appearance Hidden Layers: ├── Dense(64, ReLU) ├── Dropout(0.3) ├── Dense(32, ReLU) └── Dropout(0.2) Output Layer: └── Dense(8, Softmax) # 8 device categories

Database Schema

BT-gotchi maintains a persistent SQLite database (ble_memory.db) that stores every device and sighting for historical analysis.

Devices Table

CREATE TABLE devices ( id INTEGER PRIMARY KEY, mac TEXT UNIQUE, -- Device MAC address name TEXT, -- Broadcast device name manufacturer TEXT, -- OUI lookup result oui_prefix TEXT, -- First 3 bytes of MAC classification TEXT, -- AI classification is_known INTEGER DEFAULT 0, -- User marked as known is_tracker INTEGER DEFAULT 0, -- Identified as tracker nickname TEXT, -- User-assigned name first_seen TIMESTAMP, -- First detection time last_seen TIMESTAMP, -- Most recent detection times_seen INTEGER DEFAULT 0, -- Total sighting count threat_level TEXT DEFAULT 'NORMAL', -- Threat assessment notes TEXT -- User notes );

Sightings Table

CREATE TABLE sightings ( id INTEGER PRIMARY KEY, device_id INTEGER, -- Foreign key to devices timestamp TIMESTAMP, -- When device was seen rssi INTEGER, -- Signal strength (dBm) latitude REAL, -- GPS latitude longitude REAL, -- GPS longitude location_name TEXT, -- Named location if known session_id INTEGER, -- Scanning session FOREIGN KEY (device_id) REFERENCES devices(id) );

OUI Lookup Table

CREATE TABLE oui_lookup ( id INTEGER PRIMARY KEY, prefix TEXT UNIQUE, -- 3-byte OUI prefix manufacturer TEXT, -- Company name address TEXT, -- Company address country TEXT, -- Country code is_tracker_mfg INTEGER DEFAULT 0 -- Known tracker manufacturer ); -- 85,905 entries loaded from IEEE OUI database

API Reference

Core Endpoints

Endpoint Method Description
/api/state GET Current BT-gotchi state, mood, device counts
/api/scan GET Currently visible devices with classifications
/api/memory GET All devices in memory database
/api/new GET Newly discovered devices today
/api/device/{mac} GET Detailed profile for specific device
/api/stats GET Statistics and analytics
/api/ai/threats GET Devices flagged as potential threats

Example API Response

// GET /api/device/A4:C1:38:XX:XX:XX { "mac": "A4:C1:38:XX:XX:XX", "name": "iPhone", "manufacturer": "Apple, Inc.", "classification": "smartphone", "first_seen": "2024-12-01T08:32:15Z", "last_seen": "2024-12-13T22:15:43Z", "times_seen": 847, "threat_level": "NORMAL", "is_tracker": false, "following_score": 12, "locations_seen": 1, "behavioral_profile": { "pattern": "REGULAR_PRESENCE", "active_hours": [8, 9, 17, 18, 19], "avg_signal": -65 } }