MockDNS - Simple DNS Server

A lightweight and configurable DNS server implementation in Python that supports local records, caching, recursive queries, and fallback resolution.

Command Line Arguments

usage: mockdns.py [-h] [--host HOST] [--port PORT] [--records RECORDS] [--log LOG]

Simple DNS Server

optional arguments:
  -h, --help         show this help message and exit
  --host HOST        Host to bind to
  --port PORT        Port to bind to
  --records RECORDS  Path to DNS records JSON file
  --log LOG         Log file path (optional)

Configuration

The server uses a JSON configuration file. Here's a complete example of the configuration:

{
  "settings": {
    "default_dns_servers": [
      "8.8.8.8",
      "8.8.4.4"
    ],
    "enable_fallback": true,
    "fallback_ips": {
      "A": "127.0.0.1",
      "AAAA": "::1"
    },
    "ttl": 60,
    "enable_recursive_query": true,
    "enable_cache": true,
    "cache_ttl": 600
  },
  "records": {
    "example.com": {
      "A": ["93.184.216.34", "93.184.216.35"],
      "AAAA": ["2606:2800:220:1:248:1893:25c8:1946"],
      "MX": [
        {"preference": 10, "exchange": "mail1.example.com"},
        {"preference": 20, "exchange": "mail2.example.com"}
      ],
      "CNAME": ["www.example.com"]
    },
    "test.com": {
      "A": ["192.0.2.1"],
      "TTL": 300
    },
    "*.example.com": {
      "A": ["93.184.216.36"],
      "TTL": 120
    }
  }
}

Settings Explanation

• default_dns_servers: List of upstream DNS servers for recursive queries (default: Google DNS servers)
• enable_fallback: When true, returns fallback IPs for unresolved queries
• fallback_ips: Defines default IP addresses for A and AAAA records when resolution fails
• ttl: Default Time To Live in seconds for DNS records
• enable_recursive_query: Enables querying upstream DNS servers for unknown records
• enable_cache: Enables caching of DNS responses
• cache_ttl: How long (in seconds) to keep records in cache

Record Types Supported

The server supports the following DNS record types:

• A: IPv4 addresses
• AAAA: IPv6 addresses
• MX: Mail exchange records
• CNAME: Canonical name records

Wildcard Domains

You can use wildcard domains (e.g., *.example.com) to match any subdomain. In the example above, any undefined subdomain of example.com will resolve to 93.184.216.36.

Basic Usage

1. Create a configuration file (e.g., records.json) with your DNS records

2. Start the server:

python mockdns.py --records records.json

3. To run on a specific host and port:

python mockdns.py --host 127.0.0.1 --port 5353 --records records.json

4. To enable logging to a file:

python mockdns.py --records records.json --log dns_server.log

Note: To bind to port 53 (default DNS port), you need root privileges:

sudo python mockdns.py --records records.json

Features

• Local DNS record hosting
• Support for A, AAAA, MX, and CNAME records
• DNS response caching with configurable TTL
• Recursive query support
• Fallback IP resolution
• Wildcard domain support
• Real-time query monitoring
• Detailed statistics
• Configurable logging

Requirements

• Python 3.7+
• Required packages:
  • rich
  • dnspython

Installation

Install the required packages:

pip install rich dnspython

License

This project is open source and available under the MIT License.