Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@onehouwong
onehouwong committed Oct 23, 2024
1 parent 10dc848 commit 2aa8a40
Showing 1 changed file with 9 additions and 31 deletions.
40 changes: 9 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,18 @@ SPDX-License-Identifier: Apache-2.0

MobiFlow 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.

MobiFlow 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.
MobiFlow 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.

To learn more about the format and structure of MobiFlow, please refer to our papers:

- [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)
- [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)

MobiFlow 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.


We also have an old version 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) but not recommended any more since the ONOS RIC xApp python SDK is no longer being maintained.



## Prerequisite
Expand All @@ -28,23 +33,12 @@ Create a local docker registry to host docker images:
sudo docker run -d -p 5000:5000 --restart=always --name registry registry:2
```

## Architecture

The current implementation of MobiFlow Auditor is dedicated to 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) and OpenAirInterface5G (https://gitlab.eurecom.fr/oai/openairinterface5g/).

Its communication with the RAN nodes (via E2) is based on the [ONOS RIC's python SDK](https://github.com/onosproject/onos-ric-sdk-py) and guidance from the exemplar [ONOS RAN Intelligent Controller xApps](https://github.com/onosproject/onos-ric-python-apps/) authored in Python programming language.

MobiFlow Auditor's data can be accessed by other analytic xApps through [gRPC](https://grpc.io/docs/languages/python/). The RPC API definitions can be found at [mobiflow_service.proto](https://github.com/5GSEC/MobiFlow-Auditor/blob/main/mobiflow-auditor/secsm/rpc/protos/mobiflow_service.proto).



## MobiFlow Structure

The current MobiFlow message definition is defined in [mobiflow.py](https://github.com/5GSEC/MobiFlow-Auditor/blob/main/mobiflow-auditor/secsm/mobiflow/mobiflow.py). 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). The E2SM implementation can be found at https://github.com/onosproject/onos-e2-sm.
The 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).

MobiFlow Auditor xApp requires O-RAN compliant RAN nodes to collect and report corresponding data. We have augmented the OpenAirInterface with MobiFlow telemetry support at [https://github.com/onehouwong/OAI-5G](https://github.com/5GSEC/OAI-5G) branch `2023.w23.secsm.sdran`.
MobiFlow 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`.


## Build the MobiFlow-Auditor xApp
Expand Down Expand Up @@ -129,22 +123,6 @@ By running the MobiFlow Auditor on the RIC along with an OAI gNB and nrUE, MobiF
{"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"}
{"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"}
{"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"}
{"ts": 1729716350155, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "KPM indication reported metrics: {'UE.RNTI': '60786', 'UE.IMSI1': '0', 'UE.IMSI2': '0', 'UE.RAT': '1', 'UE.M_TMSI': '1450744508', 'UE.CIPHER_ALG': '2', 'UE.INTEGRITY_ALG': '2', 'UE.EMM_CAUSE': '0', 'UE.RELEASE_TIMER': '0', 'UE.ESTABLISH_CAUSE': '3', 'msg1': '344', 'msg2': '348', 'msg3': '372', 'msg4': '376', 'msg5': '47', 'msg6': '51', 'msg7': '15', 'msg8': '19', 'msg9': '63', 'msg10': '83', 'msg11': '0', 'msg12': '0', 'msg13': '0', 'msg14': '0', 'msg15': '0', 'msg16': '0', 'msg17': '0', 'msg18': '0', 'msg19': '0', 'msg20': '0'}"}
{"ts": 1729716350156, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;4;1729716350155.529;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;Authenticationrequest;2;1;0;0;1729716349154.0103;0;1729716349154.0103;0"}
{"ts": 1729716350157, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;5;1729716350155.5762;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;Authenticationresponse;2;1;0;0;1729716349154.0103;0;1729716349154.0103;0"}
{"ts": 1729716350157, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;6;1729716350155.591;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;Securitymodecommand;2;1;0;0;1729716349154.0103;0;1729716349154.0103;0"}
{"ts": 1729716350158, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;7;1729716350155.6025;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;Securitymodecomplete;2;1;0;0;1729716349154.0103;0;1729716349154.0103;0"}
{"ts": 1729716350158, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;8;1729716350155.6143;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;SecurityModeCommand;2;1;0;0;1729716349154.0103;0;1729716349154.0103;0"}
{"ts": 1729716350159, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;9;1729716350155.635;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;SecurityModeComplete;2;1;1;0;1729716349154.0103;0;1729716349154.0103;0"}
{"ts": 1729716350159, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL BS;4;1729716350155.6719;v2.0;SECSM;0;208;099;0;00bc614e;1000;1;0;0;1729716338046.782;0"}
{"ts": 1729716350159, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;10;1729716350155.7305;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;RRCReconfiguration;2;1;1;0;1729716349154.0103;0;1729716349154.0103;0"}
{"ts": 1729716350160, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;11;1729716350155.7585;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;RRCReconfigurationComplete;2;2;1;0;1729716349154.0103;0;1729716349154.0103;1729716350155.4705"}
{"ts": 1729716350160, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL BS;5;1729716350155.85;v2.0;SECSM;0;208;099;0;00bc614e;1000;1;0;0;1729716338046.782;0"}
{"ts": 1729716350160, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;12;1729716350155.86;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;UECapabilityEnquiry;2;2;1;0;1729716349154.0103;0;1729716349154.0103;1729716350155.4705"}
{"ts": 1729716350161, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;13;1729716350155.8835;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;UECapabilityInformation;2;2;1;0;1729716349154.0103;0;1729716349154.0103;1729716350155.4705"}
{"ts": 1729716351154, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "KPM indication reported metrics: {'UE.RNTI': '60786', 'UE.IMSI1': '0', 'UE.IMSI2': '0', 'UE.RAT': '1', 'UE.M_TMSI': '1450744508', 'UE.CIPHER_ALG': '2', 'UE.INTEGRITY_ALG': '2', 'UE.EMM_CAUSE': '0', 'UE.RELEASE_TIMER': '0', 'UE.ESTABLISH_CAUSE': '3', 'msg1': '268', 'msg2': '412', 'msg3': '0', 'msg4': '0', 'msg5': '0', 'msg6': '0', 'msg7': '0', 'msg8': '0', 'msg9': '0', 'msg10': '0', 'msg11': '0', 'msg12': '0', 'msg13': '0', 'msg14': '0', 'msg15': '0', 'msg16': '0', 'msg17': '0', 'msg18': '0', 'msg19': '0', 'msg20': '0'}"}
{"ts": 1729716351154, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;14;1729716351154.1045;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;Registrationcomplete;2;2;1;0;1729716349154.0103;0;1729716349154.0103;1729716350155.4705"}
{"ts": 1729716351155, "crit": "INFO", "id": "ricxappframe.xapp_frame", "mdc": {}, "msg": "[MobiFlow] Storing MobiFlow record to SDL UE;15;1729716351154.1343;v2.0;SECSM;0;60786;1450744508;0;0;2;2;0;ULNAStransport;2;2;1;0;1729716349154.0103;0;1729716349154.0103;1729716350155.4705"}
...
```

Expand Down Expand Up @@ -182,7 +160,7 @@ ue_mobiflow
1:�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
```

Other xApps on the
Other 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.


## Publication
Expand Down

0 comments on commit 2aa8a40

Please sign in to comment.