DiagNG 🎧 The next-generation baseband Diag client software (easily capture air traffic to PCAP - 2G/3G/4G/5G)

DiagNG is a general purpose client purpose for the diagnostic interface of Qualcomm Snapdragon basebands, present on a large part of Android phones and various USB modems.

It can be considered as a sequel for QCSuper, and also takes large inspiration from SCAT. Like these tools, it allows to capture 2G/3G/4G/5G air interface network traces and save them to the GSMTAP/PCAP format, so that you can visualize these in Wireshark.

It is an experimental, Linux-first, open-source, interoperable, brand-new way to connect to baseband USB diagnostic interfaces; whether for pedagogic or security research purposes.

It should eventually support other basebands such as Samsung Exynos processors, and why not other protocols such as AT commands.

Download for Linux 😎 (Flatpak)

Table of contents

• Feature list
• Screenshots
• Roadmap
• Legal
• Development environment setup
  • Run project tests
  • Test decoder using KSV
  • Technical architecture
• Extra resources

Feature list

• Connect a Linux raw SPI port.
• Connect a Linux raw USB interface.
• A sleek GTK 4/Adwaita-based UI.
• SPI and USB connections are safely connected to the Python UI through a privileged Rust daemon, using a Polkit/DBus-based interface to secure privileged actions, to ensure good integration with Flatpak.
• Gather phone-related information through ADB, with shortcuts to enable the QCDM USB interface easily.
• Import DLF or QMDL files in order to enable interoperability with other software.
• Support basic QCDM (Qualcomm diagnostic monitor) log registration.
• Support basic QCDM 2G/3G/4G/5G log conversion to GSMTAP/PCAP (without advanced features such as SIB decoding, reassembly).
• Wireshark plug-in management and automated installation for GSMTAP v3/5G RRC decoding (taken from SCAT).
• Flatpak packaging for good integration to the Linux desktop.

Screenshots

Roadmap

Planned for the next stable releases:

• Support for decoding IP/data packets, as present in QCSuper
• Complete QCDM to GSMTAP conversion with SIB decoding support, as present in QCSuper
• Complete QCDM to GSMTAP conversion with RRC frame reassembly support, as present in QCSuper
• QA QCDM to GSMTAP conversion with good testing protocols over real devices

Needed to cover feature gap with other softs:

• Provide good CLI functionality similar to QCSuper?
• Complete QCDM support with EFS shell decoding support, as present in QCSuper?
• Decode more QCDM logs?

Good idea to add value:

• Provide AT commands support, USIM-related commands support, QMI communication, etc.?

Wished:

• Allow to decode and register other QCDM non-OTA logs, like in SCAT?
• Support Exynos, Mediatek, HiSilicon, etc. basebands like SCAT?
• Provide more UI visualizations for QCDM features?
• Write unit tests?
• Export Kaitai Struct definitions to separate repositories/libraries?
• Take external contributions for protocolar support?
• Provide AppImage packaging?
• Provide an on-device implant to gather logs on-device, similar to QCSuper, MobileInsight, SnoopSnitch or NSG?
• Eventual Windows/macOS port?

Legal

DiagNG is released under the GPL v3 license.

DiagNG is developed with the ground of allowing the interoperability of Linux systems with baseband diagnostic interfaces, as well as of conducting security research.

P1 Security being based in France, read the following extra mentions for more detailed context on the purpose of this software:

DiagNG est un logiciel développé à des fins de sécurité informatique et de recherche, au titre de l'article L122-6-1 du Code de la propriété intellectuelle modifié par l'article 25 de la Loi n° 2013-1168 du 18 décembre 2013 relative à la programmation militaire pour les années 2014 à 2019 et portant diverses dispositions concernant la défense et la sécurité nationale.

DiagNG est également développé en connaissance de l'avis du Conseil d'État, 10ème et 9ème sous-sections réunies, 16/07/2008, 301843, rendu sur saisine de l'APRIL, qui stipule que l'article L122-6-1 du Code de la propriété intellectuelle instaure bien une exception de décompilation destinée à permettre le développement de logiciels libres.

Development environment setup

Dependencies on Ubuntu 26.04 LTS:

sudo apt install libgirepository-2.0-dev libadwaita-1-dev \
    gir1.2-modemmanager-1.0 gir1.2-adw-1 gir1.2-gtk-4.0 \
    gir1.2-gtksource-5 libgtksourceview-5-dev \
    python3-dev blueprint-compiler cargo rustc polkitd \
    google-android-platform-tools-installer git wireshark

sudo snap install --classic astral-uv

Dependencies on Archlinux:

sudo pacman -S uv blueprint-compiler python-gobject \
    gtksourceview5 libadwaita libmm-glib rust polkit \
    android-tools git wireshark-qt

Dependencies on Fedora:

sudo dnf install uv glib2-devel libadwaita-devel gtk4-devel \
    gobject-introspection-devel python3-gobject-devel \
    python3-devel cairo-devel @development-tools \
    modemmanager-glib-devel android-tools rustc cargo \
    gtksourceview5-devel polkit git wireshark

Then:

cd
git clone git@github.com:P1sec/DiagNG.git diagng

cd diagng
# Download Python modules and initialize virtualenv (creates ".venv",
# call "source .venv/bin/activate" to set up)
uv sync
# Add direct commands to $PATH, so that the commands are callable
# system-wide (creates a symlink to the source in "~/.local/bin")
uv tool install -e .

sudo install -Dm644 diagmond/share/dbus-1/system.d/com.p1security.diagmond.conf \
    /etc/dbus-1/system.d/com.p1security.diagmond.conf

sudo install -Dm644 diagmond/share/polkit-1/actions/* -t /etc/polkit-1/actions/

install -Dm644 src/diagng/ui/assets/share/icons/hicolor/scalable/apps/com.p1security.diagng.svg \
    ~/.local/share/icons/com.p1security.diagng.svg

install -Dm644 src/diagng/ui/assets/share/applications/com.p1security.diagng.desktop \
    ~/.local/share/applications/com.p1security.diagng.desktop

# In one tab:
diagmond

# In another tab:
diagng

Run project tests

uv run pytest

Test decoder using KSV

Example command for using kaitai_struct_visualizer:

sudo gem install kaitai-struct-visualizer

ksv \
  ~/qcsuper-dlf-samples/sample_name.dlf \
  ~/diagng/struct/qualcomm/dlf/dlf_file.ksy

Technical architecture

DiagNG is meant to be split into two components:

• com.p1security.diagng: The main, single-instance Python 3/GTK 4/libadwaita 1.8+ front process holding a GUI, providing D-Bus session bus IPC on /com/p1security/diagng (including the com.p1security.diagmetad D-Bus interface which provides info about Linux ModemManager communication, UDev data acquisition)
  • Diag frame decoding itself is done in the Python daemon, using Kaitai struct
• com.p1security.diagmond: The background, privileged (runs on system bus), single-instance Rust/async process handling raw USB/SPI, USB, Diag frame acquisition, providing IPC
  • Uses tokio-serial + zbus + nusb

This repository hence contains a modular GObject + GTK4 GUI app (leveraging GObject data models and signals, plus a decoupled UI-daemon architecture leveraging Polkit, so that we can perform serial port acquisition in a privileged fashion, and the UI and Diag decoder can be unprivileged/sandboxed too), allowing to control and manage interferences with the serial Diag port system-wide.

Various information is also put in a GObject model and display it using the Adwaita UI.

It also interfaces with ModemManager, Wireshark, UDev, etc.

Extra resources

• Related tools
  • SCAT (CLI, Python, multi-vendor)
  • QCSuper (CLI, Python)
  • MobileInsight (heavier framework, mixed C++/Python)
• Protocol documentation
  • GSMTAP v2 format
  • GSMTAP v3 format
  • PCAP format definition - IETF
  • Kaitai structure format
  • Qualcomm Diag - Osmocom
• Research
  • Reverse engineering a Qualcomm baseband - 28C3 - Berlin, Guillaume Delugré, 2011
  • Exploiting Qualcomm WLAN And Modem Over-The-Air - Black Hat USA - Xiling Gong, Peter Pi, 2019
  • QCSuper on Google Scholar