SCAT: Signaling Collection and Analysis Tool

This application parses diagnostic messages of Qualcomm and Samsung baseband through USB, and generates a stream of GSMTAP packet containing cellular control plane messages.

Requirements

On PC

Only tested in Linux, mostly various versions of Ubuntu. Python 3 is a minimum requirement, and the following external modules are required:

To properly decode GSMTAP packets generated by SCAT, Wireshark 2.6.0 or above is required. For older Wireshark releases, we are providing a Wireshark Lua plugin to extend the GSMTAP dissector. GSMTAP definition used by SCAT is based on libosmocore 0.11.0. Note that SCAT itself is not depending on the libosmocore.

Smartphones

Cellular device must expost the diagnostic port via USB. This is largely device-dependent and we can not give generic solution for all devices. Search the Internet with keyword (your device name) qpst to get the method of exposing the diagnostic port for Qualcomm-based smartphones. You may refer to the wiki page for instructions on how to opening the diagnostic port through USB on some devices.

If your smartphone does not expose the diagnostic port via USB, you can try using the baseband dump features existing in some smartphones. Follow the wiki page for details.

Usage

While we recommend using USB directly to access the diagnostics port, if your smartphone's or cellular module's diagnostic port is accessible via serial port, using it is also possible. The qcserial and option kernel module do not have the information of diagnostic port of all Qualcomm-based smartphones and cellular modules, and no such module exist for Samsung-based smartphones.

By default, SCAT will send packets to 127.0.0.1, control plane packets to UDP port 4729 as GSMTAP, user plane packets to UDP port 47290 as IP.

Exit the application with Ctrl+C.

Please see the wiki page for advanced options.

Common Options

-t option specifies the type of baseband. Following options are available:

-t qc: Qualcomm
-t sec: Samsung
-t hisi: HiSilicon (experimental, only baseband dump is supported)

For Samsung devices, you need to manually supply the baseband model through -m option like this example:

$ scat.py -t sec -m e333

Available model types are following:

-m cmc221s: CMC221S, used in very early Samsung LTE modem/smartphone.
-m e303: Exynos modem 303.
-m e333: Exynos modem 333.
-m e5123: Exynos modem 5123.
-m e5300: Exynos modem 5300.
For modems not listed in here, try -m e333 or -m e5123 based on the relative age of the device.

USB

Accessing the baseband diagnostics via USB:

$ scat.py -t qc -u -a 001:010 -i 2
$ scat.py -t sec -u -a 001:010 -i 2

Although there are small heuristic to determine the connected device, it is recommended to explicitly specify the USB device address and interface number of diagnostics node. -a 001:010 specifies the address, which follows the same syntax visible in lsusb command. -i 2 specifies the interface number of the diagnostic node, which is again device specific.

Newer Samsung devices require a correct magic number to be supplied to start the diagnostic session through USB. This could be specified by --start-magic option.

Serial

Accessing the baseband diagnostics via serial port:

$ scat.py -t qc -s /dev/ttyUSB0

Replace /dev/ttyUSB0 to what is your diagnostic device.

Dump

Parsing the baseband dump file:

$ scat.py -t qc -d test.qmdl
$ scat.py -t sec -d test.sdm
$ scat.py -t hisi -d test.lpd

Tested Devices

Please see the wiki page.

Known Bugs

Issues related to exposing the diagnostics port via USB is out of scope.

On certain Qualcomm devices, after exiting and launching the application for more than once, initialization eventually hangs and no messages are appearing. Root cause still in investigation. Solution: reboot the smartphone.

License

SCAT is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

References

We are kindly asking any academic works utilizing and/or incorporating this software to cite one of these references listed below:

Byeongdo Hong, Shinjo Park, Hongil Kim, Dongkwan Kim, Hyunwook Hong, Hyunwoo Choi, Jean-Pierre Seifert, Sung-Ju Lee, Yongdae Kim. Peeking over the Cellular Walled Gardens - A Method for Closed Network Diagnosis -. IEEE Transactions on Mobile Computing, February 2018.

Thanks to Christian Oschwald and Willem Hengeveld from GSMK for their support on Samsung SDM parser.

acoderhz / scat