FuzzyDoo: Your Fuzzer for 5G Core Networks

Overview

FuzzyDoo is a Mutation-Based Structure-Aware Fuzzer designed for testing the 5G core network's robustness and security. By leveraging mutation strategies and structure-awareness, it systematically generates inputs for various 5G core protocols (e.g., NGAP, NAS) to uncover vulnerabilities in protocol implementations.

Key features include:

• Protocol-Specific Fuzzing: Targets 5G-specific protocols like NGAP and NAS.
• Agent-Based Architecture: Utilizes agents for managing network sniffing, container monitoring, and protocol simulation.
• Flexible Configuration: Supports customizable test configurations via YAML files.
• Widely Extensible: Allows users to add new mutation strategies, integrate additional agents, or extend protocol support.

The choice of the name reflects the fuzzer’s purpose: to "unmask" hidden bugs and weaknesses, much like Scooby-Doo and the gang uncover hidden truths behind seemingly impenetrable mysteries.

Dependencies

General Requirements

• Python: Make sure Python 3.13 or later is installed.

• Poetry: Used for dependency management. Install it via:

  pip install poetry
  

Additional Requirements

NetworkProxy Agent

The NetworkProxy agent requires libsctp-dev and python3-dev. On Debian/Ubuntu they can be installed with:

sudo apt install libsctp-dev python3-dev

NetworkFunctionProxy Agent

The NetworkFunctionProxy agent requires the br-netfilter kernel module for network operations. To verify if it is already loaded run:

lsmod | grep br_netfilter

If no output appears, load it with:

sudo modprobe br-netfilter

UERANSIMController Agent

The UERANSIMController agent requires the UERANSIM simulator. Installation instructions can be found in the UERANSIM GitHub Repository.

Installation

Note: It is recommended to run this project inside a Python virtual environment.

1. Clone the Repository:

   git clone https://github.com/gabrielepongelli/FuzzyDoo
   cd FuzzyDoo
   

2. Build and Install: Use the Makefile to build and install the project in the current python environment:

   make install
   

   This installs the package along with all the agent dependencies. If you only need the core functionality, use:

   make install-no-agents
   

   To see all available installation options, run:

   make help
   

Usage

Fuzzer

To start fuzzing with a given configuration file (config.yaml):

fuzzydoo fuzz config.yaml

See the examples/setup directory for sample configurations.

If a vulnerability is detected (e.g., in run 1, epoch 7, test case 14 with seed 0xaabbccddeeff0011), replay it without re-running the entire fuzzing campaign:

fuzzydoo replay config.yaml 0xaabbccddeeff0011 1 --epoch 7 --test-case 14

For a complete list of commands and options, run:

fuzzydoo --help

Agents

Currently, these are the available agents:

• CommandExec
• ContainerRestart
• ContainerMonitor
• NetworkFunctionProxy
• NetworkProxy
• NetworkSniffer
• UERANSIMController

Note: CommandExec, ContainerRestart, ContainerMonitor, and NetworkSniffer have no special installation requirements beyond the core dependencies.

Each agent can be started by issuing a command obtained by translating its name from camel case to dash case. The command takes exactly 2 arguments:

1. --ip <IP>: the IP address on which it should listen for incoming connections from the core.
2. --port <PORT>: the port on which it should listen.

For example, to start the NetworkFunctionProxy agent:

network-function-proxy --ip 127.0.0.1 --port 5000

For a brief description about each agent, use the --help argument.

License

This project is licensed under the MIT License - read the LICENSE file for details.

Contributions

Contributions are welcome! Please open an issue or submit a pull request for any improvements or fixes.

Citing

If you find FuzzyDoo useful in your research or projects, we’d really appreciate it if you could cite our paper:

@article{fuzzydoo,
    title = {FuzzyDoo: a Framework for Finding Flaws in the 5G Landscape},
    journal = {Computer Networks},
    pages = {111734},
    year = {2025},
    issn = {1389-1286},
    author = {Rosario G. Garroppo, Michele Pagano, Gabriele Pongelli},
}

This helps acknowledge the original research and gives credit to the work behind the framework.