docs: rewrite README as developer-focused landing page#48
Open
docs: rewrite README as developer-focused landing page#48
Conversation
Replace the minimal README with a structured landing page targeting network engineers and 5G security researchers. Adds an architecture diagram (Mermaid), feature table, copy-paste quick start (Docker / binary / source), usage examples with real CLI flags, bundled rules table, and commands reference. Original content preserved in collapsed <details> sections. README.backup.md added as backup of the original.
- Fix release binary filename: _Linux_x86_64_Ubuntu_24.04.tar.gz (not plain _x86_64) - Fix fuzz example: add missing ngap.pdu_present argument (matches rule 7 source) - Fix type_property schema: list all valid values (FORWARD, ATTACK, SECURITY, EVASION, TEST) - Clarify ATTACK type_property behavior: packet handling follows forward.default
RAN and gNodeB are not supported targets. 5GReplay forwards to 5G core NFs (AMF, SMF, UPF) over SCTP, UDP, or HTTP/2 only. Update hero description, architecture diagram, and usage example accordingly.
nhnghia
reviewed
Apr 7, 2026
| # Replay, mutate, and inject 5G traffic against live network functions | ||
|
|
||
| **5Greplay** is a 5G network traffic fuzzer that enables the evaluation of 5G components by replaying and modifying 5G network traffic, by creating and injecting network scenarios into a target that can be a 5G core service (e.g., AMF, SMF) or a RAN network (e.g., gNodeB). The tool provides the ability to alter network packets online or offline in both control and data planes in a very flexible manner. | ||
| 5GReplay captures or reads 5G pcap traffic, applies XML-defined mutation rules at the packet level, and forwards the modified packets to a target 5G core NF (AMF, SMF, UPF) over SCTP, UDP, or HTTP/2 — online or offline, control plane or data plane. |
Collaborator
There was a problem hiding this comment.
- Should be
5Greplay(not5GReplay)
| C -->|no match| E[Forward as-is] | ||
| D --> F[5G Core NF\nAMF · SMF · UPF\nvia SCTP · UDP · HTTP2] | ||
| E --> F | ||
| F -.->|optional| G[pcap dump] |
Collaborator
There was a problem hiding this comment.
pcap dumpis incorrectly localised after5G Core NF ...(should be beforeF, and just afterDandE)
|
|
||
| # | ||
|  | ||
| Rules are compiled from XML to shared libraries (`.so`) at runtime. Each rule defines a packet pattern and a reactive action: forward, modify, fuzz, drop, or execute arbitrary C. |
Collaborator
There was a problem hiding this comment.
at runtime: No, rules must be compiled before running time
Comment on lines
+47
to
+80
| **Option A — Docker (no build required):** | ||
|
|
||
| ```bash | ||
| docker run --rm -it ghcr.io/montimage/5greplay | ||
| ``` | ||
|
|
||
| Replay a bundled pcap against a remote AMF: | ||
|
|
||
| ```bash | ||
| docker run --rm -it ghcr.io/montimage/5greplay \ | ||
| replay -t pcap/sa.pcap \ | ||
| -Xforward.target-hosts=10.0.0.2 \ | ||
| -Xforward.target-ports=38412 \ | ||
| -Xforward.nb-copies=2000 \ | ||
| -Xforward.default=FORWARD | ||
| ``` | ||
|
|
||
| **Option B — Pre-built binary (Ubuntu):** | ||
|
|
||
| ```bash | ||
| wget https://github.com/Montimage/5GReplay/releases/download/v1.0.0/5greplay-1.0.0_Linux_x86_64_Ubuntu_24.04.tar.gz | ||
| tar -xzf 5greplay-1.0.0_Linux_x86_64_Ubuntu_24.04.tar.gz | ||
| cd 5greplay-1.0.0 | ||
| ./5greplay -h | ||
| ``` | ||
|
|
||
| **Option C — Build from source:** | ||
|
|
||
| ```bash | ||
| sudo apt install gcc make git libxml2-dev libpcap-dev libconfuse-dev libsctp-dev | ||
| wget https://github.com/Montimage/mmt-dpi/releases/download/v1.7.9/mmt-dpi_1.7.9_8694eaa_Linux_x86_64.deb | ||
| sudo dpkg -i mmt-dpi*.deb && sudo ldconfig | ||
| git clone https://github.com/montimage/5greplay && cd 5greplay | ||
| make && make sample-rules |
Collaborator
There was a problem hiding this comment.
- need to check to ensure that the commands are executed correctly
| </property> | ||
| ``` | ||
|
|
||
| Valid `type_property` values: `FORWARD`, `ATTACK`, `SECURITY`, `EVASION`, `TEST` |
Collaborator
There was a problem hiding this comment.
- Only
FORWARDandDROPare relevant (other are inherent from mmt-security and irrelevant for 5Greplay)
| Valid `type_property` values: `FORWARD`, `ATTACK`, `SECURITY`, `EVASION`, `TEST` | ||
|
|
||
| - `type_property="FORWARD"` — packets matching the rule are forwarded (possibly mutated) | ||
| - `type_property="ATTACK"` — rule match triggers an alert; packet handling follows `forward.default` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
<details>sections;README.backup.mdadded as a full backupTest plan
<details>sections expand correctly