NetDefender is a comprehensive network defense and traffic redirection platform that seamlessly integrates Software-Defined Networking (SDN) and Intrusion Detection Systems (IDS).
- Core Controller: Built on the OSKen controller framework
- Packet Forwarding: Utilizes Open vSwitch (OVS) for intelligent packet forwarding and policy enforcement
- Intrusion Detection: Integrates with Snort IDS for real-time threat detection
- Dynamic Traffic Redirection: Automatically redirects suspicious traffic to containerized honeypots
- Container Orchestration: Supports basic container lifecycle management for honeypot services
- Extensible Policies: Flexible policy framework for customizable defense strategies
NetDefender supports two deployment modes. Choose one:
-
Ryu + Snort (Two-Server Deployment)
- Ubuntu 22.04+
- Python 3.9+ (both servers)
- Memory 2GB+
-
Single-Server Deployment
- Ubuntu 22.04+
- Python 3.9+
- Memory 2GB+
Installation Order: The Ryu server must be installed and configured before the Snort server.
Internet Connection: Ensure both servers have active internet connectivity before beginning the installation process.
Comment Syntax: Lines beginning with
#are comments in configuration files.
The following diagram illustrates the NetDefender network topology:
NetDefender uses a JSON-based configuration file to define honeypot containers. The configuration supports multiple honeypot types with flexible port mapping.
{
"containers": [
{
"image_name": "cowrie/cowrie",
"name": "ssh",
"ports": [
{
"host_port": 22,
"container_port": 2222,
"protocol": "tcp"
}
],
"command": "",
"multi": "yes",
"max": 10,
"max_containers": 10,
"send_response": "yes"
},
{
"image_name": "dinotools/dionaea",
"name": "dionaea",
"ports": [
{"host_port": 21, "container_port": 21, "protocol": "tcp"},
{"host_port": 42, "container_port": 42, "protocol": "tcp"},
{"host_port": 69, "container_port": 69, "protocol": "udp"},
{"host_port": 80, "container_port": 80, "protocol": "tcp"},
{"host_port": 135, "container_port": 135, "protocol": "tcp"},
{"host_port": 443, "container_port": 443, "protocol": "tcp"},
{"host_port": 445, "container_port": 445, "protocol": "tcp"},
{"host_port": 1433, "container_port": 1433, "protocol": "tcp"},
{"host_port": 1723, "container_port": 1723, "protocol": "tcp"},
{"host_port": 1883, "container_port": 1883, "protocol": "tcp"},
{"host_port": 1900, "container_port": 1900, "protocol": "udp"},
{"host_port": 3306, "container_port": 3306, "protocol": "tcp"},
{"host_port": 5060, "container_port": 5060, "protocol": "tcp"},
{"host_port": 5060, "container_port": 5060, "protocol": "udp"},
{"host_port": 5061, "container_port": 5061, "protocol": "tcp"},
{"host_port": 11211, "container_port": 11211, "protocol": "tcp"}
],
"command": "",
"multi": "yes",
"max": 10,
"max_containers": 10,
"send_response": "yes"
}
]
}| Parameter | Type | Required | Description |
|---|---|---|---|
image_name |
String | Yes | Docker image name for the honeypot container |
name |
String | Yes | Unique identifier for the container instance |
ports |
Array | Yes | Array of port mapping objects defining network access |
command |
String | No | Additional Docker command-line arguments (Delete this line if it is not needed) |
multi |
String | No | Enable multiple container instances (yes/no) (Default: no) |
max |
Integer | No | Maximum number of concurrent connections per container (Default: 10) |
max_containers |
Integer | No | Maximum total number of container instances allowed (Primary is not included) (Default: 10) |
send_response |
String | No | Whether the honeypot should send response packets (yes/no) (Default: no) |
Each object in the ports array must contain the following fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
host_port |
Integer | Yes | The external network port where incoming packets are received |
container_port |
Integer | Yes | The internal container port for traffic redirection |
protocol |
String | Yes | Network protocol (tcp or udp) |
Purpose: Emulates an SSH/Telnet service to capture brute-force attacks and shell interactions.
- Image:
cowrie/cowrie - Monitored Port: 22 (SSH)
- Internal Port: 2222
- Use Case: Capturing SSH login attempts, commands, and file downloads
Purpose: A comprehensive honeypot that emulates multiple vulnerable services simultaneously.
- Image:
dinotools/dionaea - Monitored Services:
- FTP (21): File Transfer Protocol
- WINS (42): Windows Internet Name Service
- TFTP (69, UDP): Trivial File Transfer Protocol
- HTTP (80): Web traffic
- RPC (135): Remote Procedure Call
- HTTPS (443): Secure web traffic
- SMB (445): Server Message Block
- MSSQL (1433): Microsoft SQL Server
- PPTP (1723): Point-to-Point Tunneling Protocol
- MQTT (1883): Message Queuing Telemetry Transport
- UPnP (1900, UDP): Universal Plug and Play
- MySQL (3306): MySQL Database
- SIP (5060, TCP/UDP & 5061): Session Initiation Protocol
- Memcached (11211): Distributed memory caching system
- Run as root user
- Enable promiscuous mode on the virtual network interface:
chmod a+rw /dev/vmnet0
This is required for NetDefender to capture network traffic in promiscuous mode.
Please refer to the following URL:Promiscuous Mode for Linux Virtual Adapters
If you plan to install Ryu via SSH, it is recommended to use the second network interface. A second network interface is optional. If you only have one network interface, after the installation is complete, clear the existing OpenFlow rules with:
ovs-ofctl del-flows br0 -O OpenFlow13
Then restart the Ryu controller and reconnect to Snort.
Execute the following commands to install the Ryu controller:
# Switch to root user
sudo -s
# Install Git
apt install git -y
# Clone the NetDefender repository
git clone https://github.com/sinyuan1022/NetDefender.git
# Navigate to the Ryu directory
cd ./NetDefender/ryu/
# Run the Ryu installation script
bash ./ryu_install.sh
#If you want to start it manually, please change the directory to `/NetDefender/ryu/` first, then execute:
osken-manager ovs.py
Prerequisites: Complete the Ryu server installation first.
Execute the following commands to install the Snort IDS:
# Switch to root user
sudo -s
# Install Git
apt install git -y
# Clone the NetDefender repository
git clone https://github.com/sinyuan1022/NetDefender.git
# Navigate to the Snort directory
cd ./NetDefender/snort/
# Run the Snort installation script
bash ./snort_install.sh
#If you want to start it manually, please change the directory to `/NetDefender/snort/` first, then execute:
#INTERFACE = monitor interface name (e.g., ens33)
snort -i $INTERFACE -A unsock -l /tmp -c /etc/snort/snort.conf
python3 pigrelay.pyNote: Use this option only if you want to combine both Ryu and Snort on a single server.
# Switch to root user
sudo -s
# Install Git
apt install git -y
# Clone the NetDefender repository
git clone https://github.com/sinyuan1022/NetDefender.git
# Navigate to the root directory
cd ./NetDefender/
# Run the combined installation script
bash ./singel.sh
#If you want to start it manually, please change the directory to `/NetDefender/ryu/` first, then execute:
#INTERFACE = monitor interface name (e.g., ens33)
snort -i $INTERFACE -A unsock -l /tmp -c /etc/snort/snort.conf
osken-manager ovs.py
If you see the following message:
[snort][INFO] Connect with ...
it means the controller has successfully connected to the Snort Server.
- Dual-server mode: This message should appear after the connection is established.
- Single-server mode: This message will not appear, because the controller communicates with Snort through a local Unix socket instead of a remote IP connection.
Important: In Single-server mode, make sure the
unixsockoption is set toTrue.
If you see output similar to the following:
New active IP 192.168.1.101 for service dionaea. Total active IPs: 1
Service dionaea configuration: max IPs per container=10, max containers=10
Assigned client 192.168.1.101 to primary container dionaea0, current IP count: 1/10
New active IP 192.168.1.101 for service ssh. Total active IPs: 1
Service ssh configuration: max IPs per container=10, max containers=10
Assigned client 192.168.1.101 to primary container ssh0, current IP count: 1/10
It indicates that the controller has successfully assigned the client connection to the correct container. The output provides the following information:
- Service name (e.g.,
dionaea,ssh) - Total active connections for the service
- Maximum IPs (connections) allowed per container
- **Current maximum connection capacity. Additional containers will be automatically created when the capacity is insufficient
- Assigned container handling the client connection
- Current number of connections assigned to the container (e.g.,
1/10)
When the text above appears, it means that Snort has detected a malicious packet.
Since there is no corresponding service for this packet, it is not redirected to a container.
Instead, the packet is saved.
The packet is saved under:NetDefender/ryu/other
If you see the following message:
INFO:__main__:Start the network socket client....
When this line appears, it means that the Snort server has successfully connected to the Ryu server.
Single-Port Honeypots: Use when targeting specific services like SSH or Telnet.
{
"image_name": "cowrie/cowrie",
"name": "ssh",
"ports": [
{"host_port": 22, "container_port": 2222, "protocol": "tcp"}
]
}Multi-Port Honeypots: Use when simulating comprehensive network services or vulnerable servers.
{
"image_name": "dinotools/dionaea",
"name": "dionaea",
"ports": [
{"host_port": 80, "container_port": 80, "protocol": "tcp"},
{"host_port": 443, "container_port": 443, "protocol": "tcp"}
]
}multi: "yes": Enables dynamic container spawning for high-traffic scenariosmax: 10: Limits concurrent connections per container to prevent resource exhaustionmax_containers: 10: Sets an upper bound on total container instances
send_response: "yes": Honeypot actively responds to attackers (more realistic)send_response: "no": Silent monitoring mode (useful for specific detection scenarios)
- Traffic Monitoring: Open vSwitch forwards network traffic to the Ryu controller
- Threat Detection: Snort IDS analyzes traffic patterns and generates alerts
- Policy Evaluation: The controller evaluates traffic against configured policies
- Port Matching: Incoming traffic is matched against configured
host_portvalues - Dynamic Redirection: Suspicious traffic is redirected to appropriate honeypot containers
- Container Management: The system automatically spawns and manages honeypot instances based on load
- Response Generation: Honeypots interact with attackers while logging all activities
- Data Collection: All interactions are captured for analysis and threat intelligence
Create controlled environments for studying attack patterns, malware behavior, and exploitation techniques across multiple protocols.
Collect and analyze malicious traffic data from SSH brute-force attempts, SMB exploits, SQL injection attacks, and IoT botnet activities.
Implement proactive defense mechanisms by redirecting attackers to honeypots while protecting production systems.
- Repository: https://github.com/sinyuan1022/NetDefender
- OSKen/Ryu Documentation: Component-based SDN controller framework (OSKen)
- pigrelay: Open Unix Domain Socket for Snort(NIDS) and send to Network socket (pigrelay)
- Open vSwitch: Production-quality multilayer virtual switch (Open vSwitch)
- Docker Plugin: A Docker network plugin that allocates container IP addresses (docker-net-dhcp)
- Snort: Open-source network intrusion detection and prevention system (Snort)
- Cowrie: SSH/Telnet honeypot designed to log brute-force attacks (Cowrie)
- Dionaea: Low-interaction honeypot that captures malware and exploits (Dionaea)
For issues, questions, or contributions, please visit the GitHub repository.