Application Note

Testing with CoreScope

CoreScope combines the gNodeB and UE components of srsRAN for the purposes of exercising 5G core networks, without the need for RF-hardware. It does this by emulating control and data RAN traffic identical to that generated by real UE and eNodeB/gNodeB devices. CoreScope is 5G SA ready.

It's main use-cases are to:

• Exercise core network functionality and analyze key performance metrics to quickly detect and resolve problems.
• Rapidly identify network misconfigurations and highlight bottlenecks.
• Test for security vulnerabilities and easily integrate CoreScope with third-party tools using our non-proprietary logging and packet capture outputs.

Introduction

In this application note we will connect CoreScope to a 3rd-party 5G core, namely Open5GS, to exercise and test the core. We will do this without RF-hardware, and use Open5GS in a virtual environment. All of this will be done locally, on one machine.

Open5GS

Details on how to download and install this VM and Open5GS can be found here.

Open5GS runs on a virtul machine through VirtualBox. Some configuration of the VM and VirtualBox is required such as setting up the network adapter, and ensuring TUN devices are configured.

Testing the Core

To exercise the core network using CoreScope, Open5GS needs to be running on the VM, CoreScope should then be run from your local machine. It will automatically connect to the core. Once the connection has been made tests can be run to exercise the core.

Running CoreScope

First make sure the core is running. If not, CoreScope will be unable to register.

To run CoreScope, navigate to the build folder and run CoreScope with the following command:

cd corescope/build/corescope/src 
sudo ./corescope 

CoreScope should now run and automatically connect to the core. You should see something similar to the following in the console running CoreScope:

=== CoreScope started ===
API server running on port 8000
PDU Session Establishment successful. IP: 10.45.0.3

Note:

If you run CoreScope and receive error messages, check that the IPs, the PLMN and the TAC are consistent between the core and CoreScope. If needs be, edit the config files and restart both the core and CoreScope.

Example Test Application

To quickly test the connection, CoreScope comes with a python test application called corescope-tester.py. This aims to demonstrate a simple test, by adding a UE, and pinging the core.

First, locate the file where it is stored in the corescope folder:

cd examples/core-scope-api-client

Now configure the application so that is uses the correct IP for the core. This is done on line 13 of the source code, it should look like the following:

client = Client(base_url="http://127.0.0.1:8000", timeout=5)

Configuring and adding a UE

Exemplary, we add a UE in the lines 21-93 of the corescope-tester.py. We create the UE arguments, that configure a UE. The UE arguments use usim, nas_5g, gw, pcap, and log arguments. In most cases, we use the default parameters, that are set via the API description. However, in special cases, those parameters must be adjusted.

1. We configure the USIM parameters. Those parameters must be match the parameters set in the network's UDM function.

# usim args
ue_args.usim = dto_ue_args.DtoUeUsimArgs(
    # mode: Union[Unset, str] = "soft"
    # algo: Union[Unset, str] = "mil"
    # using_op: Union[Unset, bool] = False
    # op: Union[Unset, str] = ""
    # opc: Union[Unset, str] = "63bfa50ee6523365ff14c1f45f88737d"
    # imsi: Union[Unset, str] = "001010123456780"
    # imei: Union[Unset, str] = "353490069873310"
    # k: Union[Unset, str] = "00112233445566778899aabbccddeeff"
    # pin: Union[Unset, str] = ""
    # reader: Union[Unset, str] = ""
)

2. We set the NAS 5G parameters. The important parameter is the APN which must match with the configuration of the core network.

# nas args
ue_args.nas_5g = dto_ue_args.DtoUeNas5gArgs(
    # force_imsi_attach: Union[Unset, bool] = False
    # eia: Union[Unset, str] = "1, 2"
    # eea: Union[Unset, str] = "0, 1, 2"
    # pdu_sessions: Union[Unset, List[DtoUeNasPduSessionArgs]] = UNSET
    # ia5g: Union[Unset, str] = "1, 2"
    # ea5g: Union[Unset, str] = "0, 1, 2"
)
ue_args.nas_5g.pdu_sessions = list()

pdu_session_1 = dto_ue_nas_pdu_session_args.DtoUeNasPduSessionArgs()
pdu_session_1.apn_name = "internet"
ue_args.nas_5g.pdu_sessions.append(pdu_session_1)

3. The GW configuration allows you to set the local configuration of the TUN/TAP interface, e.g., the name of the interface and subnet mask.

# gw args
ue_args.gw = dto_ue_args.DtoUeGwArgs(
    # tun_dev_name=ue_tun_interface,
    # netns=ue_tun_interface,
    # tun_dev_netmask="255.255.255.0"
)

4. The pcap parameters allow you to write a pcap on the NAS layer (decrypted). Logs allow you to write a log file specific for each UE. If you use the same filename which is set in the corescope.conf all logs are written to the same file.

# pcap args
ue_args.pcap = dto_ue_args.DtoUePcapArgs(
    # enable=False,
    # filename=""
)
# log args
ue_args.log = dto_ue_args.DtoUeLogArgs()
ue_args.log.filename = "/tmp/corescope.log"

5. The UE is added via the API call, like the following.

add_ue_data: Response[dto_ue_id.DtoUeId] = create_ue.sync_detailed(
    client=client, gnb_id=0, json_body=ue_args)

Once, you have configured the UE parameters matching your needs, you can run the tester script.

Running the tester script

The tester can now be run:

./corescope-tester.py 

This application is an examplary usage of the CoreScope API. It adds a single UE to corescope, starts the registration procedure and subsequently performs a ping using the added tun/tap interface.

You should see the following in the console once the test has run successfully:

Adding UE
Added UE with ue_id 0
Switching UE on
Sending data over tun interface...
PING 10.45.0.1 (10.45.0.1) from 10.45.0.3 tun_ue_0: 56(84) bytes of data.
64 bytes from 10.45.0.1: icmp_seq=1 ttl=64 time=0.541 ms
64 bytes from 10.45.0.1: icmp_seq=2 ttl=64 time=0.601 ms
64 bytes from 10.45.0.1: icmp_seq=3 ttl=64 time=0.460 ms

--- 10.45.0.1 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2031ms
rtt min/avg/max/mdev = 0.460/0.534/0.601/0.057 ms
Sleeping for a while

CoreScope will automatically add a TUN/TAP interface for each successfully connected UE, which then allows it to send traffic to the network.