{"id":30215575,"url":"https://github.com/5gsec/mobiwatch","last_synced_at":"2025-08-14T02:13:27.044Z","repository":{"id":228919387,"uuid":"741305885","full_name":"5GSEC/MobiWatch","owner":"5GSEC","description":"An O-RAN compliant xApp employing deep learning to detect 5G cellular network threats and anomalies","archived":false,"fork":false,"pushed_at":"2025-07-29T18:25:43.000Z","size":51003,"stargazers_count":9,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-29T19:15:42.448Z","etag":null,"topics":["5g","deep-learning","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-01-10T05:48:49.000Z","updated_at":"2025-07-29T18:25:46.000Z","dependencies_parsed_at":"2025-07-17T19:54:48.247Z","dependency_job_id":null,"html_url":"https://github.com/5GSEC/MobiWatch","commit_stats":null,"previous_names":["5gsec/5g-deepwatch","5gsec/mobiwatch"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/5GSEC/MobiWatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiWatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiWatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiWatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiWatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5GSEC","download_url":"https://codeload.github.com/5GSEC/MobiWatch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5GSEC%2FMobiWatch/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","deep-learning","o-ran","xapp"],"created_at":"2025-08-14T02:13:21.017Z","updated_at":"2025-08-14T02:13:27.011Z","avatar_url":"https://github.com/5GSEC.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MobiWatch\n\nMobiWatch is an O-RAN compliant xApp that employs unsupervised unsupervised deep learning to detect layer-3 (RRC and NAS) cellular anomalies and attacks in 5G networks. MobiWatch operates on the security data telemetry called [MobiFlow](https://github.com/5GSEC/MobiFlow-Auditor), a security audit trail for holding mobile devices accountable during the link and session setup protocols as they interact with the base station.\n\nCurrently it is compatible with two nRT-RIC implmentations: [OSC RIC](https://lf-o-ran-sc.atlassian.net/wiki/spaces/ORAN) and [SD-RAN ONOS RIC](https://docs.sd-ran.org/master/sdran-in-a-box/README.html). You can deploy and test MobiWatch based on the [tutorial](https://github.com/5GSEC/5G-Spector/wiki/O%E2%80%90RAN-SC-RIC-Deployment-Guide) we have created to instantiate an O-RAN compliant 5G network with just open-sourced software such as [OpenAirInterface](https://gitlab.eurecom.fr/oai/openairinterface5g/). \n\nFor more design details, please refer to our **HotNets'24 research paper** [6G-XSec: Explainable Edge Security for Emerging OpenRAN Architectures](https://onehouwong.github.io/papers/HotNets_2024_6gxsec.pdf). We have also released a **demo video**: [MobiWatch Demo on 5G Attack Detection with AI/DL](https://www.5gsec.com/post/video-mobiwatch-demo-on-5g-attack-detection-with-ai-dl).  \n\n![alt text](./fig/sys.png)\n\n## Prerequisite\n\n### Local Docker registry\n\nMobiWatch 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\n### MobiFlow Auditor xApp\n\nMobiWatch directly acquires security telemetry from the SDL generated from the [MobiFlow Auditor xApp](https://github.com/5GSEC/MobiFlow-Auditor) xApp. Follow the instructions to prepare the environment and collect data from a 5G network.\n\n\n## Build\n\nRun the build script:\n\n```\n./build.sh\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\nSuccessful deployment (this may take a while):\n\n```\n$ kubectl get pods -n ricxapp\nricxapp        ricxapp-mobiwatch-xapp-6b8879868d-fmnbd                      1/1     Running     0             5m32s\n```\n\n\nTo uninstall MobiWatch from the Kubernetes cluster:\n\n```\n./undeploy.sh\n```\n\n## Running Example\n\nMobiWatch's classification results with benign 5G network traffic:\n\n```\n[INFO 2024-10-23 21:42:23,990 dlagent.py:222]\n    rnti        tmsi                     msg\n0  60786  1450744508         RRCSetupRequest\n1  60786  1450744508                RRCSetup\n2  60786  1450744508        RRCSetupComplete\n3  60786  1450744508     Registrationrequest\n4  60786  1450744508   Authenticationrequest\n5  60786  1450744508  Authenticationresponse\n[INFO 2024-10-23 21:42:23,990 dlagent.py:223] Benign\n\n\n[INFO 2024-10-23 21:42:23,993 dlagent.py:222]\n    rnti        tmsi                     msg\n1  60786  1450744508                RRCSetup\n2  60786  1450744508        RRCSetupComplete\n3  60786  1450744508     Registrationrequest\n4  60786  1450744508   Authenticationrequest\n5  60786  1450744508  Authenticationresponse\n6  60786  1450744508     Securitymodecommand\n[INFO 2024-10-23 21:42:23,993 dlagent.py:223] Benign\n```\n\nMobiWatch's classification results with an specific 5G network attack:\n\n```\n[ERROR 2024-10-24 16:07:40,227 dlagent.py:225]\n    rnti        tmsi                    msg\n0  53496  1450744508        RRCSetupRequest\n1  53496  1450744508               RRCSetup\n2  53496  1450744508       RRCSetupComplete\n3  53496  1450744508    Registrationrequest\n4  53496  1450744508  Authenticationrequest\n5  53496  1450744508       Identityresponse\n[ERROR 2024-10-24 16:07:40,227 dlagent.py:226] Abnormal\n```\n\nThis attack represents a downlink overshadowing where the network's Authentication Request message is overwritten and the UE responds with an IdentityResponse message with its identity, constituding an identity extraction attack. MobiWatch classifies this as an abnormal event as it deviates from normal traffic the DL model was traineed on.\n\n\n\n## Dataset\n\nDatasets used for training the DL model are available in this [folder](./dataset). We provide both the original [pcap](./dataset/pcap/) format of the benign / attack traffic we have collected in a test 5G network based on OAI, as well as the [MobiFlow](https://github.com/5GSEC/MobiFlow-Auditor) security telemetry format in `.csv` (converted from the `.pcap` files) that are used to train our DL detection models.\n\n\n## Model Training\n\nMobiWatch has pre-trained DL models on benign layer-3 5G network traffic, including a vanilla [Autoencoder](./src/ai/autoencoder/model.py) model and a multivariate [LSTM](./src/ai/lstm/lstm_multivariate.py) model implemented by the [DeepAID](https://github.com/dongtsi/DeepAID) paper. The pre-trained models will be loaded into the xApp container.\n\n\n## Publication\n\nPlease cite our research papers if you develop any products and prototypes based on our code and datasets:\n\n```\n@inproceedings{6G-XSEC:Hotnets24,\n  title     = {6G-XSec: Explainable Edge Security for Emerging OpenRAN Architectures },\n  author    = {Wen, Haohuang and Sharma, Prakhar and Yegneswaran, Vinod and Porras, Phillip and Gehani, Ashish and Lin, Zhiqiang},\n  booktitle = {Proceedings of the Twenty-Third ACM Workshop on Hot Topics in Networks (HotNets 2024)},\n  address   = {Irvine, CA},\n  month     = {November},\n  year      = 2024\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5gsec%2Fmobiwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5gsec%2Fmobiwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5gsec%2Fmobiwatch/lists"}