{"id":51409510,"url":"https://github.com/lvdund/StormSIM","last_synced_at":"2026-07-23T06:00:35.470Z","repository":{"id":360902007,"uuid":"1192450123","full_name":"lvdund/StormSIM","owner":"lvdund","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-28T09:51:02.000Z","size":1060,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T11:22:27.169Z","etag":null,"topics":["5g-nr","5g-ran","5g-ue","5gc","gnb"],"latest_commit_sha":null,"homepage":"","language":"Go","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/lvdund.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T08:23:13.000Z","updated_at":"2026-05-28T09:50:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lvdund/StormSIM","commit_stats":null,"previous_names":["lvdund/stormsim"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lvdund/StormSIM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lvdund%2FStormSIM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lvdund%2FStormSIM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lvdund%2FStormSIM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lvdund%2FStormSIM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lvdund","download_url":"https://codeload.github.com/lvdund/StormSIM/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lvdund%2FStormSIM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35791261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","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-nr","5g-ran","5g-ue","5gc","gnb"],"created_at":"2026-07-04T14:00:27.788Z","updated_at":"2026-07-23T06:00:35.464Z","avatar_url":"https://github.com/lvdund.png","language":"Go","funding_links":[],"categories":["Lab \u0026 Testbeds"],"sub_categories":["Ready-to-Use Environments"],"readme":"# StormSim\n\n\u003e **Notice** - StormSim source code may be temporarily hidden until **10/2026** while the project completes full support for the planned specifications and features listed in [Future Work](#future-work). If you want to use StormSim during this period, use the published Docker image and follow [Simple way to run](#simple-way-to-run).\n\nA scalable **UE** and **gNodeB** emulator for **testing, validating, and benchmarking 5G Core networks**. StormSim emulates thousands of UEs and gNodeBs that establish real NAS/NGAP signalling toward an actual 5G Core (AMF/SMF/UPF, e.g. [free5GC](https://github.com/free5gc/free5gc) or [Open5GS](https://github.com/open5gs/open5gs)). It is designed for stress-testing, regression validation, and performance benchmarking of the control plane.\n\n\u003e **Note** - StormSim emulates the **control plane** (UE ↔ gNB ↔ AMF) and sets up N3 data-plane tunnels via the [gtp5g](https://github.com/free5gc/gtp5g) kernel module of Free5gc. It is not a user-plane traffic generator.\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n| --- | --- |\n| [docs/how-to-config.md](docs/how-to-config.md) | How to configure StormSim: every `config.yml` block, field reference, scenarios, recipes, and gotchas |\n| [docs/how-to-use-oam-client.md](docs/how-to-use-oam-client.md) | How to use the OAM `client`: command reference with sample output and metrics |\n\n---\n\n## Features\n\n### Scale\n\n- Each UE and gNB runs on a shared worker pool and tested up to **10,000 UEs + gNodeBs in a single run** against a real 5G Core.  \n\n### PCAP capture\n\n- Capture signalling to a PCAP file with `--pcap`. StormSim attaches a live capture to the host interface that carries the gNodeB control plane (N2, which transports **N1 NAS**), so you get the full NAS/NGAP exchange in Wireshark.\n\n### NAS procedures (UE side, 5GMM / 5GSM)\n\n- Registration (Initial / Periodic / Emergency)\n- Deregistration (UE-initiated and network-initiated; switch-off \u0026 re-registration)\n- PDU Session Establishment / Release (and modification)\n- Service Request\n- Identity / Authentication / Security Mode Control\n- Configuration Update\n- Paging\n- Idle-mode ↔ Connected-mode transitions\n- Handover: Xn handover (Path Switch Request) and N2 handover\n\n### NGAP procedures (gNB ↔ AMF)\n\n- NG Setup\n- Initial UE Message\n- Uplink NAS Transport / Downlink NAS Transport\n- Initial Context Setup (Request/Response)\n- PDU Session Resource Setup / Release\n- UE Context Release (Command/Complete)\n- Paging\n- Path Switch Request (Xn HO) and Handover Request/Command/Notify (N2 HO)\n- AMF Configuration Update\n\n### NAS protocol timers (3GPP TS 24.501)\n\nEach timer can be individually enabled/disabled in config `defaultUe.timers`: T3510, T3511, T3502, T3512, T3516, T3519, T3520, T3580, T3582\n\n### SUCI / Subscriber privacy\n\n\u003e **Status:** Currently StormSim uses the **Null-Scheme** (unconcealed SUPI/IMSI).\n\u003e **Profile A (X25519)** and **Profile B (P-256)** ECIES concealing/deconcealing are\n\u003e **not yet implemented** - see [Future Work](#future-work).\n\n### Radio-link impairment (RLink)\n\nInject realistic radio-link conditions on the UE ↔ gNB path:\n- **Delay** (`rlink.delay_ms`): random 0–N ms added per NAS message.\n- **Loss** (`rlink.loss_ratio`): probability of dropping a NAS message (0.0–1.0).\n\n### Client / OAM \u0026 metrics\n\nA remote OAM server (HTTP) plus an interactive `client` let you **inspect and trigger events at runtime** while a scenario is running, and collect per-transition **delay statistics** (mean, std-dev, P1–P99 percentiles), UE state histograms, and handover-delay metrics - see [docs/how-to-use-oam-client.md](docs/how-to-use-oam-client.md).\n\n---\n\n## Future Work\n\n- **SUCI concealing/deconcealing** - implement **Profile A (X25519)** and **Profile B (P-256)** ECIES (currently Null-Scheme only).\n- **FUZZ mode** vs **Replay mode**:\n    - FUZZ: randomized fault injection at the **UE state/event** level and at the **NAS IE** level (mutate information elements) to probe Core robustness.\n    - Replay: record a signalling trace and deterministically replay it.\n- **Conditional Handover (CHO)** and **timer handling during handover** (e.g. preserving/restarting 5GMM timers across the HO).\n\n---\n\n## Requirements\n\n\n| Component        | Requirement                                                                      |\n| ---------------- | -------------------------------------------------------------------------------- |\n| **OS**           | Ubuntu **20.04 – 22.04**                                                         |\n| **Linux kernel** | `5.4.* ≤ kernel ≤ 6.1.*` (required by `gtp5g`; StormSim borrows it from free5GC) |\n| **Go**           | **1.25+**                                                                        |\n| **SCTP**         | `sudo apt install make lksctp-tools`                                             |\n| **Build tools**  | `make`, `gcc` (kernel headers for `gtp5g`)                                       |\n\n  \n\u003e The kernel upper bound (`6.1.*`) is a hard constraint of the `gtp5g` kernel module.\n\u003e Newer kernels (6.2+) are not supported until `gtp5g` catches up.\n\nMake sure the `gtp5g` kernel module is built and loaded before running scenarios that establish PDU sessions.\n\n---\n\n## Simple way to run\n\nPull the published image from Docker Hub:\n```bash\ndocker pull lvdund/stormsim:latest\n```\n\nBefore running, make sure:\n- the host is Linux\n- the `gtp5g` kernel module is already built and loaded on the host\n\nRun the emulator:\n```bash\ndocker run --rm -it \\\n  --privileged \\\n  --network host \\\n  -v \"$(pwd)/config:/app/config:ro\" \\\n  lvdund/stormsim:latest\n```\n\nThis starts the emulator with `/app/config/config.yml` inside the container, so your host\ndirectory should contain `config/config.yml`.\n\nRun the client in interactive mode:\n```bash\ndocker run --rm -it \\\n  --network host \\\n  --entrypoint client \\\n  lvdund/stormsim:latest\n```\n\nRun the client with a single command:\n```bash\ndocker run --rm -it \\\n  --network host \\\n  --entrypoint client \\\n  lvdund/stormsim:latest list-ue\n```\n\nMore client commands and examples are documented in [`docs/how-to-use-oam-client.md`](docs/how-to-use-oam-client.md).\n\n---\n\n## Build \u0026 Compile\n\nStormSim produces two binaries via `make`:\n\n```bash\n# Build both\nmake # = make build = make emulator client\n\n# Or build individually\nmake emulator # → bin/emulator\nmake client # → bin/client\n\nmake clean # remove bin/\n```\n\n| Binary         | Purpose                                                                                                          |\n| -------------- | ---------------------------------------------------------------------------------------------------------------- |\n| `bin/emulator` | The simulator itself: loads a config, spawns UEs/gNBs, runs scenarios, and serves the OAM API.                   |\n| `bin/client`   | Command-line \u0026 interactive client that talks to the running emulator's OAM server (`localhost:4000` by default). |\n\n---\n\n## Running the Emulator\n\n```bash\n# With a config file\nsudo ./bin/emulator -c config/config.yml\n\n# With config + PCAP capture of the N2/N1 signalling\nsudo ./bin/emulator -c config/config.yml --pcap capture.pcap\n\n# Built-in configuration help\n./bin/emulator --config-help\n```\n\n\u003e **`sudo` is required** because StormSim binds SCTP/SCTP sockets, attaches a live PCAP handle to a host interface, and manages `gtp5g` N3 tunnels.\n\nThe emulator will:\n1. Load \u0026 validate the config.\n2. Connect the gNB(s) to the AMF (`NG Setup`).\n3. Spawn the configured UE groups and enqueue their events.\n4. Serve the OAM API on `remote.ip:remote.port` (default `0.0.0.0:4000`).\n\n\u003e 📖 Configuration is covered in **[docs/how-to-config.md](docs/how-to-config.md)**; using the live client is covered in **[docs/how-to-use-oam-client.md](docs/how-to-use-oam-client.md)**.\n\n---\n\n## Contributor\n\n- [lvdund](https://github.com/lvdund)\n- [Phùng Kiều Hà](mailto:ha.phungthikieu@hust.edu.vn)  \n- [Thái Quang Tùng](https://github.com/reogac)\n\n---\n\n## Citation\n\n```latex\n@software{stormsim,\n  author       = {VD},\n  title        = {{StormSim}: A Scalable {UE} and {gNodeB} Emulator for Testing, Validating, and Benchmarking {5G Core} Networks},\n  year         = {2025},\n  publisher    = {GitHub},\n  howpublished = {\\url{https://github.com/lvdund/StormSIM}},\n  note         = {Accessed: 2026-07-01}\n}\n```\n\n---\n\n## License\n\nLicensed under the **Apache License, Version 2.0**. See [LICENSE](LICENSE).\n\nStormSIM uses `gtp5g` of free5gc for enabling gtp tunnel and learns design from UERANSIM vs PacketRusher.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flvdund%2FStormSIM","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flvdund%2FStormSIM","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flvdund%2FStormSIM/lists"}