QCSuper

QCSuper is a tool communicating with Qualcomm-based phones and modems, allowing to capture raw 2G/3G/4G (and for certain models 5G) radio frames, among other things.

It will allow you to generate PCAP captures of it using either a rooted Android phone, an USB dongle or an existing capture in another format.

After having installed it, you can plug your rooted phone in USB and using it, with a compatible device, is as simple as:

qcsuper --adb --wireshark-live

Or, if you have manually enabled exposing a Diag port over your phone (the corresponding procedure may vary depending on your phone modem and manufacturer, see below for more explanations), or if you have plugged a mobile broadband dongle:

qcsuper --usb-modem auto --wireshark-live

It uses the Qualcomm Diag protocol, also called QCDM or DM (Diagnostic Monitor) in order to communicate with your phone's baseband.

You are willing to report that your device works or does not work? You can open a Github issue.

Table of contents

• Installation
  • Linux installation (PIP)
  • Linux installation (UV)
  • Windows installation
• Supported protocols
• Usage notice

Annexes:

• Using QCSuper with an USB modem
• Supported devices
• Related tools using the Diag protocol

Blog post/demo: Presenting QCSuper: a tool for capturing your 2G/3G/4G air traffic on Qualcomm-based phones

More documentation:

• The Diag protocol
• QCSuper architecture

Installation

QCSuper was lately tested and developed on Ubuntu LTS 22.04+ and also has been used over Windows 11. It depends on a few Python modules. It is advised to use Linux for better compatibility.

To use it, your phone must be rooted or expose a diag service port over USB. In order to check for compatibility with your phone, look up the phone's model on a site like GSMArena and check whether it has a Qualcomm processor.

In order to open PCAP files produced by QCSuper, you can use any Wireshark 2.x - 4.x for 2G/3G frames, but you need at least Wireshark 2.5.x for 4G frames (and 2.6.x for individual NAS messages decrypted out of 4G frames). Ubuntu currently provides a recent enough build for all versions.

Decoding 5G frames was tested under Wireshark 3.6.x and above and will be done through automatically installing a Wireshark Lua plug-in (in %APPDATA%\Wireshark\plugins under Windows or in ~/.local/lib/wireshark/plugins under Linux and macOS), which can be avoided through setting the DONT_INSTALL_WIRESHARK_PLUGIN=1 environment variable if you are willing to avoid this.

Linux installation (PIP)

In order to install the stable version of QCSuper system-wide from PyPI, you can run these commands:

# Install dependencies
sudo apt install python3-pip wireshark

# Install stable QCSuper system-wide
sudo pip3 install --upgrade qcsuper --break-system-packages

Then, you can just type qcsuper in your terminal to run QCSuper.

In order to install the development version in a specific folder, open a terminal and type the following:

# Download QCSuper
git clone https://github.com/P1sec/qcsuper
cd qcsuper

# Install dependencies
sudo apt install python3-pip wireshark
sudo pip3 install --upgrade . --break-system-packages

Then, run QCSuper from the qcsuper/ directory, using the ./qcsuper.py command in the terminal.

Linux installation (UV)

On Linux, you can to install QCSuper using the uv package manager which is a modern alternative to PIP.

First, run one of these commands in your terminal in order to install uv:

sudo snap install --classic astral-uv # On Ubuntu
sudo dnf install -y uv # On Fedora
sudo pacman -S uv # On Archlinux, Manjaro
curl -LsSf https://astral.sh/uv/install.sh | sh # On Debian and others

Then, run this to install the latest stable version:

uv tool install qcsuper

Alternatively, you can install the latest development version using this command:

uv tool install git+https://github.com/P1sec/qcsuper

You can then just type this into your terminal:

qcsuper

However, if you need to run qcsuper as root, for example because you are reading data from a modem device, qcsuper may not be in $PATH when using uv with sudo so this may require to do something such as:

sudo env "PATH=$PATH" qcsuper

If you wish to participate to the development of the tool, you can use these commands in order to download the source, then create symbolic links to QCSuper into ~/.local/bin towards the source directory:

git clone https://github.com/P1sec/qcsuper
cd qcsuper
uv sync # Create .venv in the current directory
uv tool install -e . # Create symlinks into ~/.local/bin

Windows installation

QCSuper can run on Windows, but you should beforehand ensure that Google's ADB prompt correctly runs on your machine with your device, and you should as well manually create libusb-win32 filters (through the utility accessible in the Start Menu after installing it) in the case where your device directly needs to connect to the Diag port over pseudo-serial USB.

(Please note that if you mode-switch your device, the associated USB PID/VID may change and it may require to redo driver associations in the libusb-win32 filter creation utility - and/or in the Windows peripherial devices manager depending on the case)

On Windows, you may need (in addition to Google's ADB kernel drivers) to download and install your phone's USB drivers from your phone model (this may include generic Qualcomm USB drivers). Please search for your phone's model + "USB driver" or "ADB driver" on Google for instructions.

Then, you need to ensure that you can reach your device using adb. You can find a tutorial on how to download and setup adb here. The adb.exe shell (or whatever executable path you use, a copy of the ADB executable is present in the qcsuper/inputs/external/adb folder of QCSuper) command must display a prompt to continue.

Then, follow these links (the tool has been tested lately on Windows 11 - it is not guaranteed to work on Windows 7) in order to:

• Install Python 3.12 (Windows 7 version: Python 3.7) or more recent (be sure to check options to include it into PATH, install it for all users and install pip)
• Install Wireshark 4.2 (Windows 7 version: Install Wireshark 3.6) or more recent
• Install libusb-win32 1.2.7.3 (Windows 7 version: libusb-win32 1.2.3.7) or more recent
• Restart your command prompt/terminal in order to ensure that the %PATH% system variable has been updated.
• Download and extract QCSuper

To install the required Python modules, open your command prompt and type:

pip3 install --upgrade pyserial pyusb crcmod pycrate https://github.com/pyocd/libusb-package/archive/master.zip

Still in your command prompt, move to the directory containing QCSuper using the cd command. You can then execute commands (which should start with py qcsuper.py or py3 qcsuper.py if you installed Python 3 from the online installer, or python3.exe .\qcsuper.py if you installed it from the Windows Store).

As noted above, it is possible that you have to add a libusb-win32 filter through the utility available in the Start Menu in order to ensure that the interface corresponding to the Diag port is visible by QCSuper on the mode-switched device (a first failed attempt to run the tool using the --adb flag should trigger a mode-switch if the ADB driver is working and the device is correctly rooted).

<p align="center"> <img src="https://raw.githubusercontent.com/P1sec/QCSuper/master/docs/Adding%20libusb-win32%20filter.png?raw=true" alt="Screenshot of adding a libusb-win32 filter for the Diag port of a Mi phone"> </p>

Supported protocols

QCSuper supports capturing a handful of mobile radio protocols. These protocols are put after a GSMTAP header, a standard header (encapsulated into UDP/IP) permitting to identify the protocol, and GSMTAP packets are put into a PCAP file that is fully analyzable using Wireshark.

2G/3G/4G protocols can be broken into a few "layers": layer 1 is about the digital radio modulation and multiplexing, layer 2 handles stuff like fragmentation and acknowledgement, layer 3 is the proper signalling or user data.

QCSuper allows you most often to capture on layer 3, as it is the most pratical to analyze using Wireshark, and is what the Diag protocol provide