GATTacker: BLE MITM Research Tool

GATTacker is a Node.js tool for performing man-in-the-middle attacks on Bluetooth Low Energy devices. It works by cloning a target BLE peripheral's advertising data and GATT profile, then sitting between the real device and whatever central (phone, tablet, computer) connects to it. Every read, write, and notification passes through GATTacker, where you can log, modify, or replay the data.

This makes it a powerful research tool for understanding how BLE devices communicate, finding authentication weaknesses, and testing whether IoT devices properly validate the data they receive.

What Is GATTacker?

GATTacker operates as a BLE proxy. It creates a fake peripheral that looks identical to the real one - same device name, same services, same characteristics. When a central device (like a smartphone app) connects to the fake peripheral, GATTacker forwards all operations to the real device and returns the responses.

The attack flow is:

1. Scan the target BLE device to capture its advertising data and GATT profile
2. Clone the device by creating a fake peripheral with identical characteristics
3. Stop the real device from advertising (or move it out of range, or rely on signal strength)
4. Wait for the central (phone app) to connect to your clone
5. Proxy all GATT operations between the central and the real device
6. Log, modify, or block data in transit

BLE Security Background

sequenceDiagram
    participant Phone as Phone App
    participant Fake as GATTacker (Fake Peripheral)
    participant Real as Real BLE Device
    
    Note over Phone,Real: Normal BLE Connection
    Phone->>Real: Connect + GATT Discovery
    Real-->>Phone: Services and Characteristics
    Phone->>Real: Write Command (e.g., unlock)
    Real-->>Phone: Response
    
    Note over Phone,Real: GATTacker MITM
    Phone->>Fake: Connect (thinks it is real device)
    Fake->>Real: Forward Connection
    Phone->>Fake: Write Command
    Note over Fake: Log/Modify Data
    Fake->>Real: Forward (possibly modified)
    Real-->>Fake: Response
    Fake-->>Phone: Forward Response

Normal BLE connection versus GATTacker MITM - the phone cannot distinguish the fake peripheral from the real one

BLE (Bluetooth Low Energy) uses the Generic Attribute Profile (GATT) for data exchange. A peripheral device exposes services, each containing characteristics. Characteristics have properties like read, write, write-without-response, and notify.

The fundamental security problem: most BLE devices do not authenticate at the GATT level. A peripheral does not verify who is connecting to it, and a central does not verify which peripheral it is connecting to. The connection is established based on device name and advertising data - both of which can be cloned trivially.

BLE pairing (with bonding) can provide authentication through shared keys, but many IoT devices skip pairing entirely for user convenience. Smart locks, fitness trackers, medical devices, and industrial sensors frequently use no pairing or "Just Works" pairing, which provides encryption but no authentication against MITM.

How GATTacker Works

graph TD
    subgraph "Phase 1 - Scanning"
        A["BLE Adapter 1"] --> B["Scan for Devices"]
        B --> C["Capture Advertising\nData and Services"]
        C --> D["Save Device Profile\nJSON file"]
    end
    subgraph "Phase 2 - Cloning"
        D --> E["Parse GATT Profile"]
        E --> F["Create Fake Peripheral\nBLE Adapter 2"]
        F --> G["Broadcast Matching\nAdvertisements"]
    end
    subgraph "Phase 3 - Proxying"
        H["Central Connects\nto Fake Device"] --> I["GATTacker Intercepts"]
        I --> J["Forward to Real Device\nvia Adapter 1"]
        J --> K["Log Operations"]
        K --> L["Return Responses\nto Central"]
    end
    subgraph "Optional - Modification"
        I --> M["Hook Functions"]
        M --> N["Modify Read Values"]
        M --> O["Modify Write Data"]
        M --> P["Block Operations"]
        M --> Q["Replay Previous Data"]
    end

GATTacker's three-phase operation - scan, clone, and proxy with optional data modification

GATTacker requires two Bluetooth adapters. One connects to the real target device as a central, and the other advertises as a fake peripheral to attract the victim's phone or app.

The tool is built on the noble (BLE central) and bleno (BLE peripheral) Node.js libraries. It constructs a complete GATT server that mirrors the target device, with each characteristic forwarding operations to the corresponding characteristic on the real device.

Hardware Requirements

You need two BLE-capable adapters. The internal Bluetooth on most laptops counts as one. For the second, a USB Bluetooth 4.0+ dongle works. Recommended chipsets:

• CSR8510 - widely available, cheap, good Linux support
• Intel AX200/AX210 - built into many laptops
• Broadcom BCM20702 - solid compatibility

The BLEShark Nano can complement this setup by providing BLE scanning and reconnaissance from a portable device. Use it to identify target devices and their advertising behavior before setting up the GATTacker proxy on your laptop.

Important: The two adapters need to operate simultaneously - one in central mode and one in peripheral mode. Some adapters do not support peripheral mode well. Test both before committing to a setup.

Installation

GATTacker runs on Linux (Ubuntu/Debian recommended). macOS has partial support but is less reliable for peripheral mode.

# Install dependencies
sudo apt install bluetooth bluez libbluetooth-dev libudev-dev

# Install Node.js (v12-v16 recommended for compatibility)
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install nodejs

# Clone and install GATTacker
git clone https://github.com/nicofischetti/GATTacker.git
cd GATTacker
npm install

You may need to grant Node.js raw Bluetooth access:

sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)

Configure which adapter does what by setting environment variables:

# Adapter for connecting to real device (central role)
export NOBLE_HCI_DEVICE_ID=0

# Adapter for fake peripheral (peripheral role)
export BLENO_HCI_DEVICE_ID=1

Scanning and Enumeration

Start by scanning for BLE devices:

node scan.js

This lists all discoverable BLE devices with their names, MAC addresses, RSSI, and advertised service UUIDs. Identify your target and note its address.

Next, enumerate the target's full GATT profile:

node scan.js [target MAC address]

This connects to the device and dumps all services, characteristics, descriptors, and their properties. The output is saved as a JSON file in the devices directory. This JSON file is the blueprint GATTacker uses to create the clone.

Review the JSON output carefully. Look for:

• Services with non-standard UUIDs (vendor-specific functionality)
• Characteristics with write or write-without-response properties (command channels)
• Characteristics with notify properties (data channels)
• Any readable characteristics that return interesting data

Cloning a Device

With the device profile saved, create the clone:

node advertise.js -a [device JSON file]

This starts advertising with the same name, services, and advertising data as the real device. The fake peripheral's MAC address will be different (you generally cannot clone MAC addresses in BLE without custom firmware), but most apps identify devices by name, not MAC.

Some applications do check the MAC address, especially after initial pairing. In these cases, the MITM attack only works before the first legitimate connection - after pairing, the app stores the real device's MAC and will not connect to a different one.

Running the MITM Proxy

Start the full proxy:

node ws-slave.js          # On one terminal (connects to real device)
node advertise.js -a [device file] -w   # On another terminal (fake peripheral with WebSocket forwarding)

When the victim's phone connects to the fake peripheral, GATTacker establishes a parallel connection to the real device. Every GATT operation is forwarded:

• Read: Phone reads a characteristic from the fake peripheral. GATTacker reads the same characteristic from the real device and returns the value.
• Write: Phone writes to the fake peripheral. GATTacker writes the same data to the real device's corresponding characteristic.
• Notify: Real device sends a notification. GATTacker receives it and sends the same notification to the phone through the fake peripheral.

All operations are logged to the console with timestamps, characteristic UUIDs, and data values (usually in hex).

Intercepting and Modifying Data

The real power of GATTacker is data modification. You can write hook functions that intercept and alter data in transit.

For example, if a smart lock sends an "unlock" command as a specific byte sequence, you can:

• Log the unlock command to learn the protocol
• Replay the command later without the phone
• Block the lock command to prevent unlocking
• Modify the command to test how the device handles unexpected input

Hook functions are JavaScript modules that GATTacker loads at runtime. A simple logging hook:

// hooks/log_all.js
module.exports = {
    onWrite: function(device, characteristic, data) {
        console.log(`[WRITE] ${characteristic}: ${data.toString('hex')}`);
        return data;  // Forward unchanged
    },
    onRead: function(device, characteristic, data) {
        console.log(`[READ] ${characteristic}: ${data.toString('hex')}`);
        return data;  // Forward unchanged
    },
    onNotify: function(device, characteristic, data) {
        console.log(`[NOTIFY] ${characteristic}: ${data.toString('hex')}`);
        return data;  // Forward unchanged
    }
};

A modification hook that changes temperature readings:

// hooks/modify_temp.js
module.exports = {
    onRead: function(device, characteristic, data) {
        if (characteristic === '2a6e') {  // Temperature UUID
            // Add 10 degrees to the reading
            let temp = data.readInt16LE(0);
            temp += 100;  // BLE temp is in 0.01 degree units
            let modified = Buffer.alloc(2);
            modified.writeInt16LE(temp, 0);
            return modified;
        }
        return data;
    }
};

Limitations and Defenses

BLE Secure Connections (LE Secure Connections with Numeric Comparison): If both devices support BLE 4.2+ Secure Connections with numeric comparison or passkey entry, the pairing process includes ECDH key exchange that prevents MITM. GATTacker cannot intercept these connections.

Application-layer authentication: Well-designed BLE apps implement their own authentication on top of GATT. Challenge-response protocols, signed commands, and encrypted payloads all work regardless of the transport security. GATTacker can still see the encrypted bytes but cannot modify them meaningfully.

MAC address checking: If the app remembers the device MAC from a previous connection, it will not connect to the clone. This limits the attack to first-connection scenarios.

Signal strength: In practice, the real device is usually closer to the victim's phone than the attacker. Getting the phone to connect to the fake peripheral instead of the real one requires either jamming the real device, being physically closer, or using a higher-power Bluetooth adapter.

BLE 5.x improvements: LE Audio and newer BLE specifications include enhanced security features. The protocol is gradually closing the gaps that tools like GATTacker exploit.

Defenses for BLE device developers:

• Use LE Secure Connections with numeric comparison or passkey for pairing
• Implement application-layer authentication (challenge-response)
• Sign or encrypt sensitive GATT payloads
• Validate data integrity on both ends
• Use bonding so devices remember each other
• Implement certificate-based or token-based authentication

Responsible Use

GATTacker is a research tool. Legitimate uses include:

• Security auditing of your own BLE products
• Understanding BLE protocol behavior for development
• Testing whether IoT devices are vulnerable to MITM
• Academic research into BLE security
• Penetration testing with written authorization

If you discover vulnerabilities in commercial products, follow responsible disclosure practices. Contact the manufacturer, give them reasonable time to fix the issue, and coordinate public disclosure.

BLE MITM tools combined with devices like the BLEShark Nano give you a complete toolkit for BLE security research - from initial scanning and reconnaissance to active interception and protocol analysis.

This article is for educational and authorized security research purposes only. Only test devices you own or have explicit written permission to test. Intercepting others' Bluetooth communications without authorization is illegal.