How p1sec/qcsuper works
Project type and purpose
• QCSuper is a Python-based command-line tool for capturing mobile radio frames (2G/3G/4G/5G) over Qualcomm Diag protocol and exporting them (PCAP, JSON, DLF, etc.) or sending them live to Wireshark.
• It is organized as a CLI “full-stack” utility with three main layers: Input adapters, Protocol parsing/core, and Output modules.
File structure
• Top level:
• qcsuper.py / setup.py / README.md / docs / LICENSE
• src/:
• __main__.py – entry point
• inputs/ – all Input adapters (ADB, USB modem, TCP, DLF, JSON, HDLC mixin, external ADB binaries)
• protocol/ – definitions of Qualcomm Diag protocol messages, subsystems, GSMTAP encapsulation, log types
• modules/ – output modules (pcap dump, wireshark live, JSON geo, DLF dump, EFS shell, memory dump, decoded SIBs, CLI interactive)
• tests/ – unit tests for core functionality
README for additional insights
• Describes how QCSuper uses “input” to fetch raw Diag frames, the “modules” to process or persist those frames, and external tools like ADB, pyserial, pyusb, Wireshark.
a. Entry Point / CLI
• qcsuper.py / src/__main__.py that parses arguments, discovers Input adapters, loads Protocol layer, loads Modules.
b. Input Adapters Layer
• ADB Adapter (adb_bridge, adb_wsl2)
• USB Modem Adapter (usb_modem_pyserial, pyusb, device detection logic)
• TCP Adapter (tcp_connector)
• File Readers (dlf_read, json_geo_read)
c. Core Protocol Layer
• Diag protocol parser: protocol/messages.py, subsystems.py, efs2.py, gsmtap.py, log_types.py
• Helpers: protocol framing, CRC, message reassembly (SIBs), NAS decryption
d. Output Modules Layer
• pcap_dump / wireshark_live (GSMTAP packet generator)
• json_geo_dump / json_geo_read
• dlf_dump / dlf_read
• memory_dump
• decoded_sibs_dump
• efs_shell (interactive filesystem shell)
• cli interactive REPL
• info module
e. External Services / Tools
• ADB daemon on host <–> device
• USB subsystem / libusb
• Wireshark application
• System shell / su for device mode-switching
• Python libraries: pyserial, pyusb, crcmod, pycrate
Relationships & Data flows
1. User invokes CLI → argument parsing
2. CLI selects one Input adapter → establishes connection to device or file
3. Raw Diag data flows into Core Protocol layer → parsed into high-level messages
4. Core passes messages to enabled Modules
5. Each Module:
• processes messages (encapsulate in GSMTAP, decrypt, reassemble)
• writes output to file, spawns Wireshark, or drives an interactive shell
6. External dependencies:
• ADB or USB subsystem for Input
• Wireshark for live display
Architectural patterns & design principles
• Layered architecture (Input → Core → Modules)
• Plugin pattern (each input or module extends a base class)
• Single responsibility: adapters only fetch raw frames; protocol layer only parses; modules only produce outputs
• Dependency inversion: Core layer defines interfaces; concrete adapters and modules implement them
• Testable components: protocol and modules have unit tests under tests/