# b1rh0ut/sdn-ml-ddos-mitigation architecture

> Architecture diagram of the GitHub repository b1rh0ut/sdn-ml-ddos-mitigation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/b1rh0ut/sdn-ml-ddos-mitigation
- Repository: https://github.com/b1rh0ut/sdn-ml-ddos-mitigation

## Overview

This is an SDN-based DDoS detection and mitigation system: a Ryu controller polls switch flow statistics, applies a threshold fast path and ML classification, then installs network-wide blocking rules. The repository also supports topology provisioning, training/evaluation from real or synthetic datasets, and operational monitoring. Runtime controller details are only partially sampled; major additional capabilities and their broad module paths are retained from the README and tree, with uncertain call wiring omitted.

Main entry points: [`src/sdn_ddos_detector/controller/ddos_controller.py`](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py) (Ryu controller), [`src/sdn_ddos_detector/ml/train.py`](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/train.py) (Model training), [`src/sdn_ddos_detector/topology/topology.py`](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/topology/topology.py) (Spine-leaf topology), [`src/sdn_ddos_detector/controller/api_auth.py`](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/api_auth.py) (Bearer authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_network["Network fabric"]
  node_switches["OpenFlow switches"]
  node_topology["Spine-leaf topology<br/>[topology.py]"]
  node_normalgen["Normal traffic generator<br/>[generate_normal.py]"]
  node_attackgen["Attack traffic"]
end

subgraph group_detection["Detection and control"]
  node_controller["Ryu controller<br/>[ddos_controller.py]"]
  node_auth["Bearer authentication<br/>[api_auth.py]"]
  node_features["Flow features"]
  node_threshold["Threshold fast path<br/>[ddos_controller.py]"]
  node_classifier["RF inference<br/>[ddos_controller.py]"]
  node_breaker["Circuit breaker<br/>[circuit_breaker.py]"]
  node_drift["Drift detection<br/>[drift_detector.py]"]
  node_mitigation["Network mitigation<br/>[ddos_controller.py]"]
end

subgraph group_mlops["ML data lifecycle"]
  node_datasets["Dataset sources"]
  node_adapters["Dataset adapters"]
  node_synthetic["Synthetic data"]
  node_training["Model training<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[evaluation.py]"]
  node_collector["Flow data collection"]
end

subgraph group_operations["Operations"]
  node_metrics["Performance monitor"]
  node_config["Controller configuration<br/>[ryu.conf]"]
end

node_operator(("Network operator"))
node_traffic(("Network traffic"))
node_api(("REST API client"))

node_operator -->|"starts network"| node_topology
node_topology -->|"creates fabric"| node_switches
node_traffic -->|"sends traffic"| node_switches
node_normalgen -->|"generates traffic"| node_switches
node_attackgen -->|"generates attacks"| node_switches
node_switches -->|"flow statistics"| node_controller
node_controller -->|"polls statistics"| node_switches
node_controller -->|"extracts features"| node_features
node_controller -->|"checks rates"| node_threshold
node_controller -->|"classifies batches"| node_classifier
node_controller -->|"guards inference"| node_breaker
node_controller -->|"monitors drift"| node_drift
node_controller -->|"dispatches blocks"| node_mitigation
node_mitigation -->|"installs DROP rules"| node_switches
node_controller -.->|"records flows"| node_collector
node_api -->|"sends requests"| node_auth
node_auth -->|"authorizes access"| node_controller
node_operator -->|"obtains datasets"| node_datasets
node_datasets -->|"provides files"| node_adapters
node_adapters -->|"maps features"| node_training
node_synthetic -->|"provides samples"| node_training
node_training -->|"produces model"| node_classifier
node_training -->|"supplies model"| node_evaluation
node_features -->|"defines schema"| node_training
node_operator -->|"runs monitoring"| node_metrics
node_metrics -.->|"queries flow state"| node_switches
node_config -->|"configures behavior"| node_controller

click node_topology "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/topology/topology.py"
click node_normalgen "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/traffic/generate_normal.py"
click node_attackgen "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/traffic/attack_generator.sh"
click node_controller "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py"
click node_auth "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/api_auth.py"
click node_features "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/feature_engineering.py"
click node_threshold "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py"
click node_classifier "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py"
click node_breaker "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/circuit_breaker.py"
click node_drift "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/drift_detector.py"
click node_mitigation "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py"
click node_datasets "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/tree/main/src/sdn_ddos_detector/datasets"
click node_adapters "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/tree/main/src/sdn_ddos_detector/ml/dataset_adapters"
click node_synthetic "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/generate_synthetic_dataset.py"
click node_training "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/train.py"
click node_evaluation "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/evaluation.py"
click node_collector "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/utils/dataset_collector.py"
click node_metrics "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/utils/performance_monitor.py"
click node_config "https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/config/ryu.conf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_switches,node_topology,node_normalgen,node_attackgen,node_api toneBlue
class node_controller,node_auth,node_features,node_threshold,node_classifier,node_breaker,node_drift,node_mitigation toneAmber
class node_datasets,node_adapters,node_synthetic,node_training,node_evaluation,node_collector toneMint
class node_metrics,node_config toneRose
class node_operator,node_traffic toneIndigo
```

## Components

### Network fabric

- **OpenFlow switches**
- [Spine-leaf topology](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/topology/topology.py): `src/sdn_ddos_detector/topology/topology.py`
- [Normal traffic generator](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/traffic/generate_normal.py): `src/sdn_ddos_detector/traffic/generate_normal.py`
- [Attack traffic](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/traffic/attack_generator.sh): `src/sdn_ddos_detector/traffic/attack_generator.sh`

### Detection and control

- [Ryu controller](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py): `src/sdn_ddos_detector/controller/ddos_controller.py`
- [Bearer authentication](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/api_auth.py): `src/sdn_ddos_detector/controller/api_auth.py`
- [Flow features](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/feature_engineering.py): `src/sdn_ddos_detector/ml/feature_engineering.py`
- [Threshold fast path](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py): `src/sdn_ddos_detector/controller/ddos_controller.py`
- [RF inference](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py): `src/sdn_ddos_detector/controller/ddos_controller.py`
- [Circuit breaker](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/circuit_breaker.py): `src/sdn_ddos_detector/ml/circuit_breaker.py`
- [Drift detection](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/drift_detector.py): `src/sdn_ddos_detector/ml/drift_detector.py`
- [Network mitigation](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/controller/ddos_controller.py): `src/sdn_ddos_detector/controller/ddos_controller.py`

### ML data lifecycle

- [Dataset sources](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/tree/main/src/sdn_ddos_detector/datasets): `src/sdn_ddos_detector/datasets`
- [Dataset adapters](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/tree/main/src/sdn_ddos_detector/ml/dataset_adapters): `src/sdn_ddos_detector/ml/dataset_adapters`
- [Synthetic data](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/generate_synthetic_dataset.py): `src/sdn_ddos_detector/ml/generate_synthetic_dataset.py`
- [Model training](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/train.py): `src/sdn_ddos_detector/ml/train.py`
- [Model evaluation](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/ml/evaluation.py): `src/sdn_ddos_detector/ml/evaluation.py`
- [Flow data collection](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/utils/dataset_collector.py): `src/sdn_ddos_detector/utils/dataset_collector.py`

### Operations

- [Performance monitor](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/utils/performance_monitor.py): `src/sdn_ddos_detector/utils/performance_monitor.py`
- [Controller configuration](https://github.com/b1rh0ut/sdn-ml-ddos-mitigation/blob/main/src/sdn_ddos_detector/config/ryu.conf): `src/sdn_ddos_detector/config/ryu.conf`

### Other components

- **Network operator**
- **Network traffic**
- **REST API client**

## Connections

- Network operator → Spine-leaf topology: starts network
- Spine-leaf topology → OpenFlow switches: creates fabric
- Network traffic → OpenFlow switches: sends traffic
- Normal traffic generator → OpenFlow switches: generates traffic
- Attack traffic → OpenFlow switches: generates attacks
- OpenFlow switches → Ryu controller: flow statistics
- Ryu controller → OpenFlow switches: polls statistics
- Ryu controller → Flow features: extracts features
- Ryu controller → Threshold fast path: checks rates
- Ryu controller → RF inference: classifies batches
- Ryu controller → Circuit breaker: guards inference
- Ryu controller → Drift detection: monitors drift
- Ryu controller → Network mitigation: dispatches blocks
- Network mitigation → OpenFlow switches: installs DROP rules
- Ryu controller → Flow data collection: records flows
- REST API client → Bearer authentication: sends requests
- Bearer authentication → Ryu controller: authorizes access
- Network operator → Dataset sources: obtains datasets
- Dataset sources → Dataset adapters: provides files
- Dataset adapters → Model training: maps features
- Synthetic data → Model training: provides samples
- Model training → RF inference: produces model
- Model training → Model evaluation: supplies model
- Flow features → Model training: defines schema
- Network operator → Performance monitor: runs monitoring
- Performance monitor → OpenFlow switches: queries flow state
- Controller configuration → Ryu controller: configures behavior