Tramex project

logo_telecom_ipparis.png

Tramex is a university project conducted in Télécom Paris supervised by Philippe Martins

Tramex is a project that serves the goal of allowing users to analyze and visualize frames in a 4G network.

Tramex is a project derived from :

  • VIGIE
  • Amarisoft web interface

VIGIE

One of the functionalities of the VIGIE software is to analyze the frames of a 2G/3G network. For more information on this topic, please visit https://hal.science/hal-02141173.

Tramex can be seen as an upgrade of the VIGIE software because it allows the user to analyze the frames of a 4G network. Note that Tramex does not have all the functionalities implemented in the VIGIE software.

VIGIE Citation 
@article{oyedapo:hal-02141173,
  TITLE = {{VIGIE : A learning tool for cellular air interfaces (GSM, GPRS, UMTS, WiFi)}},
  AUTHOR = {Oyedapo, Olufemi and Martins, Philippe and Lagrange, Xavier},
  URL = {https://hal.science/hal-02141173},
  JOURNAL = {{The IPSI BgD Transactions on Internet Research}},
  HAL_LOCAL_REFERENCE = {1097},
  VOLUME = {1},
  NUMBER = {2},
  PAGES = {65 - 69},
  YEAR = {2005},
  KEYWORDS = {UMTS},
  HAL_ID = {hal-02141173},
  HAL_VERSION = {v1},
}

Amarisoft web interface

Amarisoft is a software company that provides a 4G LTE software suite. The web interface of Amarisoft lets the user visualize the frames of a 4G network. This tool uses a Websocket to retrieve the frames transmitted within the network.

Tramex

Tramex stands for Trame Exploration. As it is a French project, "Trame" is the French word for "Frame" and "Exploration" can be read either in French or in English.

Based on the Amarisoft software, Tramex uses the same WebSocket method to retrieve the frames transmitted within the network, but it displays them in a more user-friendly manner, similarly to the VIGIE software.

User Guide

This section is meant to help get started with Tramex.

Tramex in a nutshell

Tramex is a 4G network scanner. With Tramex, it is possible to analyze each message of a 4G communication. Those messages are called frames. Tramex allows users to read 4G frames and display the content data such as the channels followed during the communication or the RRC state. Tramex was developed to be accessible from several platforms:

  • in browser mode: the user only needs to go on the tramex website
  • in binary mode: the user needs to download the binary file of tramex from the releases page and run it
  • in crates mode: the user can download and install Tramex with the command: cargo install tramex and then run tramex in the terminal

Get started with Tramex

The Tramex interface is always alike, no matter the mode used. In this section, the various functionalities will be described.

Documentation access

General information is accessible with a click on the Menu button on the left of the top bar then About.

Tramex repository is also accessible from the Tramex interface with a click on the About button on the left of the top bar then Tramex repository.

From the Tramex interface, it is possible to access different documentations:

  • User documentation: Click on the About button on the left of the top bar then User documentation.
  • Tramex code documentation: Click on the About button on the left of the top bar then tramex type.
  • Tramex tools code documentation: Click on the About button on the left of the top bar then tramex-tools types.

Processing modes

In order to analyze frames, Tramex offers two processing modes:

  • File reader: read recorded data from a .log file.
  • Websocket: read real-time data from a server.

The user can choose the processing mode using the buttons Choose ws or file on the top of the left vertical panel.

File reader mode

When using the file reader mode, the user is asked to provide the file to read which can be done in two ways:

  • With the file explorer by clicking on the Open file... button in the left vertical panel.
  • From the files list in the left vertical panel by clicking on the arrow on the left of each directory name until reaching the desired file.

When done with the file, it is possible to close it by clicking on the Close button on the left vertical panel. It is necessary to close the current file to open another one or switch to the websocket mode.

Websocket mode

When using the websocket mode, the user is asked to provide the IP address as well as the port number of the distant server. The information must be provided in the format ws://127.0.0.1:9001 where 127.0.0.1 is the example IP address and 9001 is the example port number in the typebar below the processing mode choosing buttons. Then click on the Connect button.

The connection might take a few moments and if Tramex cannot connect to the server using the websocket, an error message should appear in the Errors panel. From this window, it is possible to read the description of the error, copy it and report it to the tramex repository if necessary.

Analyze frames with Tramex

Regardless of the chosen mode, the display of the frame analysis using Tramex is always the same. Several windows called panels are available and each of them provide specific information.

This section will define the various panels available.

Current message panel

The current message panel contains the information regarding the current frame. The Received events field points out the total number of messages for the current communication. The Current msg index field indicates the frame ID within the analyzed communication. The MessageType field informs the user about the date and time when the message was received, the model layer such as RRC or NAS, the direction of the link, the channel used and the message type. Finally, the content of the message il also displayed.

Logical channels panel

In this panel, it is possible to visualize the channels used to transmit the current message. The panel is divided into three rows and two columns. The first row corresponds to the logical channels, the second row to the transport channels and the third row to the physical channels. The three rows are separated into two, the left hand-side corresponds to a downlink communication whereas the right hand-side corresponds to an uplink communication.

This panel allows the user to easily spot the channels followed for the current message by illuminating the name of the used channels with specific colors. Moreover, the direction of the communication is therefore also highlighted.

The color applied to the name of the channel specifies the channel type:

  • red is for broadcast channels: the message is intended for every UE in the network
  • blue is for shared channels: the message is intended for a group of UEs
  • orange is for dedicated channels: the message is intended for a specific UE alone
  • green is for traffic channels: the message contains data

RRC state panel

The RRC state panel contains the information regarding the current RRC state. Initially, the UE is in idle state until the reception of a RRC Connection Setup message. The UE then switches to a connected state. Similarly, the UE returns to the idle state when a RRC Connection Release message is received.

Proceed through the frames

To browse through the frames, Tramex implemented two buttons located in the top right corner of the screen. With the Next button, it is possible to visualize the following message whereas the Previous button allows the user to return to the previous message.

As a communication coveys a lot of information, Tramex enables the user to choose the data to display. By clicking on the Windows button in the top right corner, it is possible to select the panels to display. If a panel is closed unintentionally, the user can reopen it with the Windows button.

Finally, by clicking on Options in the vertical bar on the left of the screen, the user can select the message types to display or not and change the size of the messages to display. By default, the size is set to a maximum of 1024 messages.

Architecture

Architecture

Development

To start developing on the project, you will first need to install rustup.

Rustup is an installer for the Rust language. It is the recommended way to install Rust, as it manages both the installation and updates of the Rust compiler and tools. It installs the Rust compiler (rustc) and the cargo package manager.

After installing rustup, you can install trunk with :

cargo install trunk

trunk allows you to build, bundle, and optimize your WebAssembly application.

Finally, you can clone the repository with :

git clone git@github.com:tramex/tramex.git

Development

To start the application, you can run the following command in the repository :

# for the web application
trunk serve

# for the desktop application
cargo run

Tips

To check the code style, you can run the following command :

cargo clippy

Debug mode

To run the application in debug mode, you can run the following command :

# this will activate the debug features in tramex and tramex-tools
cargo run --features debug

# more logs
RUST_BACKTRACE=1 RUST_LOG=debug cargo run --features debug

Documentation

You will also need to install mdbook. It is used to automatically generate documentation from the md format to the HTML format, just like this web page. The installation can be done using :

cargo install mdbook

To launch the development server for the documentation, you can run :

# in the tramex repository
mdbook serve docs/

Crates documentation

Latest crates documentation is deployed and available on the local website:

ASN.1

ASN.1 (Abstract Syntax Notation One) is a standard interface description language used for defining data structures that can be serialized and deserialized in a cross-platform way. It is used in telecommunications, cryptography, and other fields.

Download ASN.1 from 3gpp docx

Another solution is to access through the ftp server:

Convert docx to asn1

If the document from 3gpp has asn1 inside, it can be extracted with the following command (using the tool docx-asn1):

# download docx from 3gpp

# install python package docx_asn1
python -m pip install docx_asn1

# use docx_asn1 to convert docx to asn1
python -m docx_asn1 file.docx > output.asn1

# the converted asn1 file is then called output.asn1 and can be found in the current directory

asn1c

For raw decoding, the tool asn1c (https://github.com/vlm/asn1c) can be used to generate C code from the ASN.1 file. The generated code can be used to decode the messages.

types_lte_3gpp

The crate types_lte_3gpp (https://github.com/tramex/types_lte_3gpp/) is used to automatically generate Rust code from ASN.1 files (extracted automatically from docx files created by 3gpp). It is used in the Tramex project to generate the code for the LTE protocol.

CI/CD

Continuous Integration/Continuous Delivery is a conceptual approach that consists in automatizing actions done on applications throughout their life cycle such as tests, integration or delivery in order to accelerate their development.

For more information on the global topic, please refer to : https://about.gitlab.com/topics/ci-cd/

In the Tramex project, CI/CD is used for deployment and tests. There are three files :

The files use the .yml format which is a human-readable serialization language. It is used to translate a data structure from a language to another.

The file gives precisions on the running context and the steps to follow. Each step has a name and corresponds to an action such as command execution.

Deployment file

This file is executed when a push command is performed on the main branch of the GIT repository. It can be ran automatically when trying to push or manually from the Action tab.

The targets of the deployment file are the GitHub Pages. GitHub Pages is a static site hosting service that publishes a website using either HTML, CSS or JavaScript files stored on a GitHub repository. For more information on this topic, please refer to : https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages

The deployment file follows the recommended steps which are the configuration of the pages, the cargo cache and the mdbook, the build, the coverage and finally the deployment.

In the Rust language, the cargo command corresponds to the run command. Once the script is executed, it builds the output in a specific location. In our case, the cargo cache is used for fastest results.

The website is built using the trunk command. It is important not to forget the --release flag in order to optimize the performances and the size of the output code. It is also necessary to use the --public-url flag because Tramex is stored on https://tramex.github.io/tramex domain (so in the folder tramex/ - a relative url). To ease the deployment, all the built files are stored in the dist directory.

The coverage step corresponds to the measurement of the quantity of tested code. The output is automatically saved in a specific location but using the rsync command, the output is relocated in the dist directory as well.

In the Tramex application, it is possible to open documentation from the About section. This documentation appears as a website and is generated from the mdbook. mdbook is static site generator that publishes a website using markdown (.md) files. The mdbook is also set up, then it transforms all .md files located in the docs folder of the repository and output the result in the dist directory (as configured in the configuration file of mdbook (https://github.com/tramex/tramex/blob/main/docs/book.toml).

Finally the whole content of the dist directory is deployed to GitHub Pages.

After the deployment, the accessible URLs are:

Tests file

This file is executed when a push command is performed or when a pull is requested on the main branch of the Git repository. It is used to test code before any new modification is accepted in order to preserve the consistency of the Tramex code through the development.

The Tests file sets up the cargo cache, builds the project and runs the tests implemented in the cargo test command on the whole workspace. The --verbose flag is used to facilitate the debugging in the event of an error.

WASM file

WASM stands for Web ASseMbly.

This file is executed when a push command is performed or when a pull is requested on the main branch of the Git repository. It is used to test code before any new modification is accepted in order to preserve the consistency of the Tramex code through the development. Unlike the Tests file that runs tests on the consistency of the global code, the WASM file specifically tests the build of the wasm rust target (made by trunk).

Typos

typos.yml is a file that is executed when a push command is performed or when a pull is requested on the main branch of the Git repository. It is used to check the spelling of the documentation. It uses the typos command to check the spelling.

If a false positive is detected, it is possible to add the word to the typos.toml file in the root of the repository.

Amarisoft Resources

Amarisoft File Log Format

From the amarisoft documentation: https://https://tech-academy.amarisoft.com/

LTE Software eNodeB and NR Software gNB

PHY

Format

time layer dir ue_id cell rnti frame.subframe channel:short_content long_content

Doc

time Time using the selected format.

layer Layer ([PHY] here).

dir UL (uplink) or DL (downlink).

ue_id eNodeB UE identifier (hexadecimal, unique among all cells).

cell Low 8 bits of the cell identifier (hexadecimal).

rnti Associated RNTI (hexadecimal) or - if none.

frame.subframe Frame number (0-1023) and either subframe number (0-9) for LTE and NB-IoT cells or slot number for NR cells.

channel PHY channel name (e.g. PUSCH, PUCCH, PRACH, SRS, PSS, PBCH, PCFICH, PDSCH, PHICH, PDCCH, EPDCCH, ...).

short_content Single line content.

long_content Hexadecimal dump of the message if phy.max_size > 0.

RLC PDCP NAS

Format

When a message is dumped, the format is:

time layer - ue_id message

When a PDU is dumped (debug level), the format is:

time layer dir ue_id short_content long_content

Doc

time Time using the selected format

layer Layer ([RLC], [PDCP], or [NAS] here).

dir UL (uplink) or DL (downlink).

ue_id eNodeB UE identifier (hexadecimal, unique among all cells).

short_content Single line content.

RLC, PDCP: preceded by the SRB or DRB identifier. long_content NAS: full content of the NAS message if layer.max_size > 0.

MAC RRC

Format

When a message is dumped, the format is:

time layer - ue_id message When a PDU is dumped (debug level), the format is:

time layer dir ue_id short_content long_content

Doc

time Time using the selected format

layer Layer ([MAC] or [RRC] here).

dir UL (uplink) or DL (downlink).

ue_id eNodeB UE identifier (hexadecimal, unique among all cells).

cell_id Primary cell identifier. See cell_id

short_content Single line content.

long_content MAC: hexadecimal dump of the message if layer.max_size > 0. RRC: full ASN.1 content of the RRC message if layer.max_size > 0. long_content MAC, RLC, PDCP: hexadecimal dump of the message if layer.max_size > 0. RRC: full ASN.1 content of the RRC message if layer.max_size > 0.

S1AP NGAP X2AP XnAP M2AP GTP-U

Format

When a message is dumped, the format is:

time layer - message When a PDU is dumped (debug level), the format is:

time layer dir ip_address short_content long_content

Doc

time Time using the selected format.

layer Layer (e.g. [S1AP]).

dir Direction: TO or FROM.

ip_address Source or destination IP address, depending on the dir field.

short_content Single line content.

long_content S1AP, NGAP, X2AP, XnAP, M2AP: full ASN.1 content of the message if layer.max_size > 0. GTPU: hexadecimal dump of the message if layer.max_size > 0.

LTE and NR Core Network

NAS

Format

When a NAS message is dumped, the format is:

time layer - message When a NAS data PDU is dumped (debug level), the format is:

time layer dir MME_UE_ID message_type long_content

Doc

time Time using the selected format

layer Indicate the layer ([NAS] here).

dir UL (uplink) or DL (downlink).

MME_UE_ID MME S1AP UE identifier (hexadecimal).

message_type NAS message type.

long_content Full content of the NAS message if nas.max_size > 0.

IP

Format

When a IP data PDU is dumped (debug level), the format is:

time layer dir short_content long_content

Doc

time Time using the selected format

layer Indicate the layer ([IP] here).

dir UL (uplink) or DL (downlink).

short_content Single line content (at least the IP protocol and the source and destination address).

long_content Optional hexadecimal dump of the PDU if ip.max_size > 0.

S1AP NGAP SBcAP LCSAP GTP-U

Format

When a message is dumped, the format is:

time layer - message When a data PDU is dumped (debug level), the format is:

time layer dir ip_address short_content long_content

Doc

time Time using the selected format.

layer Indicate the layer ([S1AP], [NGAP], [SBCAP], [LCSAP], or [GTPU] here).

dir Direction: TO or FROM.

ip_address source or destination IP address, depending on the dir field.

short_content Single line content.

long_content S1AP, NGAP, SBCAP, LCSAP: full ASN.1 content of the message if layer.max_size > 0. GTPU: hexadecimal dump of the message if layer.max_size > 0.

LTE IMS Server

IMS SIP

Format

time layer dir id message

Doc

time Time using the selected format.

layer Indicate the layer.

dir FROM or TO or - (No direction associated).

id For IMS, represents a unique ID associated with a UE binding. For SIP, represents a unique ID associated to a SIP dialog.

message Log message.

CX RX

Format

time layer dir addr message

Doc

time Time using the selected format.

layer Indicate the layer.

dir FROM or TO or - (No direction associated).

addr Source IP address for incoming messages. Destination IP address for outgoing messages. message Log message.

MEDIA

Format

time layer id dir protocol/media message

Doc

time Time using the selected format.

layer Indicate the layer.

dir FROM or TO or - (No direction associated).

id SIP associated dialog id.

protocol Can be either RTP or RTCP.

media Media type: audio, video or text.

message Log message.

Knowledge base

Copy pasting in the browser

To enable copy-pasting in the browser, you will need to add the --cfg=web_sys_unstable_apis flag. For more information, please refer to the following links :

Coverage

Code coverage made by cargo-llvm-cov is available at https://tramex.github.io/tramex/coverage/

CORS Errors

If the website is running on HTTPS, connections to insecure endpoints (like ws instead of wss) are forbidden because of CORS. There are four options to solve this issue:

  • disable CORS in your browser
  • add an SSL certificate to your ws server
  • use a WS proxy to translate the ws connection to a secure one (wss)
  • use a local WS proxy to remove CORS issue
# example of a local WS proxy (and with a origin header) using npx
npx @n4n5/proxy-ws -t ws://10.0.0.1:9001 -h '{"origin":"toto"}'
# will redirect ws://127.0.0.1:9001 -> ws://10.0.0.1:9001
# cors will not be an issue anymore with the local address 127.0.0.1

Compilation crash

In certain cases, the compilation may heavily use the CPU and slow down the computer. This is due to the cargo process that is using all the available CPU. To solve this issue, you can use the --jobs flag to limit the number of jobs that cargo can run in parallel. Note that on linux, you can use the nproc command to get the number of available CPUs.

cargo build --jobs 10

# or
cargo build -j 10

Another simple solution is to create a ~/.cargo/config.toml file and add the following content:

[build]
jobs = 10

Change file list from url

Using search parameters, you can change the file list from a url. For example, to change the file list from https://example.com/, you can use the following url:

https://tramex.github.io/tramex/?files_url=https://example.com/

Contributors