GATTacker

[Gold Max]

A Node.js package for BLE (Bluetooth Low Energy) security assessment using Man-in-the-Middle and other attacks.

Install

Code:
npm install gattacker

Usage

Configure

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

Code:
sudo node ws-slave

Connects to targeted peripheral and acts as websocket server.

Debug:

Code:
DEBUG=ws-slave sudo node ws-slave

Scanning

Scan for advertisements

Code:
node scan

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

Explore services and characteristics

Code:
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.

Example:

Code:
{
"uuid": "06d1e5e779ad4a718faa373789f7d93c",
"name": null,
"properties": [
"write",
"notify"
],
"startHandle": 8,
"valueHandle": 9,
"endHandle": 10,
"descriptors": [
{
"handle": 10,
"uuid": "2902",
"value": ""
}
],
"hooks": {
"dynamicWrite": "dynamicWriteFunction",
"dynamicNotify": "customLog"
}
}
Click to expand...
Click to expand...

Functions:

<dynamic|static><Write|Read|Notify>

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.

Code:
staticValue – static value

Start “peripheral” device

Code:
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.

Code:
cd helpers/bdaddr
make

wrapper script:

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

Dump, replay

Dump files are saved in a path configured by DUMP_PATH in config.env (by default dump). More info: https://github.com/securing/gattacker/wiki/Dump-and-replay

Troubleshooting

Turn off, cross fingers, try again

reset device

Code:
hciconfig <hci_interface> reset

Running ws-slave and advertise on the same box

With this configuration you may experience various problems.

Try switching NOBLE_HCI_INTERFACE and BLENO_HCI_INTERFACE

hcidump debug

Code:
hcidump -x -t <hci_interface>