MITM BLE Security Assessment: gattacker

ID N0WHERE:115264
Type n0where
Reporter N0where
Modified 2016-09-12T17:34:01


MITM BLE Security Assessment

A Node.js package for BLE (Bluetooth Low Energy) Man-in-the-Middle & more

The tool creates exact copy of attacked device in Bluetooth layer, and then tricks mobile application to interpret its broadcasts and connect to it instead the original device. At the same time, it keeps active connection to the device, and forwards to it the data exchanged with mobile application. In this way, acting as “Man-in-the-Middle”, it is possible to intercept and/or modify the transmitted requests and responses.

Most mobile applications initiate connection to device by looking for advertising packets broadcasted by device. Usually battery-powered devices optimize advertising intervals in order to minimize power consumption. The attacker however can broadcast the relevant advertisements with minimal intervals (much “quicker”). The mobile application will interpret the first received advertisement – and in this case it will most probably be the spoofed one. Additionally, as most devices do not broadcast advertisements during active connection, the attacker can just constantly keep connected to original device and thus prevent it from broadcasting.

Currently the tool works for devices which do not implement Bluetooth LE link-layer pairing/encryption. However there is surprisingly lot of such devices.

Possible attacks against encrypted connections are described in:

MITM BLE Security Assessment: gattacker

What are the components of the tool?

The “central” module (ws-slave.js) listens for advertisements, scans the device’s services for cloning in “peripheral”, and forwards the read/write/notification messages exchanged during active attack.

The “peripheral” module (advertise.js) loads device specification (advertisement, services, characteristics, descriptors) collected by “central” module, and acts as the device “emulator”.

Optional hook functions allow to tamper requests and responses.

Helper script scan.js scans for devices and creates JSON files with advertisements and device’s services+characteristics.

Additionally, a BlueRadios AT interface script is attached in standalone/blueRadiosCmd.js.

The components can be run on the same box (with at least two Bluetooth 4 interfaces), or on separate ones. They connect to each other using websockets. By running on the same box, you may experience some unstability, like kernel-level device mismatch (to be debugged). Switching devices with one another usually helps.

By running components on separate boxes, you can interact with devices remotely, e.g. have one box close to a smart lock and another one close to the owner’s phone in separate location. In this way it is possible to abuse auto-unlock proximity features.

What hardware is supported?

The software runs on any recent Linux, including Raspberry Pi. Each module (“central”, “peripheral”) requires a Bluetooth Low Energy adapter. The most popular, CSR 8510-based USB dongle is available for about $10, and is confirmed with stable MAC address changing using the Bluez bdaddr tool.

Do I need to clone the MAC of original device?

In many cases, where mobile application relies only on advertisement contents – not. But many mobile applications match the MAC address of the device. In order to successfully intercept such communication, you need to clone the MAC address. It is possible to do using Bluez bdaddr tool (attached for your convenience in In such case, the attribute’s handle numbers, by which the devices exchange GATT data, must match exactly the original device’s ones. Otherwise the mobile OS’s GATT cache will not match and prevent the communication.


npm install gattacker



Running both components Set up variables in config.env:

  • NOBLE_HCI_DEVICE_ID : noble (“central”, ws-slave) device
  • BLENO_HCI_DEVICE_ID : bleno (“peripheral”, advertise) device

If you run “central” and “peripheral” modules on separate boxes with just one BT4 interface, you can leave the values commented.

  • WS_SLAVE : IP address of ws-slave box
  • DEVICES_PATH : path to store json files

Start “central” device

sudo node ws-slave

Connects to targeted peripheral and acts as websocket server.


DEBUG=ws-slave sudo node ws-slave


Scan for advertisements

node scan

Without parameters scans for broadcasted advertisements, and records them as json files (.adv.json) in DEVICES_PATH

Explore services and characteristics

node scan <peripheral>

Explore services and characteristics of chosen peripheral. Saves the explored service structure in json file (.srv.json) in DEVICES_PATH.

Hook configuration (option)

For active request/response tampering configure hook functions for characteristic in device’s json services file.


                "uuid": "06d1e5e779ad4a718faa373789f7d93c",
                "name": null,
                "properties": [
                "startHandle": 8,
                "valueHandle": 9,
                "endHandle": 10,
                "descriptors": [
                        "handle": 10,
                        "uuid": "2902",
                        "value": ""
                "hooks": {
                    "dynamicWrite": "dynamicWriteFunction",
                    "dynamicNotify": "customLog"


dynamic: connect to original device

static: do not connect to original device, run the tampering function locally

It will try to invoke the specified function from hookFunctions, include your own. A few examples provided in hookFunctions subdir.

staticValue – static value

Start “peripheral” device

node advertise -a <advertisement_json_file> [ -s <services_json_file> ]

It connects via websocket to ws-slave in order to forward requests to original device. Static run (-s) sets services locally, does not connect to ws-slave. You have to configure the hooks properly.

MAC address cloning

For many applications it is necessary to clone MAC address of original device. A helper tool bdaddr from Bluez is provided in helpers/bdaddr.

cd helpers/bdaddr

wrapper script:

./mac_adv -a <advertisement_json_file> [ -s <services_json_file> ]

MITM BLE Security Assessment: gattacker Download