BtleJuice is a complete framework to perform Man-in-the-Middle attacks on Bluetooth Smart devices (also known as Bluetooth Low Energy). It is composed of:
How to install BtleJuice ?
Installing BtleJuice is a child's play. First of all, make sure your system uses a recent version of Node.js (>=4.3.2) and npm. Then, make sure to install all the required dependencies:
Ubuntu/Debian/Raspbian
How to use BtleJuice ?
BtleJuice is composed of two main components: an interception proxy and a core. These two components are required to run on independent machines in order to operate simultaneously two bluetooth 4.0+ adapters. BtleJuice Proxy does not work in a Docker container.
The use of a virtual machine may help to make this framework work on a single computer.
From your virtual machine, install btlejuice and make sure your USB BT4 adapter is available from the virtual machine:
Launch the proxy in your virtual machine:
The Web User Interface is now available at http://localhost:8080. Note the web server port may be changed through command-line.
Using the web interface
The BtleJuice's web interface provides in the top-right corner a set of links to control the interception core, as shown below.
![]()
Target selection
First, click the Select target button and a dialog will show up displaying all the available Bluetooth Low Energy devices detected by the interception core:
![]()
Double-click on the desired target, and wait for the interface to be ready (the bluetooth button's aspect will change). Once the dummy device ready, use the associated mobile application or another device (depending on what is expected) to connect to the dummy device. If the connection succeeds, a Connected event would be shown on the main interface.
![]()
All the intercepted GATT operations are then displayed with the corresponding services and characteristics UUID, and of course the data associated with them. The data is shown by default with the HexII format (a variant of the format designed by Ange Albertini), but you may want to switch from HexII to Hex (and back) by clicking on the data itself. Both Hex and HexII format are supported by BtleJuice.
Replay GATT operations
It is possible to replay any GATT operation by right-clicking it and then selecting the Replay option, as shown below:
![]()
![]()
Click the Write (or Read) button to replay the corresponding GATT operation. This operation will be logged in the main interface.
On-the-fly data modification
Last but not least, the interface may intercept locally or globally any GATT operation and allow on-the-fly data modification. You may either use the global interception by clicking the Intercept button in the top-right corner or use the contextual menu to enable or disable a hook on a given service and characteristic. Any time a GATT operation is intercepter, the following dialog box will show up:
![]()
Export data to file
Since version 1.0.6, the interface provides a data export feature allowing readable and JSON exports. These exports are generated based on the intercepted GATT operations, but also include information about the target device. When the Export button is clicked, the following dialog will show up:
![]()
Click the Export button at the bottom of the dialog box to download a JSON (or text) version of the intercepted data.
Settings
The settings dialog provides a single option at the moment allowing to automatically reconnect the proxy when the target device disconnects. This may be useful when dealing with devices that are active during a short amount of time.
![]()
Disconnection
Clicking the top-right Select Target button when the proxy is active will stop it and allow target selection again.
Installing the bindings
BtleJuice's Node.js bindings may be installed as well through npm:
![]()
- an interception core
- an interception proxy
- a dedicated web interface
- Python and Node.js bindings
How to install BtleJuice ?
Installing BtleJuice is a child's play. First of all, make sure your system uses a recent version of Node.js (>=4.3.2) and npm. Then, make sure to install all the required dependencies:
Ubuntu/Debian/Raspbian
sudo apt-get install bluetooth bluez libbluetooth-dev libudev-devsudo yum install bluez bluez-libs bluez-libs-devel npmsudo npm install -g btlejuiceHow to use BtleJuice ?
BtleJuice is composed of two main components: an interception proxy and a core. These two components are required to run on independent machines in order to operate simultaneously two bluetooth 4.0+ adapters. BtleJuice Proxy does not work in a Docker container.
The use of a virtual machine may help to make this framework work on a single computer.
From your virtual machine, install btlejuice and make sure your USB BT4 adapter is available from the virtual machine:
$ sudo hciconfig
hci0: Type: BR/EDR Bus: USB
BD Address: 10:02:B5:18:07:AD ACL MTU: 1021:5 SCO MTU: 96:6
DOWN
RX bytes:1433 acl:0 sco:0 events:171 errors:0
TX bytes:30206 acl:0 sco:0 commands:170 errors:0
$ sudo hiconcig hci0 upLaunch the proxy in your virtual machine:
$ sudo btlejuice-proxy$ sudo service bluetooth stop
$ sudo hciconfig hci0 up$ sudo btlejuice -u <Proxy IP address> -wThe Web User Interface is now available at http://localhost:8080. Note the web server port may be changed through command-line.
Using the web interface
The BtleJuice's web interface provides in the top-right corner a set of links to control the interception core, as shown below.
Target selection
First, click the Select target button and a dialog will show up displaying all the available Bluetooth Low Energy devices detected by the interception core:
Double-click on the desired target, and wait for the interface to be ready (the bluetooth button's aspect will change). Once the dummy device ready, use the associated mobile application or another device (depending on what is expected) to connect to the dummy device. If the connection succeeds, a Connected event would be shown on the main interface.
All the intercepted GATT operations are then displayed with the corresponding services and characteristics UUID, and of course the data associated with them. The data is shown by default with the HexII format (a variant of the format designed by Ange Albertini), but you may want to switch from HexII to Hex (and back) by clicking on the data itself. Both Hex and HexII format are supported by BtleJuice.
Replay GATT operations
It is possible to replay any GATT operation by right-clicking it and then selecting the Replay option, as shown below:
Click the Write (or Read) button to replay the corresponding GATT operation. This operation will be logged in the main interface.
On-the-fly data modification
Last but not least, the interface may intercept locally or globally any GATT operation and allow on-the-fly data modification. You may either use the global interception by clicking the Intercept button in the top-right corner or use the contextual menu to enable or disable a hook on a given service and characteristic. Any time a GATT operation is intercepter, the following dialog box will show up:
Export data to file
Since version 1.0.6, the interface provides a data export feature allowing readable and JSON exports. These exports are generated based on the intercepted GATT operations, but also include information about the target device. When the Export button is clicked, the following dialog will show up:
Click the Export button at the bottom of the dialog box to download a JSON (or text) version of the intercepted data.
Settings
The settings dialog provides a single option at the moment allowing to automatically reconnect the proxy when the target device disconnects. This may be useful when dealing with devices that are active during a short amount of time.
Disconnection
Clicking the top-right Select Target button when the proxy is active will stop it and allow target selection again.
Installing the bindings
BtleJuice's Node.js bindings may be installed as well through npm:
$ sudo npm install -g btlejuice-bindings