Awesome

<h1 align="center">Bluing</h1> <h3 align="center">An intelligence gathering tool for hacking Bluetooth</h3> <a href="https://fo-000.github.io/bluing/">English</a> · <a href="https://fo-000.github.io/bluing/index-cn.html">简体中文</a> <img src="https://img.shields.io/badge/python-3.10-blue"> <a href="https://pypi.org/project/bluing/"><img src="https://img.shields.io/pypi/v/bluing?color=blue"></a> <a href="https://pepy.tech/badge/bluing"><img src="https://pepy.tech/badge/bluing"></a> <a href="https://pepy.tech/badge/bluescan"><img src="https://static.pepy.tech/personalized-badge/bluescan?period=total&units=international_system&left_color=grey&right_color=blue&left_text=predecessor%20downloads"></a> <img src="https://img.shields.io/badge/Tested%20on-Ubuntu%2022.04%20(x64)%20%7C%20Kali%202022.4%20(x64)%20%7C%20Kali%20NetHunter%202022.4%20(aarch64)-brightgreen">

Bluing (formerly bluescan) is a Bluetooth Intelligence Gathering tool written primarily in Python. It can help us snoop on the internal structure of Bluetooth which is a complex protocol, or hack Bluetooth devices. Here are the main features of the tool:

Installation

Bluing partially depend on BlueZ, the official Linux Bluetooth protocol stack. So it only supports running on Linux. The following command is used to install dependencies:

sudo apt install python3-pip python3-dev libcairo2-dev libgirepository1.0-dev \
                 libbluetooth-dev libdbus-1-dev bluez-tools python3-cairo-dev \
                 rfkill meson patchelf bluez ubertooth adb python-is-python3

Currently, bluing is distributed via PyPI and only supports Python 3.10. The following is an installation command:

sudo pip3.10 install bluing

Usage

God said, "Let there be colorful", and there was colorful.

Perhaps you would like a brief overview of the recommended hardware.

<details><summary><code>$ bluing --help</code></summary> <pre> An intelligence gathering tool for hacking Bluetooth Usage: bluing [-h | --help] bluing (-v | --version) bluing [-i &lthci>] --clean BD_ADDR bluing --flash-micro-bit bluing &ltcommand> [&ltargs>...] Arguments: BD_ADDR Bluetooth device address Options: -h, --help Print this help and quit -v, --version Print version information and quit -i &lthci> HCI device --clean Clean cached data of a remote device --flash-micro-bit Download the dedicated firmware to micro:bit(s) Commands: br Basic Rate system, includes an optional Enhanced Data Rate (EDR) extension le Low Energy system android Android Bluetooth stack spoof Spoof with new local device information plugin Manage plugins Run `bluing &ltcommand> --help` for more information on a command. </pre> </details>

`br` command: Basic Rate system

<details><summary><code>$ bluing br --help</code></summary> <pre> Usage: bluing br [-h | --help] bluing br [-i &lthci>] [--inquiry-len=&ltn>] --inquiry bluing br [-i &lthci>] --sdp BD_ADDR bluing br [-i &lthci>] --local --sdp bluing br [-i &lthci>] --lmp-features BD_ADDR bluing br [-i &lthci>] --local --lmp-features bluing br [-i &lthci>] --stack BD_ADDR bluing br [-i &lthci>] --local --stack bluing br [-i &lthci>] [--inquiry-scan] --mon-incoming-conn bluing br --org=&ltname> --timeout=&ltsec> --sniff-and-guess-bd-addr Arguments: BD_ADDR BR/EDR Bluetooth device address Options: -h, --help Print this help and quit -i &lthci> HCI device --local Target a local BR/EDR device instead of a remote one --inquiry Discover other nearby BR/EDR controllers --inquiry-len=&ltn> Maximum amount of time (added to --ext-inquiry-len=&ltn>) specified before the Inquiry is halted. Time = n * 1.28 s Time range: 1.28 to 61.44 s Range of n: 0x01 to 0x30 [default: 8] --ext-inquiry-len=&ltn> Extended_Inquiry_Length measured in number of Baseband slots. Interval Length = n * 0.625 ms (1 Baseband slot) Time Range: 0 to 40.9 s Range of n: 0x0000 to 0xFFFF [default: 0] --sdp Retrieve information from the SDP database of a remote BR/EDR device --lmp-features Read LMP features of a remote BR/EDR device --stack Determine the Bluetooth stack type of a remote BR/EDR device --mon-incoming-conn Print incoming connection from other nearby BR/EDR devices --inquiry-scan Enable the Inquiry Scan --sniff-and-guess-bd-addr Sniff SAPs of BD_ADDRs over the air, then guess the address based on the organization name. Need at least one Ubertooth device --org=&ltname> An organization name in the OUI.txt --timeout=&ltsec> Timeout in second(s) </pre> </details>

`--inquiry`: Discover other nearby BR/EDR controllers

<details><summary><code>$ sudo bluing br --inquiry</code></summary> <pre> [INFO] Discovering other nearby BR/EDR Controllers on hci0 for 10.24 sec BD_ADDR: B0:C9:52:45:33:13 (GUANGDONG OPPO MOBILE TELECOMMUNICATIONS CORP.,LTD) Page scan repetition mode: 1 (R1) Reserved: 0x02 CoD: 0x5a020c Service Class: 0b1011010000 Telephony Object Transfer Capturing Networking Major Device Class: 0b00010, Phone Clock offset: 0x50D5 RSSI: -61 Extended inquiry response: Complete Local Name: old man phone Complete List of 16-bit Service Class UUIDs 0x1105 OBEXObjectPush 0x110a AudioSource 0x110c A/V_RemoteControlTarget 0x110e A/V_RemoteControl 0x1112 Headset - Audio Gateway (AG) 0x1115 PANU 0x1116 NAP 0x111f HandsfreeAudioGateway 0x112d SIM_Access 0x112f Phonebook Access - PSE 0x1200 PnPInformation 0x1132 Message Access Server Complete List of 32-bit Service Class UUIDs None Complete List of 128-bit Service Class UUIDs A49EAA15-CB06-495C-9F4F-BB80A90CDF00 00000000-0000-0000-0000-000000000000 ... ... [INFO] Requesting the names of all discovered devices... B0:C9:52:45:33:13 : old man phone ... ... </pre> </details>

`--sdp`: Retrieve information from the SDP database of a remote BR/EDR device

<details><summary><code>$ sudo bluing br --sdp 34:13:46:23:6A:4D</code></summary> <pre> Scanning ⠋ Number of service records: 18 Service Record 0x0000: ServiceRecordHandle (uint32) 0x0001000d 0x0001: ServiceClassIDList (sequence) 0x1105: OBEXObjectPush 0x0004: ProtocolDescriptorList (sequence) 0x0100: L2CAP 0x0003: RFCOMM channel: 0x0c 0x0008: OBEX 0x0005: BrowseGroupList (sequence) 0x1002: PublicBrowseRoot 0x0009: BluetoothProfileDescriptorList (sequence) 0x1105: OBEXObjectPush v1.2 0x0100: ServiceName (guess) (text) OBEX Object Push 0x0200: GoepL2CapPsm (guess) (uint16) 0x1023 0x0303: SupportedFormatsList (guess) (sequence) 0x01: vCard 2.1 0x02: vCard 3.0 0x03: vCal 1.0 0x04: iCal 2.0 0xff: Any type of object ... ... </pre> </details>

`--lmp-features`: Read LMP features of a remote BR/EDR device

<details><summary><code>$ sudo bluing br --lmp-features 6A:8D:99:33:56:AE</code></summary> <pre> Version Version: Bluetooth Core Specification 5.2 (LMP) Bluetooth Core Specification 5.2 (LL) Manufacturer name: HiSilicon Technologies CO., LIMITED Subversion: 33561 LMP features 3 slot packets: True 5 slot packets: True Encryption: True Slot offset: True Timing accuracy: True Role switch: True Hold mode: False Sniff mode: True Previously used: False Power control requests: True Channel quality driven data rate (CQDDR): True ... ... Extended LMP features Page 1 Secure Simple Pairing (Host Support): True LE Supported (Host): True Simultaneous LE and BR/EDR to Same Device Capable (Host): True Secure Connections (Host Support): True Page 2 Connectionless Slave Broadcast - Master Operation: False Connectionless Slave Broadcast - Slave Operation: False Synchronization Train: False Synchronization Scan: False HCI_Inquiry_Response_Notification event: True ... ... </pre> </details>

`--mon-incoming-conn`: Print incoming connection from other nearby BR/EDR devices

<details><summary><code>$ sudo bluing br --inquiry-scan --mon-incoming-conn</code></summary> <pre> [INFO] Inquiry_Scan_Interval: 4096, 2560.0 ms Inquiry_Scan_Window: 4096, 2560.0 ms [INFO] Inquiry Scan and Page Scan enabled A0:DE:0F:99:EF:78 incoming CoD: 0x5a020c Service Class: 0b1011010000 Telephony Object Transfer Capturing Networking Major Device Class: 0b00010, Phone link type: 0x01 - ACL ... ... </pre> </details>

`--sniff-and-guess-bd-addr`: Sniff and guess nearby BD_ADDRs over the air

<details><summary><code>$ bluing br --org='Huawei Device Co., Ltd.' --timeout=600 --sniff-and-guess-bd-addr</code></summary> <pre> [INFO] Possible BD_ADDR for ??:??:99:4C:45:C3 24:A7:99:4C:45:C3 [INFO] Possible BD_ADDR for ??:??:E4:2D:69:EE BC:1A:E4:2D:69:EE D0:05:E4:2D:69:EE 30:AA:E4:2D:69:EE [INFO] Possible BD_ADDR for ??:??:15:60:81:7F 64:23:15:60:81:7F D4:74:15:60:81:7F ... ... </pre> </details>

`le` command: Low Energy system

<details><summary><code>$ bluing le --help</code></summary> <pre> Usage: bluing le [-h | --help] bluing le [-i &lthci>] [--scan-type=&lttype>] [--timeout=&ltsec>] [--sort=&ltkey>] --scan bluing le [-i &lthci>] --pairing-feature [--timeout=&ltsec>] [--addr-type=&lttype>] PEER_ADDR bluing le [-i &lthci>] --ll-feature-set [--timeout=&ltsec>] [--addr-type=&lttype>] PEER_ADDR bluing le [-i &lthci>] --gatt [--io-cap=&ltname>] [--addr-type=&lttype>] PEER_ADDR bluing le [-i &lthci>] --local --gatt bluing le [-i &lthci>] --mon-incoming-conn bluing le [--device=&lt/dev/tty>] [--channel=&ltnum>] --sniff-adv Arguments: PEER_ADDR LE Bluetooth device address Options: -h, --help Print this help and quit -i &lthci> HCI device --scan Discover advertising devices nearby --scan-type=&lttype> The type of scan to perform. active or passive [default: active] --sort=&ltkey> Sort the discovered devices by key, only support RSSI now [default: rssi] --ll-feature-set Read LL FeatureSet of a remote LE device --pairing-feature Request the pairing feature of a remote LE device --timeout=&ltsec> Duration of the LE scanning, but may not be precise [default: 10] --gatt Discover GATT Profile hierarchy of a remote LE device --io-cap=&ltname> Set IO capability of the agent. Available value: DisplayOnly, DisplayYesNo, KeyboardOnly, NoInputNoOutput, KeyboardDisplay (KeyboardOnly) [default: NoInputNoOutput] --addr-type=&lttype> Type of the LE address, public or random --sniff-adv Sniff advertising physical channel PDU. Need at least one micro:bit (or other supported NRF51 device specified with --device) --channel=&ltnum> LE advertising physical channel, 37, 38 or 39 [default: 37,38,39] --device=&lt/dev/tty> Device to use, comma separated (e.g., /dev/ttyUSB0,/dev/ttyUSB1,/dev/ttyUSB2) Only needed if using NRF51 devices other than micro:bit (e.g., Bluefruit) </pre> </details>

`--scan`: Discover advertising devices nearby

<details><summary><code>$ sudo bluing le --scan</code></summary> <pre> [WARNING] You might want to spoof your LE address before doing an active scan [INFO] LE active scanning on hci0 for 10 sec Scanning ⠴ ----------------LE Devices Scan Result---------------- Addr: 74:A3:4A:D4:78:55 (ZIMI CORPORATION) Addr type: public Connectable: True RSSI: -68 dBm General Access Profile: Flags: LE General Discoverable Mode BR/EDR Not Supported Service Data - 16-bit UUID: UUID: 0x95FE Data: 9055990701b743e34aa3740e00 Appearance: 0000 Tx Power Level: 0 dBm (pathloss 68 dBm) Complete Local Name: Mesh Mi Switch ... ... </pre> </details>

`--ll-feature-set`: Read LL FeatureSet of a remote LE device

<details><summary><code>$ sudo bluing le --ll-feature-set --addr-type=public 18:D9:8F:77:24:F1</code></summary> <pre> [INFO] Reading LL FeatureSet of 18:D9:8F:77:24:F1 on hci0 Reading ⠼ LE LL Features: LE Encryption: True Connection Parameters Request Procedure: False Extended Reject Indication: False Slave-initiated Features Exchange: False LE Ping: False LE Data Packet Length Extension: True LL Privacy: False Extended Scanner Filter Policies: False LE 2M PHY: False Stable Modulation Index - Transmitter: False Stable Modulation Index - Receiver: False ... ... </pre> </details>

`--pairing-feature`: Request the pairing feature of a remote LE device

<details><summary><code>$ sudo bluing le --pairing-feature --addr-type=public 18:D9:8F:77:24:F1</code></summary> <pre> [INFO] Requesting pairing feature of 18:D9:8F:77:24:F1 on hci0 Requesting ⠧ Pairing Response IO Capability: 0x03 - NoInputNoOutput OOB data flag: 0x00 - Not Present AuthReq: 0x01 Maximum Encryption Key Size: 16 Initiator Key Distribution: 0x00 EncKey: False IdKey: False SignKey: False LinkKey: False RFU: 0b0000 Responder Key Distribution: 0x01 EncKey: True IdKey: False SignKey: False LinkKey: False RFU: 0b0000 </pre> </details>

`--gatt`: Discover GATT Profile hierarchy of a remote LE device

<details><summary><code>$ sudo bluing le --gatt --addr-type=public 18:D9:8F:77:24:F1</code></summary> <pre> Connecting ⠋ Discovering all primary services ⠏ Discovering all characteristics of service 0x0001 ⠹ ... ... Discovering all descriptors of characteristic 0x0002 ⠼ ... ... Reading value of the descriptor 0x0013 ⠴ ... ... ----------------GATT Scan Result---------------- Number of services: 6 Service (0x0100 - 0x0112, 7 characteristics) Declaration Handle: 0x0100 Type: 2800 (Primary Service declaration) Value: 1812 (Human Interface Device) Permissions: Read (no authen/author) Characteristic (2 descriptors) Declaration Handle: 0x010d Type: 2803 (Characteristic declaration) Value: Properties: Read, Write Without Response, Write, Notify Handle: 0x010e UUID: 2A4D (Report) Permissions: Read (no authen/author) Value Handle: 0x0302 Type: 4A02 (Unknown) Value: Read Not Permitted Permissions: Higher layer specific Descriptor Handle: 0x010f Type: 2902 (Client Characteristic Configuration declaration) Value: b'\x00\x00' Permissions: Read (no authen/author), Write (higher layer specifies authen/author) ... ... </pre> </details>

`--sniff-adv`: Sniff advertising physical channel PDU

<details><summary><code>$ sudo bluing le --sniff-adv</code></summary> <pre> [INFO] Using micro:bit /dev/ttyACM2 on channel 37 [INFO] Using micro:bit /dev/ttyACM1 on channel 38 [INFO] Using micro:bit /dev/ttyACM0 on channel 39 [INFO] micro:bit 38 < Ready -> Start [INFO] micro:bit 37 < Ready -> Start [INFO] micro:bit 39 < Ready -> Start [38] [ADV_NONCONN_IND] random AdvA: 28:7A:88:B2:35:0B [39] [ADV_IND] public AdvA: A4:E4:72:B1:CB:8D [37] [SCAN_REQ] random ScanA: 6A:90:0C:07:3E:14 random AdvA: 7D:9B:A8:5A:F2:81 ... ... </pre> </details>

`android` command: Android Bluetooth stack

<details><summary><code>$ bluing android --help</code></summary> <pre> Usage: bluing android [-h | --help] bluing android [-t &ltid>] --collect-btsnoop-log [-o &ltfile>] Options: -h, --help Display this help and quit -t &ltid> Use android device with given transport id. This option will be ignored when only one device is available --collect-btsnoop-log Collect the btsnoop log being generated to a local file, default ./btsnoop_hci.log -o &ltfile> Place the output into <file> [default: ./btsnoop_hci.log] </pre> </details>

`--collect-btsnoop-log`: Collect the btsnoop log being generated

<details><summary><code>$ bluing android -t 3 --collect-btsnoop-log -o btsnoop_hci.log; file btsnoop_hci.log</code></summary> <pre> btsnoop_hci.log: BTSnoop version 1, HCI UART (H4) </pre> </details>

`spoof` command: Spoof with new local device information

<details><summary><code>$ bluing spoof --help</code></summary> <pre> Usage: bluing spoof [-h | --help] bluing spoof [-i &lthci>] --bd-addr=&ltBD_ADDR> bluing spoof [-i &lthci>] --cls-of-dev=&ltnum> bluing spoof --host-name=&ltname> bluing spoof [-i &lthci>] --alias=&ltalias> Options: -h, --help Print this help and quit -i &lthci> HCI device --bd-addr=&ltBD_ADDR> Spoof with a new BD_ADDR --cls-of-dev=&ltnum> Spoof with a new Class of Device --host-name=&ltname> Spoof with a new host name --alias=&ltalias> Spoof with a new alias </pre> </details>

`--bd-addr=<BD_ADDR>`: Spoof with a new BD_ADDR

This feature is currently based on spooftooph, which can be installed by runing sudo apt install spooftooph if you are using it on Kali Linux. However, if you are using this feature on Ubuntu, you will need to manually compile and install spooftooph.

<details><summary><code>$ sudo bluing spoof --bd-addr=AA:BB:CC:DD:EE:FF</code></summary> <pre> [WARNING] The original HCI device number may have been changed [INFO] BD_ADDR changed: 11:22:33:44:55:66 -> AA:BB:CC:DD:EE:FF </pre> </details>

`--cls-of-dev=<num>`: Spoof with a new Class of Device

<details><summary><code>$ sudo bluing spoof --cls-of-dev=0x6c0100</code></summary> <pre> No output when successful </pre> </details>

`--host-name=<name>`: Spoof with a new host name

<details><summary><code>$ sudo bluing spoof --host-name=Bluing</code></summary> <pre> No output when successful </pre> </details>

`--alias=<alias>`: Spoof with a new controller alias

<details><summary><code>$ sudo bluing spoof --alias='Bluing Alias'</code></summary> <pre> No output when successful </pre> </details>

`plugin` command: Manage plugins

<details><summary><code>$ bluing plugin --help</code></summary> <pre> Usage: bluing plugin [-h | --help] bluing plugin &ltcommand> [&ltargs>...] Options: -h, --help Display this help and quit Commands: list List installed plugins install Install a plugin uninstall Uninstall a plugin run Run a plugin </pre> </details>

Recommended Hardware

Bluetooth adapter

Many features of bluing require access to at least 1 Bluetooth adapter. Although it is possible to use the adapter that comes with the Linux physical machine or make the Linux virtual machine exclusive to an adapter of the host machine, it is still recommended to use an external USB Bluetooth adapter for more stability, such as Parani UD100-G03.

Original micro:bit (optional)

Bluing requires at least 1 original micro:bit when sniffing advertising physical channel PDUs (le --sniff-adv), and it is recommended to use 3 of them at the same time. These micro:bits need to run the dedicated firmware provided by bluing. After connecting the micro:bits to Linux, the pre-built firmware can be flashed by executing the following command:

<pre> bluing --flash-micro-bit </pre>

While less convenient to use than the micro:bit, but more accessible to purchase, more generic NRF51 adapters can be supported as well. Support has been added for the Adafruit Bluefruit LE Friend and the BLE400 boards. To use these, they will need to be flashed using SWD. This tool does not support flashing these devices. Additionally, the tool cannot automatically identify these devices. Instead the --devices option needs to identify the ports connected to computer.

Ubertooth One (optional)

When sniffing and guessing nearby BD_ADDRs (br --sniff-and-guess-bd-addr), bluing requires an Ubertooth One.

FAQ

`rfkill` cannot find hci0

The following is the exception message:

Exception: Can't find the ID of hci0 in rfkill

This exception may be caused by the lack of support for -r and -n option in the old version of rfkill, for example:

<pre> $ cat /etc/os-release | head -n 2 NAME="Ubuntu" VERSION="16.10 (Yakkety Yak)" $ rfkill --version rfkill 0.5-1ubuntu3 (Ubuntu) </pre>

At this time, upgrading rfkill to a newer version can solve the problem, such as:

<pre> $ cat /etc/os-release | head -n 2 PRETTY_NAME="Kali GNU/Linux Rolling" NAME="Kali GNU/Linux" $ rfkill --version rfkill from util-linux 2.38.1 </pre>

Management command `scanend` failed to execute

The following is an error message:

ERROR: Failed to execute management command 'scanend' (code: 11, error: Rejected)

Try restarting the Bluetooth service to solve the problem:

<pre> sudo systemctl restart bluetooth.service </pre>

Awesome

Installation

Usage

br command: Basic Rate system

--inquiry: Discover other nearby BR/EDR controllers

--sdp: Retrieve information from the SDP database of a remote BR/EDR device

--lmp-features: Read LMP features of a remote BR/EDR device

--mon-incoming-conn: Print incoming connection from other nearby BR/EDR devices

--sniff-and-guess-bd-addr: Sniff and guess nearby BD_ADDRs over the air

le command: Low Energy system

--scan: Discover advertising devices nearby

--ll-feature-set: Read LL FeatureSet of a remote LE device

--pairing-feature: Request the pairing feature of a remote LE device

--gatt: Discover GATT Profile hierarchy of a remote LE device

--sniff-adv: Sniff advertising physical channel PDU

android command: Android Bluetooth stack

--collect-btsnoop-log: Collect the btsnoop log being generated

spoof command: Spoof with new local device information

--bd-addr=<BD_ADDR>: Spoof with a new BD_ADDR

--cls-of-dev=<num>: Spoof with a new Class of Device

--host-name=<name>: Spoof with a new host name

--alias=<alias>: Spoof with a new controller alias

plugin command: Manage plugins