This is the starting page of the documentation of this Project. All available documentation and tutorials are linked here. As an entry point to this project we would recommend reading the corresponding publication "5G-Pentest-UE: A Penetration Testing Framework for Identifying 5G System Vulnerabilities" [version of record, preprint (open access)]. There the 5G-Pentest-UE is introduced properly and some background information is given. This documentation on the other hand is especially useful to investigate the usage and implementation details of our 5G-Pentest-UE.
We have also written a basic introduction to mobile networks and the 5G protocol stack which can be found here.
Everything in the documentation is directly written in English or translated from German with the help of DeepL.
- /docs
- Folder that contains all documentation for the 5G-Pentest-UE.
- /openairinterface5g
- This folder only exists after you run the create project script.
- 5G-Pentest-UE -> Open Air Interface open source UE (tag 2025.w20) with the additions that create the framework already added.
- /patches
- Patch folder containing all patch files describing the changes done to the Open Air Interface open source UE (tag 2025.w20) to create the 5G-Pentest-UE.
- .gitignore
- Ignores the openairinterface5g/ folder which is built when running the create project script.
- create_project.sh
- Shell script to download the OAI UE, checkout the correct tag and apply the 5G-Pentest-UE patches to it.
- LICENSE
- License information
- README.md
- Start page of the 5G-Pentest-UE documentation (the file you are reading at the moment).
- Goal of the project
- Idea
- Basic usage of the framework
- Basic Architecture
- Version
- Test Setup
- List of Documentation Pages
- Useful external Links
- FAQ
The goal of this project is to develop a holistic, easy to use and well documented 5G-Pentesting-UE. The framework is provided to simplify the security testing of 5G Systems. The perspective taken here when speaking of security testing is the perspective of a normal UE in the network (with our without valid user credentials). That means that in practice no knowledge of or access to the 5G network is necessary to test it for security flaws. This is useful e.g. when security testing closed source systems, like proprietary private networks.
The basic idea therefore is to allow the user to deviate from the 5G protocol whenever he wants (to test core network and base station implementations) while still taking care of adhering to the protocol wherever needed (to make sure parameters are correct and communication can happen).
At first glance this project might seem like a hacking tool for mobile networks. But in fact its just an extension for the Open Air Interface open source UE that allows to deviate from the OAI UE flow in any place wanted but adhere in every aspect needed. The framing of the framework as a "pentesting tool" exists because it was developed for this use case. But in principle, our framework can also be used for other purposes. For example, you could use it as a generic testing tool to verify new functionalities in your core network or gNB, which at the moment can not be tested by the "normal" OAI UE, because it does not provide the necessary messages.
In this Project and the corresponding publication 5G-Pentest-UE: A Penetration Testing Framework for Identifying 5G System Vulnerabilities no concrete attacks are shown or guides for harming systems are given. We only provide the basis for security testing 5G networks from the perspective of an user end device, by allowing the user of the framework to deviate from the 5G protocol. In fact it is easily possible to use the OAI open source UE and adjust it to send a message you want instead of what it would normally send. This Project and the corresponding publication therefore just provide a framework to skip the annoying but with some basic programming knowledge rather easy task of making the OAI UE do what you want!
As described in the first section the goal of the 5G-Pentest-UE is to enable the user to adhere to the 5G protocol when needed but deviate whenever wanted. To be able to adhere to the 5G protocol we choose the Open Air Interface open source UE as a basis. This allows us to search networks and connect to them. To now be able to deviate from the protocol we changed the OAI code by adding different interfaces to it which allow us to alter data or the control flow.
The easiest way to enable the user of the framework to send everything he wants would be to give him the possibility to manipulate and insert e.g. MAC layer packages while the UE is running. The problem with that is, that e.g. the connection establishment is time critical and therefore the user of the framework would have to retain those timings. Another problem would be that if the user of the framework wants to send a NAS package he would have to handcraft all the layers between the MAC and the NAS layer. This would include e.g. keeping track of sequence numbers or applying encryption and integrity protection if necessary. To do all of this he would basically need to implement the necessary parts of the protocol stack himself which would make the framework relatively useless.
The preceding paragraph shows us that we need different options for the framework user to manipulate the OAI UE. Because of the time critical connection establishment phase we decided to give the user the opportunity to specify the messages he wants the UE to send when establishing a connection in advance inside a configuration file. (Further description in the corresponding section of this documentation) The second functionality we added to our framework is the ability to send any message in the fully connected UE state (after the connection establishment procedure is over). Therefore we added a REST socket to the OAI UE code which waits for messages from the framework user and on receipt passes them to the correct OAI UE function that passes them down the protocol stack and sends them to the network. As discusses above we want to enable sending messages on different protocol layers e.g. encrypted NAS message, MAC message or RRC. Therefore we added different interfaces with different options to the REST socket. This gives the user the ability to specify the message he wants and the corresponding protocol layer + layer options and then make the OAI UE send this message to the network. For usability we also added a message printing feature which allows the user to specify on which layer all of the received/ transmitted messages shall be printed. This is useful to analyse what is happening e.g. in a block-box testing scenario or to create adaptive attacks.
-
Message sending in fully connected state --> REST socket
- NAS
- security protected
- not security protected
- RRC
- over SRB 0
- over SRB 1
- over SRB 2
- PDCP
- over SRB 1
- over SRB 2
- MAC
- SDAP
- NAS
-
Changing Connection Establishment Content
- RRC_SetupRequest
- RRC_SetupComplete
- NAS_RegistrationRequest
- NAS_AuthenticationResponse
- NAS_SecurityModeComplete
- RRC_SecurityModeComplete
- RRC_ReconfigurationComplete
- NAS_RegistrationComplete
- NAS_SessionEstablishmentRequest
- NAS_DeregistrationRequest
-
Printing Messages
-
MAC
- outgoing traffic to PHY
- incoming traffic from PHY
-
RRC
- outgoing traffic to PDCP (SRB1/2) and RLC (SRB0)
- incoming from below PDCP and RLC
- signals from other OAI threads
-
NAS
- outgoing traffic to RRC
- incoming traffic from RRC
- signals from other OAI threads
-
PDCP -> DRB (Data Radio Bearer)
- outgoing traffic to SDAP
- incoming traffic from SDAP
-
Before starting i would recommend to clone this project and execute the create_project.sh script. What this script does is download the OAI UE, checkout the correct tag and apply all changes which create the 5G-Pentest-UE from the normal OAI UE.
To use this framework you need to know how to configure the OAI UE to connect to the system you want to test. That means only if you are able to connect the vanilla OAI UE of tag 2025.w20 to your network you will be able to use this framework.
To test this you can either clone the original OAI repository or just use the openairinterface5g folder of this project (if you don't add the "--sectest-conf-file-path" command line parameter it will behave the same as the vanilla oai UE).
A description on how to setup a local testbed and how to connect the UE can be found in the corresponding documentation pages:
In those tutorials many parts and aspects of the UE build and configuration are described and this might help you connecting to your network. If you still have problems consider the official oai documentation or other sources like this tutorial.
This is basically the same as step 1. If you already used the code provided in this project the step is already done. If you used the original OAI repository you need to do everything you did exactly the same here. (build, configure, connect) For this you can just ignore that the openairinterface5g folder also contains the 5G-Pentest-UE code. It will behave like the plain OAI repository for now.
Here you need to configure the secTest.conf file according to your needs. So change the connection establishment messages (insert the hex code that shall be sent) if you want, enable the message socket (change value to 1 for activation) if you need it and activate the necessary prints (also change value to 1 for activation).
From step 1 you know how to run the OAI UE. To now execute the security tests you just need to add the "--sectest-conf-file-path" command line parameter to your execution command and give it the path to the secTest.conf file as an input. This could look something like this:
sudo ./nr-uesoftmodem <the other parameters> --sectest-conf-file-path ../../../security_testing/config/secTest.conf
Starting the UE will now connect to your network and send the specified connection establishment messages (if specified) and then open up the socket to make the REST API available (if specified). Also the activated prints will be shown in the logs.
If you have activated the socket, you can now send your own messages to the UE (some examples on how to manually craft messages are given here), which it then sends to the network. An easy example would be the following:
curl -X POST http://127.0.0.1:8080/nas_no_sec \
-H "Content-Type: application/json" \
-d '{"message": "7e004119"}'
This curl command sends the message "7e004119" to the core network (nas layer) without applying any ciphering.
As shown in the figure the 5G-Pentest-UE consists of three logical layers. The first containing the OAI UE code and the changes made to it to open the interfaces for our framework. The second containing the code necessary to make use of the added interfaces. And the third to write scripts making use of the provided functionalities. Each of them has separate documentation pages linked below.
The basis of the 5G-Pentest-UE is the OAI UE code. To deeply understand the architecture of the 5G-Pentest-UE and comprehend the decisions made it is useful to have an idea of the OAI ue architecture. Reading this documentation page is not necessary to start using the framework.
Since I did not find the OAI documentation very helpful for the most part, I have summarized my findings in this documentation page. The findings are based on tag 2023.w43 of the OAI repository. But most of the information is still valid. We gained the information given there mainly by studying the 5g specifications and analyzing the OAI code. References to useful OAI documentation pages, an overview of the project structure and of the problems within the project are also given there.
As shown in the figure the first layer of our framework not only contains the plain OAI UE code. The first layer also includes all changes made ot this code. Where which changes were made and how and why is precisely described in this documentation page(s).
The second layer implements the functionality of the 5G-Pentest-UE framework. The 5G-Pentest-UE documentation describes again the idea and the architecture of the 5G-Pentest-UE and how it is included into the OAI code. It also describes the capabilities of the 5G-Pentest-UE and how to utilize them.
** Reading this documentation page will give you a clear understanding on how the 5G-Pentest-UE works and how you can use it. **
Third layer software means software, that does not directly interact with the OAI code but uses the provided capabilities to e.g. automate security testing.
Third layer software for fuzzing or fuzzing related tasks is collected and described in the fuzzing documentation.
Fuzzing means that random data is sent to the various end points of the gNB and the core network. The aim is to achieve random inputs that lead to errors in processing on the receiver side.
Third layer utility scripts that help building pentest scripts third layer utility documentation.
current version uses tag 2025.w20 of the oai open source code!
-
As a base for the development of the 5G-Pentest-UE, the code from tag 2023.w43 of the OAI Repository was cloned and adjusted.
- To update to the second version (2024.w51) i searched for all changes I made to the original OAI code from 2023.w43 and then put them in the same place in the new 2024.w51 version. Since lots of the code changed some adjustments had to be made to my code extensions, but the coarse function structure was the same therefore the mitigation only caused few hard problems.
- If you migrate between OAI-UE versions which are closer together auto merging might work, but for the 2023.w43 to 2024.w51 step it was not possible and caused lots of conflicts which were harder to fix than just doing everything manually.
- From 2024.w51 i then upgraded to 2025.w20 (current version). Also here some merge conflicts occurred but those where rather easy to fix.
- To update to the second version (2024.w51) i searched for all changes I made to the original OAI code from 2023.w43 and then put them in the same place in the new 2024.w51 version. Since lots of the code changed some adjustments had to be made to my code extensions, but the coarse function structure was the same therefore the mitigation only caused few hard problems.
-
For the gNB the code from tag 2023.w43 of the OAI Repository was used for the main part of testing and development. But in principal the gNB has nothing to do with the 5G-Pentest-UE and you can connect to every gNB that works with the currently used OAI-UE version.
-
For the Core Network Version v1.5.1 was used for the main part of testing and development. Same as for the gNB the purpose of this 5G-Pentest-UE is that you can test different Core Networks, therefore you can investigate every Core Network that works with the current OAI-UE version.
- Separate documentation pages
The basis for the development of this 5G-Pentest-UE was a local test setup which can be set up as described in TestSetup. The current descriptions for the UE and gNB are based on tag 2023.w43 of the OAI Repository and therefore are rather old. For the core network the now also outdated version v1.5.1 of the OAI core network was used. But nevertheless useful information e.g. on how to connect the UE to a given gNB can be extracted from there. We will update this section soon to provide an up to date testbed for familiarizing with the 5G-Pentest-UE.
Like a real 5G SA network, this test setup consists of three main components. The UE(s) (end devices such as smartphones), the gNB (radio unit with associated software) and the core network (management of the users and connection to various services).
The base software for the different components comes from the OpenAirInterface open source projects. UE and gNB can be found here:
and the core network here:
-
Test setup
-
Other Information
- Non OAI Tutorial i found
- Mostly similar to the tutorials I have created
- Describes how to setup CN and gNB and connect USRP/5G Wireless Modem Module/COTS UE
- No description for local "no air interface" rfsim setup
For every of the 5 big parts of this project we have added an FAQ in the corresponding main page. The following links directly take you to the FAQ sections:
The questions in the different faq's were not really asked frequently, but questions we asked ourselves when developing the framework.