Metadata-Version: 2.4
Name: ble-radar
Version: 0.1.0
Summary: BLE device scanner, fingerprinter, and tracker detector for security research
Author-email: ghost-ble <bill.jtrammell@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bill-jtrammell/ble-radar
Project-URL: Repository, https://github.com/bill-jtrammell/ble-radar
Keywords: bluetooth,ble,scanner,fingerprint,security,iot,tracker
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: bleak>=0.20.0

# ble-radar

BLE device scanner, fingerprinter, and tracker detector. Find nearby Bluetooth devices, identify brands/models, detect AirTags and Tile trackers, and fingerprint IoT devices.

## Install

```bash
pip install ble-radar
```

## Quick Start

```python
import asyncio
from bleradar import BLEScanner

async def main():
    scanner = BLEScanner()
    result = await scanner.scan(duration=10.0)
    
    print(f"Found {result.count} devices in {result.scan_duration:.1f}s")
    for dev in result.by_rssi(min_rssi=-70):
        print(dev)

asyncio.run(main())
```

## Filter Results

```python
result = await scanner.scan(duration=10.0)

# Strong signal only
strong = result.by_rssi(min_rssi=-60)

# By name
apple_devices = result.by_name("AirPods")

# By manufacturer
apple = result.by_manufacturer(0x004C)

# By service UUID
led_controllers = result.by_service("49535343")

# Only connectable
connectable = result.connectable()
```

## Device Fingerprinting

```python
from bleradar import BLEScanner, FingerprintDB

scanner = BLEScanner()
fingerprint_db = FingerprintDB()

result = await scanner.scan(duration=10.0)

for dev in result.devices:
    fp = fingerprint_db.identify(dev)
    print(f"{dev.name or dev.address}: {fp.brand} {fp.model} ({fp.device_type})")
    print(f"  Confidence: {fp.confidence:.0%}")
    print(f"  Clues: {', '.join(fp.clues)}")
```

## Tracker Detection

Find AirTags, Tile trackers, and other tracking devices nearby:

```python
result = await scanner.scan(duration=10.0)
trackers = fingerprint_db.find_trackers(result.devices)

if trackers:
    print(f"WARNING: {len(trackers)} tracker(s) detected!")
    for dev, fp in trackers:
        print(f"  {dev.address} ({dev.name}) - {fp.brand} {fp.model} @ {dev.rssi}dBm")
```

## Unknown Devices

Find devices that don't match any known pattern — potential security targets:

```python
unknown = fingerprint_db.find_unknown(result.devices)
for dev in unknown:
    print(f"Mystery device: {dev.address} RSSI:{dev.rssi}")
    print(f"  Manufacturer data: {dev.manufacturer_data}")
    print(f"  Service UUIDs: {dev.service_uuids}")
```

## Continuous Monitoring

```python
import asyncio
from bleradar import BLEScanner

scanner = BLEScanner()

def on_device_found(dev):
    print(f"[NEW] {dev}")

async def monitor():
    result = await scanner.scan(
        duration=60.0,
        callback=on_device_found
    )

asyncio.run(monitor())
```

## Requirements

- Python >= 3.10
- Bluetooth adapter (supports BLE 4.0+)
- `bleak` (auto-installed)
- Linux recommended (macOS and Windows also supported)

## Use Cases

- **Security research**: Scan for nearby IoT devices, identify vulnerable hardware
- **Tracker detection**: Find AirTags/Tile trackers being used for surveillance
- **Network auditing**: Map all BLE devices in an environment
- **IoT development**: Debug and fingerprint BLE peripherals
- **Penetration testing**: Recon before targeting BLE-enabled systems

## Donate

If this saved you time or caught a tracker:
- **PayPal**: bill.jtrammell@gmail.com
- **Cash App**: $slauter99

## License

MIT
