{"id":49382119,"url":"https://github.com/5GSEC/MobiFlow-Auditor","last_synced_at":"2026-05-14T17:01:13.024Z","repository":{"id":219350012,"uuid":"741356486","full_name":"5GSEC/MobiFlow-Auditor","owner":"5GSEC","description":"An O-RAN compliant xApp supporting fine-grained and security-aware statistics monitoring over 5G RAN and UEs","archived":false,"fork":false,"pushed_at":"2025-07-22T15:40:48.000Z","size":1176,"stargazers_count":6,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-03T11:11:24.734Z","etag":null,"topics":["5g","o-ran","security","visibility","xapp"],"latest_commit_sha":null,"homepage":"https://www.5gsec.com/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/5GSEC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-10T08:20:40.000Z","updated_at":"2026-01-30T13:13:14.000Z","dependencies_parsed_at":"2024-02-05T20:04:14.466Z","dependency_job_id":"99116944-f444-4f8b-a2dc-e866410410e8","html_url":"https://github.com/5GSEC/MobiFlow-Auditor","commit_stats":null,"previous_names":["5gsec/mobiflow-auditor"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/5GSEC/MobiFlow-Auditor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiFlow-Auditor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiFlow-Auditor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiFlow-Auditor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiFlow-Auditor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5GSEC","download_url":"https://codeload.github.com/5GSEC/MobiFlow-Auditor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiFlow-Auditor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33034788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["5g","o-ran","security","visibility","xapp"],"created_at":"2026-04-28T06:00:28.381Z","updated_at":"2026-05-14T17:01:13.018Z","avatar_url":"https://github.com/5GSEC.png","language":"C","funding_links":[],"categories":["AI \u0026 Machine Learning"],"sub_categories":["O-RAN AI/ML"],"readme":"\u003c!--\nSPDX-FileCopyrightText: Copyright 2004-present Facebook. All Rights Reserved.\nSPDX-FileCopyrightText: 2019-present Open Networking Foundation \u003cinfo@opennetworking.org\u003e\n\nSPDX-License-Identifier: Apache-2.0\n--\u003e\n\n# MobiFlow-Auditor-xApp\n\nMobiFlow Auditor is an O-RAN compliant xApp aiming to support ***fine-grained and security-aware statistics monitoring over the RAN data plane***, which is not solved by the default O-RAN standard and service models. We abstract such telemetry streams as **MobiFlow**, a novel security audit trail for holding mobile devices accountable during the link and session setup protocols as they interact with the base station, and interval statistics generated for tracking large-scale patterns of abuse against the base station.\n\nMobiFlow Auditor can drive various analyses. For example, it can drive expert system analysis with [MobiExpert](https://github.com/5GSEC/MobieXpert). MobiExpert xApp allows network operators to program stateful production-based IDS rules for detecting a wide range of cellular L3 attacks. It features the Production-Based Expert System Toolset ([P-BEST](https://ieeexplore.ieee.org/document/766911)) language. MobiFlow Auditor can also drive AI / ML-based analytics, such as [MobiWatch](https://github.com/5GSEC/MobiWatch) that uses unsupervised deep learning to detect layer-3 anomalies from 5G network traffic.\n\nTo learn more about the format and structure of MobiFlow, please refer to our papers:\n\n- [A Fine-Grained Telemetry Stream for Security Services in 5G Open Radio Access Networks](https://dl.acm.org/doi/abs/10.1145/3565474.3569070) (EmergingWireless'22)\n- [5G-Spector: An O-RAN Compliant Layer-3 Cellular Attack Detection Service](https://web.cse.ohio-state.edu/~wen.423/papers/5G-Spector-NDSS24.pdf) (NDSS'24)\n\nMobiFlow Auditor's current implementation is dedicated for the [OSC RIC](https://wiki.o-ran-sc.org/display/ORAN). It is developed based on the [OSC RIC's python SDK](https://github.com/o-ran-sc/ric-plt-xapp-frame-py). Our running example below shows how to setup a 5G network based on the [OpenAirInterface5G](https://gitlab.eurecom.fr/oai/openairinterface5g/) project.\n\n\nWe also have an old version at branch `main` implemented for the [ONOS RIC](https://docs.onosproject.org/v0.6.0/onos-cli/docs/cli/onos_ric/) on [SD-RAN](https://docs.sd-ran.org/master/index.html). It was used as part of the [5G-Spector](https://github.com/5GSEC/5G-Spector) artifact but not recommended any more since the ONOS RIC xApp python SDK is no longer being maintained.\n\n\n## MobiFlow Structure\n\nThe current MobiFlow message definition is defined in [mobiflow.py](./src/mobiflow/mobiflow.py#L60). It mainly collects (1) the fine-grained layer-3 (RRC and NAS) state transition information of UEs at the message level; (2) the aggregated flow-based statistics from the base stations. The MobiFlow telemetry report process is based on the E2SM-KPM (v2.0) service model (SM). \n\nMobiFlow Auditor xApp requires O-RAN compliant RAN nodes to collect and report corresponding data. We have augmented the OpenAirInterface project with MobiFlow telemetry support at [https://github.com/onehouwong/OAI-5G](https://github.com/5GSEC/OAI-5G) branch `v2.1.0.secsm.osc`.\n\n\n\n## Prerequisite\n\n### Local Docker registry\n\nMobiFlow-Auditor is built from source as a local Docker container. Refer to the official tutorial (https://docs.docker.com/engine/install/) to install and set up the Docker environment.\n\nCreate a local docker registry to host docker images: \n\n```\nsudo docker run -d -p 5000:5000 --restart=always --name registry registry:2\n```\n\n### OSC nearRT RIC\n\nBefore deploying the xApp, make sure the OSC nRT-RIC is deployed by following this [tutorial](https://github.com/5GSEC/5G-Spector/wiki/O%E2%80%90RAN-SC-RIC-Deployment-Guide#deploy-the-osc-near-rt-ric).\n\n\n## Build the MobiFlow-Auditor xApp\n\nSimply run our build script:\n\n```\n./build.sh\n```\n\nAfter a successful build, the xApp will be compiled as a standalone Docker container.\n\n```\n$ docker images\nREPOSITORY                         TAG       IMAGE ID       CREATED          SIZE\nlocalhost:5000/mobiflow-auditor    0.0.1     c6312eb0d32e   2 minutes ago    237M\n```\n\n\n## Install / Uninstall the xApp\n\nFirst, onboard the xApp. You need to set up the proper environment with the `dms_cli` tool. Follow the instructions [here](https://github.com/5GSEC/5G-Spector/wiki/O%E2%80%90RAN-SC-RIC-Deployment-Guide) to install the tool. \n\nThen execute the following to onboard the xApp:\n\n```\ncd init\nsudo -E dms_cli onboard --config_file_path=config-file.json --shcema_file_path=schema.json\n```\n\nThen, simply run the script to deploy the xApp under the `ricxapp` K8S namespace in the nRT-RIC.\n\n```\ncd ..\n./deploy.sh\n```\n\nMake sure the xApp is up and running:\n\n```\n$ kubectl get pods -n ricxapp\nNAME                                READY   STATUS    RESTARTS   AGE\nmobiflow-auditor-68d598d7fb-vhlqw   1/1     Running   0          4m10s\n...\n```\n\nIf you wish to undeploy the MobiFlow-Auditor xApp from Kubernetes, run:\n\n```\n./undeploy.sh\n```\n\n## Running Example\n\nThe below running example shows how to use the MobiFlow Auditor xApp to capture security telemetry from a live 5G network and stores the telemetry into the SDL database.\n\n### Step 1. Deploy the OSC nRT RIC\n\nDeploy the OSC nRT-RIC and make sure it is running properly following this [tutorial](https://github.com/5GSEC/5G-Spector/wiki/O%E2%80%90RAN-SC-RIC-Deployment-Guide#deploy-the-osc-near-rt-ric)\n\n### Step 2. Deploy the OAI gNB\n\nNext, deploy the OAI gNB that connects to the nRT-RIC through the E2 interface. You can refer to our [tutorial](https://github.com/5GSEC/5G-Spector/wiki/O%E2%80%90RAN-SC-RIC-Deployment-Guide#connect-oai-gnb-to-osc-ric) to deploy the OAI gNB which is extended with the E2 agent we have implemented. Ensure the gNB is up and connected to the RIC.\nMake sure the gNB's E2 interface IP points to the nRT-RIC's E2T pod.\n\n### Step 3. Run the MobiFlow Auditor xApp\n\nRun the MobiFlow Auditor xApp (assuming the image has been built):\n\n```\n./deploy.sh\n```\n\nThe xApp will recognize the gNB and starts a subscription with it through the E2SM KPM service model.\n\n### Step 4. Start the OAI nrUE to generate traffic\n\nFinally, run the OAI nrUE (or a commercial UE) to attach to the gNB and generate 5G traffic. We have provided instructions on how to run the OAI UE at this [link](https://github.com/5GSEC/5G-Spector/wiki/O%E2%80%90RAN-SC-RIC-Deployment-Guide#run-oai-ue).\n\n### Step 5. Examine the MobiFlow data\n\nBy running the MobiFlow Auditor on the RIC along with an OAI gNB and nrUE, MobiFlow Auditor will generate and store MobiFlow telemetry. You can check the run-time logs with:\n\n```\n./log.sh\n```\n\nExample log entries from the xApp:\n\n```\n{\"ts\": 1729716349154, \"crit\": \"INFO\", \"id\": \"ricxappframe.xapp_frame\", \"mdc\": {}, \"msg\": \"[MobiFlow] Storing MobiFlow record to SDL UE;0;1729716349154.052;v2.0;SECSM;0;60786;1450744508;0;0;0;0;0;RRCSetupRequest;0;0;0;0;0;0;0;0\"}\n{\"ts\": 1729716349155, \"crit\": \"INFO\", \"id\": \"ricxappframe.xapp_frame\", \"mdc\": {}, \"msg\": \"[MobiFlow] Storing MobiFlow record to SDL UE;1;1729716349154.0964;v2.0;SECSM;0;60786;1450744508;0;0;0;0;0;RRCSetup;2;0;0;0;1729716349154.0103;0;0;0\"}\n{\"ts\": 1729716349155, \"crit\": \"INFO\", \"id\": \"ricxappframe.xapp_frame\", \"mdc\": {}, \"msg\": \"[MobiFlow] Storing MobiFlow record to SDL BS;2;1729716349154.1838;v2.0;SECSM;0;208;099;0;00bc614e;1000;1;0;0;1729716338046.782;0\"}\n{\"ts\": 1729716349156, \"crit\": \"INFO\", \"id\": \"ricxappframe.xapp_frame\", \"mdc\": {}, \"msg\": \"[MobiFlow] Storing MobiFlow record to SDL UE;2;1729716349154.2026;v2.0;SECSM;0;60786;1450744508;0;0;0;0;0;RRCSetupComplete;2;0;0;0;1729716349154.0103;0;0;0\"}\n{\"ts\": 1729716349156, \"crit\": \"INFO\", \"id\": \"ricxappframe.xapp_frame\", \"mdc\": {}, \"msg\": \"[MobiFlow] Storing MobiFlow record to SDL UE;3;1729716349154.2297;v2.0;SECSM;0;60786;1450744508;0;0;0;0;0;Registrationrequest;2;1;0;0;1729716349154.0103;0;1729716349154.0103;0\"}\n{\"ts\": 1729716349156, \"crit\": \"INFO\", \"id\": \"ricxappframe.xapp_frame\", \"mdc\": {}, \"msg\": \"[MobiFlow] Storing MobiFlow record to SDL BS;3;1729716349154.2725;v2.0;SECSM;0;208;099;0;00bc614e;1000;1;0;0;1729716338046.782;0\"}\n...\n```\n\n## SDL Database\n\nThe MobiFlow telemetry will be stored in the SDL databased provided by the OSC RIC infrastructure. The Shared Data Layer (SDL) provides a lightweight, high-speed interface (API) for accessing shared data storage. SDL can be used for storing and sharing any data. Data can be shared at VNF level. One typical use case for SDL is sharing the state data of stateful application processes. Thus enabling stateful application processes to become stateless, conforming with, e.g., the requirements of the fifth generation mobile networks. Refer to: https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=20874400\n\nBy default, the OSC near-RT RIC will deploy the redis database as a service backend.\n\n```\n$ sudo kubectl get pods -n ricplt\nNAME                                                         READY   STATUS    RESTARTS   AGE\n...\nstatefulset-ricplt-dbaas-server-0                            1/1     Running   0          100m\n```\n\nYou may login to the SDL through:\n\n```\nkubectl exec -it statefulset-ricplt-dbaas-server-0 -n ricplt sh\n```\n\nUse the `sdlcli` command in the pod to lookup the stored MobiFlow data:\n\n```\n/data # sdlcli get namespaces\nappdb\nappmgr\nbs_mobiflow\ne2Manager\nsubmgr_restSubsDb\nue_mobiflow\n/data #\n/data # sdlcli get ue_mobiflow 1\n1:�iUE;1;1729716349154.0964;v2.0;SECSM;0;60786;1450744508;0;0;0;0;0;RRCSetup;2;0;0;0;1729716349154.0103;0;0;0\n```\n\nOther xApps deployed at the nRT-RIC can also use RESTFul APIs to access these data in the SDL. Refer to our other xApp examples such as [MobieXpert](https://github.com/5GSEC/MobieXpert/tree/osc) and [MobiWatch](https://github.com/5GSEC/MobiWatch) to checkout the implementation.\n\n\n## Publication\n\nPlease cite our research papers if you develop any products and prototypes based on our code:\n\n```\n@inproceedings{wen2022fine,\n  title={A fine-grained telemetry stream for security services in 5g open radio access networks},\n  author={Wen, Haohuang and Porras, Phillip and Yegneswaran, Vinod and Lin, Zhiqiang},\n  booktitle={Proceedings of the 1st International Workshop on Emerging Topics in Wireless},\n  pages={18--23},\n  year={2022}\n}\n```\n\n```\n@inproceedings{5G-Spector:NDSS24,\n  title     = {5G-Spector: An O-RAN Compliant Layer-3 Cellular Attack Detection Service},\n  author    = {Wen, Haohuang and Porras, Phillip and Yegneswaran, Vinod and Gehani, Ashish and Lin, Zhiqiang},\n  booktitle = {Proceedings of the 31st Annual Network and Distributed System Security Symposium (NDSS'24)},\n  address   = {San Diego, CA},\n  month     = {February},\n  year      = 2024\n}\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5GSEC%2FMobiFlow-Auditor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5GSEC%2FMobiFlow-Auditor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5GSEC%2FMobiFlow-Auditor/lists"}