DNS Tunnel Simulator

A comprehensive DNS tunneling simulator that enables you to create, monitor, and analyze DNS tunnel traffic. The system supports multiple popular DNS tunneling tools (dnscat2, iodine) through an extensible plugin architecture.

Features

• Multiple DNS Tunnel Tools: Support for dnscat2, iodine, and extensible to more tools
• Docker Isolation: Each tunnel session runs in isolated Docker containers
• Traffic Capture: Automatic PCAP file generation for analysis
• Detailed Analysis: Extract DNS queries, subdomains, timing, and decoded data
• Web Interface: Modern React-based UI for tunnel management and traffic visualization
• REST API: Full-featured API for programmatic control
• Real-time Updates: WebSocket support for live traffic monitoring
• Extensible Architecture: Plugin-based system for adding new tunnel tools

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     React Frontend                          │
│  - Tunnel configuration UI                                   │
│  - Real-time traffic dashboard                               │
│  - PCAP viewer/download                                      │
└────────────────────┬────────────────────────────────────────┘
                     │ WebSocket + REST API
┌────────────────────▼────────────────────────────────────────┐
│                  FastAPI Backend                             │
│  - Tunnel management service                                 │
│  - Docker container orchestration                            │
│  - Traffic capture & analysis                                │
│  - WebSocket for real-time updates                           │
└───┬──────────────┬──────────────┬───────────────────────────┘
    │              │              │
┌───▼────┐  ┌─────▼─────┐  ┌────▼────────┐
│ Docker │  │  SQLite   │  │ PCAP Storage│
│ Engine │  │ Database  │  │   (/pcaps)  │
└────────┘  └───────────┘  └─────────────┘

Quick Start

Prerequisites

• Docker (version 20.10+)
• Docker Compose (version 2.0+)
• Python 3.11+ (for local development)
• Node.js 20+ (for local development)

Using Docker Compose (Recommended)

1. Clone the repository:

git clone <repository-url>
cd tunnel-sim

2. Start the application:

docker-compose up -d

3. Access the web interface:

http://localhost:3000

4. Access the API documentation:

http://localhost:8000/docs

Local Development

Backend:

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the backend
python -m app.main

Frontend:

cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

Usage

Creating a Tunnel

1. Navigate to the web interface at http://localhost:3000
2. Click "Create Tunnel"
3. Select a tool (dnscat2 or iodine)
4. Configure parameters:
   • Domain: The domain to use for tunneling (e.g., example.com)
   • Tool-specific settings: Port, passwords, etc.
5. Click "Create"

Monitoring Traffic

1. From the tunnel list, click "View" on a running tunnel
2. View real-time traffic in the dashboard:
   • Traffic Records: Tab showing all DNS queries/responses
   • Subdomains: List of unique DNS subdomains used
   • Statistics: Query types, volume, timing info

Downloading PCAP Files

1. Click on a tunnel to view its details
2. Click the "Download PCAP" button
3. PCAP files can be analyzed with Wireshark or other tools

Supported Tools

DNSCat2

Creates a secure command channel through DNS with support for encryption.

Parameters:

• domain (required): Domain for tunneling
• port (optional): DNS port (default: 53)
• secret (optional): Encryption passphrase

Iodine

Tunnels full IPv4 traffic through DNS, creating a virtual network interface.

Parameters:

• domain (required): Domain for tunneling
• password (optional): Tunnel password
• mtu (optional): Maximum transmission unit (default: 1024)
• port (optional): DNS port (default: 53)

Adding New Tools

The simulator supports easy extension with new DNS tunneling tools. See docs/ADDING_TOOLS.md for detailed instructions.

Basic steps:

1. Create a new tool class inheriting from DNSTunnelTool
2. Implement required methods (get_name, build_server_command, etc.)
3. Create Dockerfiles for server and client
4. Register the tool in the registry

API Documentation

Interactive API documentation is available when running the backend:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

See docs/API.md for complete API reference.

Project Structure

tunnel-sim/
├── backend/                 # Python FastAPI backend
│   ├── app/
│   │   ├── api/            # API routes
│   │   ├── core/           # Business logic
│   │   ├── models/         # Database models
│   │   ├── tools/          # DNS tunnel tool implementations
│   │   ├── main.py         # FastAPI application
│   │   └── database.py     # Database connection
│   ├── requirements.txt
│   └── Dockerfile
│
├── frontend/                # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── services/       # API client
│   │   └── types/          # TypeScript definitions
│   ├── package.json
│   └── Dockerfile
│
├── docker/                  # Docker infrastructure
│   ├── dnscat2/           # DNSCat2 Dockerfiles
│   └── iodine/            # Iodine Dockerfiles
│
├── docs/                    # Documentation
│   ├── ARCHITECTURE.md     # System architecture
│   ├── API.md              # API documentation
│   └── ADDING_TOOLS.md     # Tool extension guide
│
├── pcaps/                   # Stored PCAP files
├── docker-compose.yml
└── README.md

Documentation

• Architecture Overview - System design and component details
• API Reference - Complete API documentation
• Adding Tools Guide - How to extend with new tools

Development

Running Tests

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

Building Tool Images

Tool images are built on-demand when creating tunnels. To manually build:

# Build dnscat2 server image
docker build -t tunnel-sim/dnscat2-server:latest -f docker/dnscat2/server/Dockerfile .

# Build iodine client image
docker build -t tunnel-sim/iodine-client:latest -f docker/iodine/client/Dockerfile .

Security Considerations

This tool is designed for:

• Educational purposes
• Security research and testing
• C2 (Command and Control) simulation in authorized environments
• Network traffic analysis training

Important: Use only on networks and systems you own or have explicit authorization to test.

Troubleshooting

Containers won't start

• Ensure Docker daemon is running
• Check that ports 53, 8000, 3000 are available
• Verify Docker-in-Docker is working: docker run hello-world

Traffic not captured

• Verify tcpdump is installed in containers
• Check PCAP directory permissions
• Ensure container has access to /capture volume

Frontend can't connect to backend

• Verify CORS settings in backend config
• Check API URL in frontend environment variables
• Ensure both services are on the same Docker network

Contributing

Contributions are welcome! Areas for contribution:

• Additional DNS tunnel tool implementations
• Enhanced traffic analysis features
• UI/UX improvements
• Bug fixes and performance optimizations

License

This project is provided as-is for educational and research purposes.

Acknowledgments

• DNSCat2 - DNS tunneling tool
• Iodine - IP over DNS tunnel
• FastAPI - Modern Python web framework
• React - UI library
• Scapy - Packet manipulation library