readme.md

July 24, 2026 · View on GitHub

MininetGym

Reinforcement learning Mininet OpenDayLight This project aims to provide a basic framework for DDoS mitigation using reinforcement learning (Deep and not). The network is implemented using Mininet (based on Software-Defined networking). The design of the solution is inspired by the work "MininetGym: A modular SDN-based simulation environment for reinforcement learning in cybersecurity" by Salvo Finistrella and others here.
Explore the docs »

Report Bug · Request Feature

Table of Contents

About The Project
- Built With
Getting Started
- Prerequisites
- Installation
Usage
Roadmap
Contributing
License
Contact
Acknowledgments

About The Project

Schema Screen Shot Schema Product Screen Shot Web UI

A Modular SDN-based Simulation Environment for Reinforcement Learning in Cybersecurity Real-time traffic generation and flow monitoring via Mininet and Custom Gym environments for traffic classification and DoS attack detection.

Built With

(back to top)

Getting Started

This section provides instructions on how to set up and run the MininetGym project on a clean Ubuntu 20.04+ system.

Prerequisites

Ensure you have the following installed on your system:

Python 3.11 or later
Mininet: A network emulator that creates a network of virtual hosts, switches, controllers, and links.
OpenDayLight (ODL): A modular open-source platform for Software-Defined Networking (SDN). Java 1.8.0 or later is required for ODL.

Installation

Follow these steps to get your development environment set up.

Install Mininet, hping3, and System Dependencies The project requires the hping3 tool for network attack simulation. Make sure it is installed along with Mininet.

bash sudo apt update && sudo apt upgrade -y sudo apt-get install mininet python3-venv git -y # Installazione di hping3 sudo apt-get install -y hping3 Verifica e Pulizia: Verification and Cleanup: Run a simple Mininet test and clean the environment to ensure that hping3 is recognized by the virtual hosts.

bash sudo mn --test pingall sudo mn -c You can verify the hping3 installation with: hping3 --help or which hping3.

Clone the Repository Create a new directory for your project, navigate into it, and clone your repository.

mkdir MininetGym
cd MininetGym
git clone [https://github.com/dipi-unimore/mininet-gym.git](https://github.com/dipi-unimore/mininet-gym.git)
cd mininet-gym

Create and Activate a Python Virtual Environment It is crucial to use a virtual environment to manage project dependencies and avoid conflicts with system packages. This also prevents the externally-managed-environment error.
```
# Create a new virtual environment named 'venv'
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate
```
You will see (venv) prepended to your terminal prompt, indicating that the virtual environment is active.
Install Python Dependencies With your virtual environment activated, install the required Python packages using requirements.txt.
```
pip install -r requirements.txt
```
If you encounter an error related to ale-py, you may need to update the version in the requirements.txt file (e.g., to ale-py>=0.11.0).
Troubleshooting: libcudnn.so Errors If you encounter an error like ImportError: libcudnn.so.9: cannot open shared object file: No such file or directory, it means that your PyTorch installation is configured to use NVIDIA GPU acceleration but cannot find the necessary libraries. You have two options to resolve this:

Option A: Install the CPU-only version of PyTorch (Recommended) This is the simplest and safest solution, especially if you do not have a dedicated NVIDIA GPU. It avoids the need for any CUDA or cuDNN libraries.
```
pip uninstall torch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
```
Option B: Install the Full CUDA Toolkit and cuDNN (If you have an NVIDIA GPU) If your machine has a compatible NVIDIA GPU and you want to use it for training, you'll need to install the full CUDA Toolkit and the cuDNN library. This is a more complex process and is not covered in detail in this guide. You should refer to NVIDIA's official documentation for instructions on how to install the appropriate versions of CUDA and cuDNN for your system.
First Run and Configuration Bootstrap On the first start, the application checks for config/default.yaml. If the file does not exist, it creates the config/ directory and copies base_config.yaml to config/default.yaml.
```
sudo python3 main.py
```
If the configuration file was just created, the application exits after printing a message. Open config/default.yaml, set the parameters you need, and restart the application.

Pay special attention to server_user: this is the account the application switches to before creating training folders and later regaining root privileges for Mininet setup.

After the initial configuration is in place, run the same command again to start the Mininet simulation, run the environment, and begin the training process.
OpenDayLight (ODL) Controller Setup (Optional) For installing the OpenDayLight controller, follow the instructions provided in the ODL-Ubuntu22-installation guide. This project was developed with ODL Karaf version 0.8.4.

You might also use a Docker container for ODL. To start an OpenDayLight controller container:
```
docker run -d -t -v ~/.m2:/root/.m2/ -p 6633:6633 -p 8101:8101 -p 8181:8181 --net=bridge --hostname=ovsdb-cluster-node-1 --name=opendaylight opendaylight/opendaylight:0.18.2 [https://github.com/sfuhrm/docker-opendaylight](https://github.com/sfuhrm/docker-opendaylight)
```
To connect via SSH to the ODL controller inside the Docker container on a virtual machine (e.g., 192.168.1.226):
```
ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null admin@192.168.1.226 -p 8101
```
Ensure your JAVA_PATH is correctly set, especially if you are running ODL directly and not via Docker.
```
echo 'export JAVA_PATH=/usr/lib/jvm/java-21-openjdk-amd64/bin/java' >> ~/.bashrc
source ~/.bashrc
```
Adjust the path to your Java installation accordingly.

(back to top)

Usage

Once the application is running (sudo python3 main.py), open a browser and navigate to:

http://<host>:5000

The web UI is organised into three panels accessible from the top navigation bar:

Panel	Purpose
Configuration Setup	Define topology, scenario, agents and all hyperparameters
Training Dashboard	Monitor reward, accuracy and host-status in real time via WebSocket
Results Panel	Inspect per-agent metrics, confusion matrices, radar charts; export PDF

Configuring an Experiment

All experiment parameters are stored in config/default.yaml and can be edited live from the Configuration Setup panel without restarting the application.

Key configuration sections:

env_params.gym_type — selects the scenario: classification, attacks, attacks_ho, marl_attacks, marl_pz (and *_from_dataset variants).
env_params.episodes / max_steps — control experiment length.
env_params.attacks — tune attack probability, duration and SDN blocking behaviour.
env_params.communication — (marl_pz only) select the inter-agent communication strategy: none, naive_broadcast, uaq, federated_sync, policy_exchange, experience_sharing.
env_params.pettingzoo — (marl_pz only) PettingZoo Parallel API settings: local_ratio, shared_reward, max_cycles.
env_params.net_params — set topology size (hosts, IoT nodes) and OpenDayLight controller address.
agents — add one or more agents (Q-Learning, SARSA, DQN, PPO, A2C, Supervised) with independent hyperparameters.

Full parameter reference — open the application, click the ? User Manual button in the top navigation bar, and navigate to the Full Configuration Reference section for a complete description of every parameter, including attack thresholds, exploration schedules and algorithm-specific hyperparameters.

Additional Pages

URL	Description
`http://<host>:5000/screensaver.html`	Auto-advancing presentation slideshow (AAMAS 2026)
`http://<host>:5000/video.html`	Embedded demo video player

(back to top)

Roadmap

Phase 1 — Foundation · Sept 2024

Terminal-based application architecture
Mininet topology emulation (OVS switch · hosts · IoT nodes)
OpenDayLight REST API integration and flow-rule management
Traffic Classification environment (Gym Env #1) — 4-class: None / Ping / UDP / TCP
Tabular agents: Q-Learning, SARSA (log-bin state discretisation)

Phase 2 — Attack Detection Scenarios · late 2024

Attack-Net environment — binary Normal / Attack detection at network level
Attack-PerHost environment — per-host Normal / Victim / Attacker with SDN link blocking
Deep RL agents via Stable-Baselines3: DQN, PPO, A2C
Publication on SoftwareX Elsevier MininetGym: A modular SDN-based simulation environment for reinforcement learning in cybersecurity https://www.sciencedirect.com/science/article/pii/S235271102500278X

Phase 3 — First Publication · Jan – Jul 2025

Systematic evaluation across Classification and Attack-PerHost environments
Metrics pipeline: Accuracy, F1, Mitigation Ratio, False Negative Rate, Attack Latency
ICAART 2025 paper submission with first experimental results (July 2025)
Publication for ICAART conference SciTePress Experiences in Exploiting Reinforcement Learning for Network Traffic Classification and Attack Detection https://scholar.google.com/scholar?oi=bibs&cluster=16065980299158333333&btnI=1&hl=it

Phase 4 — Web Dashboard · 2025 (parallel)

Flask + Socket.IO real-time web UI
Live training charts via WebSocket (reward, accuracy, ε-decay)
Host-status monitor with SDN block visualisation
Mobile-responsive layout
Experiment PDF export (charts + metrics + config)
Save / load YAML configuration from browser
Scenario management: generate, preview, load from file

Phase 5 — Enhanced Scenarios & MARL · Sept 2025 – May 2026

Phase 6 — AAMAS 2026 · Dec 2025 – May 2026

Demo video production and YouTube publication
AAMAS 2026 paper — live demonstration of RL-based cybersecurity training (Paphos, Cyprus)
Screensaver presentation for conference booth
QR-code video integration in screensaver

Upcoming

Communication architecture axis (paper 7 §Communication Architecture): peer-to-peer vs. hierarchical (cluster-head aggregation for large IoT topologies), orthogonal to and applicable to any Tier B strategy — not a strategy of its own
S2–S4 support for SB3 deep agents (DQN weight averaging, prioritised experience replay sharing)
Docker Compose one-command deployment (Mininet + ODL + MininetGym)
Additional attack types: Slowloris, DNS amplification
Curriculum learning: progressive difficulty ramp across episodes
Multi-switch topologies and inter-domain MARL

(back to top)

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request, or simply open an issue with the tag enhancement.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

(back to top)

Acknowledgments

This section is not yet filled out.