{"id":30215541,"url":"https://github.com/5gsec/mobiexpert","last_synced_at":"2025-08-14T02:12:52.299Z","repository":{"id":224285727,"uuid":"762040946","full_name":"5GSEC/MobieXpert","owner":"5GSEC","description":"The first signature-based L3 cellular attack detection xApp for O-RAN","archived":false,"fork":false,"pushed_at":"2025-07-07T03:39:33.000Z","size":724,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-07T04:36:55.743Z","etag":null,"topics":["5g","intrusion-detection","o-ran","xapp"],"latest_commit_sha":null,"homepage":"https://www.5gsec.com/","language":"Python","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-02-23T00:57:10.000Z","updated_at":"2025-07-07T03:39:37.000Z","dependencies_parsed_at":"2024-09-06T20:31:41.239Z","dependency_job_id":"83cbed62-896a-4eae-931c-81a350aaa011","html_url":"https://github.com/5GSEC/MobieXpert","commit_stats":null,"previous_names":["5gsec/mobiexpert"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/5GSEC/MobieXpert","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobieXpert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobieXpert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobieXpert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobieXpert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5GSEC","download_url":"https://codeload.github.com/5GSEC/MobieXpert/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobieXpert/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270347825,"owners_count":24568605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"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","intrusion-detection","o-ran","xapp"],"created_at":"2025-08-14T02:12:49.675Z","updated_at":"2025-08-14T02:12:52.256Z","avatar_url":"https://github.com/5GSEC.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"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# MobieXpert\n\nMobieXpert is the first L3 cellular attack detection xApp deployed at O-RAN compliant near-RT RIC. \nMobieXpert’s design is based on the Production-Based Expert System Toolset ([P-BEST](https://ieeexplore.ieee.org/document/766911)) language, \nwhich has been widely used for decades in stateful intrusion detection. \nWith MobieXpert, network operators can program stateful production-based IDS rules for detecting a wide range of cellular L3 attacks.\n\nMobieXpert is an essential part of 5G-Spector. To get started and learn more about 5G-Spector, please refer to our \n[paper](https://web.cse.ohio-state.edu/~wen.423/papers/5G-Spector-NDSS24.pdf) in NDSS'24\nand the [5G-Spector](https://github.com/5GSEC/5G-Spector) git repository.\n\nMobieXpert is dedicated for the [OSC RIC](https://wiki.o-ran-sc.org/display/ORAN).\nIt is developed based on the [OSC RIC's python SDK](https://github.com/o-ran-sc/ric-plt-xapp-frame-py).\nMobieXpert obtains MobiFlow telemetry stream from the [MobiFlow Auditor xApp](https://github.com/5GSEC/MobiFlow-Auditor) via the Shared Data Layer (SDL) database.\n\nWe also have an old version at branch `master` 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## Prerequisite\n\n### Local Docker registry\n\nMobieXpert 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 nRT 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### MobiFlow Auditor xApp\n\nMobieXpert directly acquires security telemetry from the SDL generated from the [MobiFlow Auditor xApp](https://github.com/5GSEC/MobiFlow-Auditor) xApp. Following the instructions to prepare the environment and collect data from a 5G network.\n\n\n## IDS Programming with MobieXpert\n\nMobieXpert’s programming capability is powered by the Production-Based Expert System Toolset ([P-BEST](https://ieeexplore.ieee.org/document/766911)) language.\nThe IDS rule file is located at [src/pbest/expert/rules.pbest](./src/pbest/expert/rules.pbest). It has already integrated the L3 attack detection rules described in our original paper.\n\nTo get started with the P-BEST syntax, please refer to the P-BEST original paper: [Detecting computer and network misuse through the production-based expert system toolset (P-BEST)](https://ieeexplore.ieee.org/document/766911).\n\nDuring compilation and building, the P-BEST rule file will be translated into C executables by the `pbcc` compiler. The executable listens to the input from a local `csv` file that is constantly updated with MobiFlow streams.\n\n\n## Example Walkthrough\n\nBelow we provided an example of how [BTS Resource Depletion Attack](https://ieeexplore.ieee.org/document/8835363) could be detected by programming a P-BEST rule set which has been already integrated into [src/pbest/expert/rules.pbest](./src/pbest/expert/rules.pbest) from [line 433-536](./src/pbest/expert/rules.pbest#L433).\nOur original [paper](https://web.cse.ohio-state.edu/~wen.423/papers/5G-Spector-NDSS24.pdf) also describes how this rule sets were developed.\n\n![alt text](https://github.com/5GSEC/MobieXpert/blob/osc/figure.png)\n\nThe following P-BEST rule defined in `rules.pbest`  serves as an auxiliary rule for detecting BTS resource depletion attack:\n\n```\nrule[bts_depletion_add_first_transient_ue_5g:\n    [+s:ue_session^TRANSIENT]\n    [+ts_ev:ts_event]\n    [?|s.nas_state == 1]                                        `NAS registering state\n    [?|ts_ev.value - s.ts \u003e 'BTS_DEPLETION_REG_INIT_TIME_THRESHOLD]\n    [-transient_ue_counter|bs_id == s.bs_id]\n    [-transient_ue|bs_id == s.bs_id, rnti == s.rnti]\n==\u003e\n    [+transient_ue_counter|bs_id = s.bs_id, value = 1, ts = s.ts]\n    [+transient_ue|bs_id = s.bs_id, rnti = s.rnti, ts = s.ts]\n    [$|s:TRANSIENT]\n    [!|debugprintf(\"[BTS Resource Depletion][ADD_FIRST_TRANSIENT_UE_5G] Marking UE %d/%x as transient\\n\", s.rnti, s.rnti)]\n    [!|debugprintf(\"[BTS Resource Depletion][ADD_FIRST_TRANSIENT_UE_5G] Transient UE counter of bs %d is %d\\n\", s.bs_id, 1)]\n]\n```\n\nThis rule based on certain user-defined `xtype` structures in the P-BEST file. It determines whether a UE is a `transient UE` that explicits a layer-3 RRC DoS pattern.\nFrom the rule, it leverages the MobiFlow features, i.e., the UE timers, and checks whether the session has been stuck at NAS registering state exceeding a time threshold `BTS_DEPLETION_REG_INIT_TIME_THRESHOLD`.\nThen this rule will be triggered to add a transient UE instance and update the counters. The accumulated counters will then be evaluated to determine whether to trigger a BTS resource depletion attack alert, based on the rule below:\n\n```\nrule[bts_depletion_generate_event:\n    [+tran_ue_cntr: transient_ue_counter^BTS_RESOURCE_DEPLETION]\n    [?|tran_ue_cntr.value \u003e 'BTS_DEPLETION_UE_THRESHOLD]\n==\u003e\n    [$|tran_ue_cntr: BTS_RESOURCE_DEPLETION]\n    [+event|id = 'event_id_cntr,\n\t        name = \"BTS Resource Depletion\",\n            ts = tran_ue_cntr.ts,\n            bs_id = tran_ue_cntr.bs_id,\n            ue = 0\n    ]\n    [!|'event_id_cntr += 1 ]\n    [!|debugprintf(\"[BTS Resource Depletion][GENERATE_EVENT] Event detected for bs %d\\n\", tran_ue_cntr.bs_id)]\n    [!|eventprintfjson('event_id_cntr, \"BTS Resource Depletion\", tran_ue_cntr.bs_id, tran_ue_cntr.ts, tran_ue_cntr.value)]\n]\n```\n\nAdditionally, all the defined `ptype` in P-BEST need to be cleaned up in time. The rule below uses a timer-based clean up strategy to release the transient UEs to avoid filing an false alarm:\n\n```\nrule[bts_depletion_release_transient_ue:\n    [+tran_ue:transient_ue]\n    [+tran_ue_cntr:transient_ue_counter|bs_id == tran_ue.bs_id]\n    [+ts_ev:ts_event]\n    [?|(ts_ev.value - tran_ue.ts) \u003e 'BTS_DEPLETION_RELEASE_TIME_THRESHOLD]\n==\u003e\n    [/tran_ue_cntr|value -= 1]\n    [-|tran_ue]\n    [!|debugprintf(\"[BTS Resource Depletion][RELEASE_TRANSIENT_UE] Removing transient UE %d/%x\\n\", tran_ue.rnti, tran_ue.rnti)]\n]\n```\n\n## Build the MobieXpert xApp\n\nAfter the new rules are integrated into [src/pbest/expert/rules.pbest](./src/pbest/expert/rules.pbest), you can use our Docker build script to build the MobiExpert xApp: \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\nlocalhost:5000/mobiexpert-xapp               0.0.1        39cc298cbb97   11 minutes ago   232MB\n```\n\nIf your `rules.pbest` file contains syntax error, an exception will occur and fail the build process.\n\n## Install the MobieXpert xApp\n\nFirst, onboard the xApp. You need to set up the proper environment with the `dms_cli` tool. Following the instructions here: https://github.com/5GSEC/OAI-5G-Docker/blob/master/O-RAN%20SC%20RIC%20Deployment%20Guide.md#mobiexpert-xapp. 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\nSuccessful deployment:\n\n```\n$ kubectl get pods -n ricxapp\nricxapp       ricxapp-mobiexpert-xapp-796846cc9b-sjwhn                     1/1     Running     0          26m\n```\n\n## Uninstall MobieXpert xApp\n\nUndeploy the MobieXpert xApp from Kubernetes:\n\n```\n./undeploy.sh\n```\n\n\n## Publication\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5gsec%2Fmobiexpert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5gsec%2Fmobiexpert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5gsec%2Fmobiexpert/lists"}