Metadata-Version: 2.3
Name: scat
Version: 1.3.0
Summary: Signaling Collection and Analysis Tool
Project-URL: Homepage, https://github.com/fgsect/scat
Project-URL: Bug Tracker, https://github.com/fgsect/scat/issues
Author-email: Shinjo Park <peremen@gmail.com>
License: GPL-2.0-or-later
License-File: COPYING
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Requires-Dist: bitstring>=3.1.7
Requires-Dist: pyserial>=3.3
Requires-Dist: pyusb>=1.0.2
Provides-Extra: fastcrc
Requires-Dist: libscrc>=1.8.0; extra == 'fastcrc'
Description-Content-Type: text/markdown

# 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:

* [pyUSB](https://pypi.org/project/pyusb/)
* [pySerial](https://pypi.org/project/pyserial/)

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](https://github.com/fgsect/scat/wiki/Devices) 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](https://github.com/fgsect/scat/wiki/Baseband-Dumps) for details.

## Installation

Install SCAT through pip using:

```
# If you want fast CRC calculation (for Qualcomm and HiSilicon)
$ pip install "scat[fastcrc] @ git+https://github.com/fgsect/scat"

# If you don't want or can't build libscrc
$ pip install git+https://github.com/fgsect/scat
```

Please note that the name SCAT is taken in the PyPI, I will find further solution.

For development purposes, please use `pip install -e .[fastcrc]` or `pip install
-e .` on your checkout directory.
The older `scat.py` is moved to `src/scat/main.py`.

## 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](https://github.com/fgsect/scat/wiki/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)

If one of the following packets are not properly decoded on Samsung baseband
please file an issue with the debug output (`--debug`) attached:

* HSPA UL1 RF Info
* LTE PHY Cell Info
* LTE RRC Serving Cell

SCAT version up to 1.1.0 required specifying the Samsung baseband type manually
using `-m`. As SCAT now autodetects the Samsung baseband type, for SCAT 1.2.0
and above this option is only required when analyzing the raw SDM file without
start response.

### USB
Accessing the baseband diagnostics via USB:

```
$ scat -t qc -u -a 001:010 -i 2
$ scat -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. Please see [Issue #27](https://github.com/fgsect/scat/issues/27#issuecomment-1416233282)
for more information on this.

### Serial
Accessing the baseband diagnostics via serial port:

`$ scat -t qc -s /dev/ttyUSB0`

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

### Dump
Parsing the baseband dump file:

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

### Tested Devices

Please see the [wiki page](https://github.com/fgsect/scat/wiki/Devices).

## 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.
