NinjaDoH A Censorship-Resistant DNS over HTTPS System

Overview

NinjaDoH is a censorship-resistant DNS over HTTPS (DoH) system that dynamically rotates server IP addresses and query paths using IPFS/IPNS, making it extremely difficult for censors to block. By eliminating static domain names and continuously changing endpoints, NinjaDoH stays ahead of detection mechanisms while maintaining performance comparable to traditional DoH services.

Screenshot

The NinjaDoH client dashboard showing real-time connectivity status, latency statistics, and IP address resolution. The right panel demonstrates successful DNS over HTTPS connectivity verification.

Features

• Dynamic IP Rotation: Server IP addresses rotate automatically using AWS Elastic IPs
• IPFS/IPNS Integration: Server endpoints are published via IPNS, eliminating static domain names
• Dynamic Query Paths: Query paths change with each rotation, defeating path-based blocking
• Censorship Resistance: Designed to evade both list-based and ML-based detection systems
• Real-time Updates: Clients automatically discover new server endpoints via IPNS pubsub
• Performance Monitoring: Built-in latency tracking and connectivity monitoring
• Easy Deployment: Simple setup scripts for both server and client components

Architecture

NinjaDoH consists of two main components:

Server Component

• Runs on AWS EC2 with multiple network interfaces
• Rotates Elastic IPs between network interfaces
• Publishes new IP addresses and query paths to IPFS/IPNS
• Generates SSL certificates for each new IP address
• Runs AdGuard Home as the DoH server

Client Component

• Resolves IPNS keys to discover current server endpoints
• Updates dnscrypt-proxy configuration automatically
• Monitors connectivity and latency
• Provides real-time dashboard for status monitoring

┌─────────────┐         ┌──────────┐         ┌─────────────┐
│   Client    │────────▶│   IPFS   │────────▶│   Server    │
│             │         │  /IPNS   │         │  (AWS EC2)  │
└─────────────┘         └──────────┘         └─────────────┘
     │                                           │
     │                                           │
     └──────────── DoH Queries ──────────────────┘

Quickstart

Prerequisites

Server:

• AWS account with EC2 access
• EC2 instance with multiple network interfaces
• IPFS node installed and running
• AdGuard Home installed
• Python 3.7+

Client:

• Linux system
• IPFS node installed and running
• dnscrypt-proxy installed
• Python 3.7+

Server Setup

1. Install IPFS and generate IPNS key:

   # Install IPFS (if not already installed)
   # Follow instructions at https://docs.ipfs.io/install/
   
   # Initialize IPFS node
   ipfs init
   
   # Start IPFS daemon
   ipfs daemon
   
   # Generate IPNS key (save the key ID for client configuration)
   ipfs key gen ninjadoh-key

2. Generate root CA certificate:

   bash generate_rootCA.sh

3. Configure AWS credentials:

   export AWS_ACCESS_KEY_ID=your_access_key
   export AWS_SECRET_ACCESS_KEY=your_secret_key
   export AWS_DEFAULT_REGION=us-east-2

4. Set required environment variables:

   # Required: your EC2 instance ID (with ladder2/ladder3 interfaces)
   export NINJADOH_EC2_INSTANCE_ID=i-xxxxxxxxxxxxxxxxx
   # Required: your IPNS key ID (from: ipfs key gen ninjadoh-key)
   export NINJADOH_IPNS_NAME=k51q...
   # Optional overrides:
   # export NINJADOH_AWS_REGION=us-east-2
   # export NINJADOH_CERT_DIR=/home/ubuntu/adguard/certs/
   # export NINJADOH_IPFS_API_URL=http://127.0.0.1:5001/api/v0

   Ensure network interface descriptions are set to ladder2 and ladder3 in AWS for the instance.

5. Set up IP rotation:

   # Install Python dependencies
   pip install -r requirements.txt
   
   # Run IP rotation script (typically via cron)
   python rotate_ladder.py

6. Publish initial IP:

   python publishIP.py <your_server_ip>

Client Setup

1. Install and configure IPFS:

   # Install IPFS (if not already installed)
   # Start IPFS daemon
   ipfs daemon

2. Install dnscrypt-proxy:

   # On Ubuntu/Debian
   sudo apt-get install dnscrypt-proxy
   
   # Configure dnscrypt-proxy to use NinjaDoH
   # Edit /etc/dnscrypt-proxy/dnscrypt-proxy.toml
   # Set server_names = ['ninjadoh']

3. Configure NinjaDoH client:

   # Edit linux_client.py or app_dash.py
   # Update IPNS_KEY with your server's IPNS key

4. Run the client:

   # Simple client (linux_client.py)
   python linux_client.py
   
   # Or dashboard client (app_dash.py)
   python app_dash.py
   # Enter IPNS key when prompted

5. Verify connectivity:

   # Test DNS resolution
   dig @127.0.0.1 google.com
   
   # Or visit https://1.1.1.1/help/ in your browser
   # to verify DoH is active

Requirements

Python Dependencies

Install all dependencies using:

pip install -r requirements.txt

Key dependencies include:

• requests - HTTP client for IPFS API
• dnsstamps - DNSCrypt stamp generation
• boto3 - AWS SDK for IP rotation
• numpy, pandas - Data analysis (for evaluation)

System Requirements

Server:

• AWS EC2 instance (t2.micro or larger)
• Multiple Elastic IPs
• Multiple network interfaces
• Ubuntu 20.04+ or similar Linux distribution

Client:

• Linux system
• IPFS node
• dnscrypt-proxy
• Root/sudo access for dnscrypt-proxy configuration

Project Structure

.
├── assets/                 # Logo and images
├── evaluation/             # Research evaluation scripts
│   ├── baseline/          # Baseline DoH performance comparisons
│   ├── ml/                # ML-based detection evaluation
│   ├── ipns_resolution/   # IPNS resolution timing tests
│   └── tor/               # Tor-based DoH comparisons
├── terraform/             # AWS infrastructure as code
├── tests/                 # Test suite and acceptance criteria
├── app_dash.py            # Client dashboard (curses-based UI)
├── linux_client.py        # Simple client implementation
├── publishIP.py           # Server: Publish IP to IPFS/IPNS
├── rotate_ladder.py       # Server: Rotate IPs between interfaces
├── generate_certs.py      # Server: Generate SSL certificates
├── generate_rootCA.sh     # Server: Generate root CA
└── requirements.txt       # Python dependencies

Evaluation

The evaluation/ directory contains scripts and results from our research evaluation:

• Baseline comparisons: Performance comparison with standard DoH servers
• ML detection: Evaluation against machine learning-based detection systems
• IPNS resolution: Timing analysis of IPNS resolution
• Tor comparison: Comparison with DNS over Tor

To run evaluations, see the individual README files in each evaluation subdirectory.

Citation

If you use NinjaDoH in your research, please cite:

@inproceedings{Seidenberger2026NinjaDoH,
  title        = {NinjaDoH: A Censorship-Resistant Moving Target DoH Server Using Hyperscalers and IPNS},
  author       = {Seidenberger, Scott and Beret, Marc and Wijewickrama, Raveen and Jadliwala, Murtuza and Maiti, Anindya},
  booktitle    = {Workshop on Measurements, Attacks, and Defenses for the Web (MADWeb)},
  year         = {2026},
  address      = {San Diego, CA, USA},
  month        = {Feb},
  doi          = {10.14722/madweb.2026.23006},
  url          = {https://dx.doi.org/10.14722/madweb.2026.23006}
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Website: https://ninjadoh.secretlab.page
• Paper: MADWeb 2026
• IPFS Documentation: https://docs.ipfs.io
• dnscrypt-proxy: https://github.com/DNSCrypt/dnscrypt-proxy

Contact

For questions or issues, please open an issue on GitHub or contact the research team.

---

NinjaDoH - Evading censorship, one rotation at a time.