Comprehensive Guide to Wireshark Bluetooth Analysis with Ubertooth on Ubuntu

VMWare Version: 14.0.0 build-6661328 Operating System: Ubuntu 14.04.5 LTS Ubertooth Software Version: ubertooth 2018-12-R1 Libbtbb Version: libbtbb 2018-12-R1 Wireshark Version: Version 2.6.6 (Git v2.6.6 packaged as 2.6.6-1~ubuntu14.04.0) Keywords: Wireshark Bluetooth Analysis

The objective of this build and installation is to use Wireshark to view and analyze the intercepted Bluetooth packets. Thus, two components are needed: Ubertooth (the main application) and libbtbb (Bluetooth Baseband Library, with a Wireshark plugin included in the source code).

There is actually another part to consider, included in the Ubertooth download source code, which is the firmware corresponding to the hardware. Since the firmware is matched with the software, it’s necessary to flash the corresponding firmware onto the hardware when compiling the software; otherwise, a “API mismatch” error will occur (discussed further below).

The compilation part of the software is quite simple. If using the Ubuntu system, there is relevant documentation on the official git, and it’s very detailed, allowing for a straightforward following of instructions. Here is a brief explanation.

First, here’s the link to the official WiKi (Build-Guide); if your reading skills are strong, you can directly look at the official instructions. The following description uses Ubuntu as an example.

First, install the compilation environment, such as cmake, gcc, etc., with a single command:

Next, install the Bluetooth Baseband Library, download the source code, and extract it. Here we also borrowed the official command provided, exactly the version I installed is 2018-12-R1.

If you don’t use the wget command, you can also directly download it from the Releases page (note the version and file name), then manually extract it~~

Next, according to the official instructions, use the cd command to enter the extracted folder, and use the mkdir command to create a new folder named build for compiling the source code. After that, it’s a simple and straightforward make process. However, note that the final make install must be run with sudo (having used Kali for a long time, I’ve forgotten there’s something called “Run as Administrator”…) The complete command is as follows:

If there are no errors, it means the installation was successful. Below are some of the screenshots of my build process:

According to the official instructions, the first installation might report errors or fail to find the lib library. In this case, you need to execute in the command line:

That’s it, although I’m not sure why, and I didn’t encounter any error prompts when I installed it.

Ubertooth tool software refers to the command that can be executed in the command line by entering command like ubertooth-xxx. The compilation is similar to libbtbb; download using the wget command or directly from the Release page, and extract. The official command is as follows:

The following steps are the same, create a build folder, complete the installation in this folder with cmake – make – make install:

It should be noted that the compilation is performed in the host folder. There are many other folders in the extracted source code, be careful not to confuse them.

Similarly, the official instructions also provide a hint; if the first compilation or reports of missing the lib library issue occur, execute in the command line:

At this point, the baseband and tools are fully installed, plug in Ubertooth, assign it to the virtual machine, and enter ubertooth-util -v in the command line to see the current firmware version of your Ubertooth.

I’ve already flashed the firmware here, so the displayed version is 2018-12-R1 (I forgot to take a screenshot before flashing the firmware). Seeing the firmware indicates that both the btbb library and Ubertooth tools are successfully installed.

According to the official libbtbb github issue 50, the author has responded to the Wireshark plugin issue:

For Wireshark versions before 2.0, it is necessary to compile the plugins in plugins-legacy.

For Wireshark versions 2.0 to 2.2, it is necessary to compile the plugins in plugins.

For Wireshark versions 2.2+, no plugin compilation is required as Wireshark officially includes the relevant plugins.

Hence, the step of compiling plugins can be skipped.

Before use, it is necessary to update the firmware in the Ubertooth hardware. The ubertooth-util -v command mentioned above can check the current flashed firmware version, and there is also an API version issue. Ubertooth requires the firmware API version to match the Ubertooth tools version, or it will not work.

The source code of Ubertooth tools includes the firmware, which is a .dfu formatted file. Ready-to-use firmware is included in ubertooth-2018-12-R1/ubertooth-one-firmware-bin/bluetooth_rxtx.dfu. The command to update the firmware is:

When I executed this step in the virtual machine, an error occurred. Every time it attempted to switch to DFU mode, USB showed unrecognized, and the four deep-to-light red indicators on the hardware kept cycling. I’m not sure if there’s a problem with my virtual machine or my USB port.

After many unsuccessful attempts, I found a MacBook, installed the ubertooth tool, executed the above command, and successfully flashed.

Here the official provides a troubleshooting: if there is an error libUSB Error: Command Error: (-1), or the four lights on the hardware perform a horse-running effect, the firmware needs to be recompiled, utilizing the contents of the ubertooth-2018-12-R1/firmware folder. The compilation command is as follows:

Previously, when there was a consistent “Unable to find Ubertooth” prompt, I attempted to compile the firmware. It proved that it was not a firmware issue. Since I didn’t successfully flash the compiled firmware, this part will not be discussed further.

At this point, the preliminary preparation work is all completed. Now, Ubertooth needs to be linked with Wireshark to transmit the data collected by Ubertooth to Wireshark for analysis. The main reference here is the official Wiki. The steps are as follows:

Run the command in the terminal: mkfifo /tmp/pipe

Open Wireshark, choose ‘Capture -> Options’ to set up the capture interface

Click on the bottom right corner ‘Manage Interfaces’ to manage the interfaces

Switch to the ‘Pipes’ tab

Save the settings, select ‘/tmp/pipe’ and click to start

At this point, run command in the terminal: ubertooth-btle -f -c /tmp/pipe

Switch back to Wireshark, and you should see the packets scrolling.

One thing to note here, the “mkfifo /tmp/pipe” command needs to be executed before all steps, namely creating the pipe file first, then setting Wireshark to read, and finally writing using the Ubertooth-btle command. An incorrect order will lead to failure.

Some minor issues.

My personal understanding of this problem is that Wireshark could not recognize the specific category of this data packet, thus requiring manual specification.

Before the operation (when there was an error):

The steps are very simple:

Click Edit -> Preference (Edit -> Preferences);

Select DLT_USER option under Protocol on the left;

Click the Edit button.

Click the “+” at the bottom left to add a record. In the DLT section select DLT=147, double-click to modify in the Payload protocol section, input btle, click OK to save.

Now, the display will be normal.

This is what it looks like after fixing:

undefined symbol: new_create_dissector_handle

This issue was caused by compiling the plugins according to the official Build Guide under Wireshark 2.2+ versions. The reason has been explained in the plugin compilation section above, versions 2.2+ can be used directly, without any plugin compilation work.

Since it took quite some time to understand the differences between various versions, mentioning it here seems worthwhile to note.

Below is the error screenshot: