pydns-scanner 2.0.5

A high-performance DNS scanner with TUI, SlipNet/Slipstream tunnel testing, DNS tunnel-compatibility scoring (NS/TXT/RND/DPI/EDNS0/NXD), real-time ISP/DNSSEC/security checks, and Iran CIDR bundle

PYDNS Scanner

🇺🇸 English    |    🇮🇷 فارسی    |    🇨🇳 中文

A modern, high-performance DNS scanner with a beautiful Terminal User Interface (TUI) built with Textual.
This tool can scan millions of IP addresses to find working DNS servers with three scan modes — Slipstream, SlipNet (DNSTT, NoiseDNS), and DNS Scan — plus automatic DNS type scoring and multi-platform client download.

🆕 v2.0.0: SlipNet support, DNS Scan mode, bidirectional multi-range scanning, Advanced settings, and major performance boost!

🎉 What's New in v2.0.0

🌐 Three Scan Modes

• Slipstream — Classic proxy testing with SOCKS5 support
• SlipNet — Full SlipNet configs support for DNSTT and NoiseDNS tunnels with SOCKS5 / SSH authentication and auto-detected auth method
• DNS Scan — New lightweight mode: just insert a domain, set concurrency, and scan — no proxy testing, no authentication. Tests security, DNS types, ping, resolved IP, EDNS0, and more

🔀 New Scan Strategy — Bidirectional Multi-Range

Scanner now scans from the start and end of each IP range simultaneously across multiple ranges, combined with random shuffle — faster performance and higher chance of finding working DNS servers compared to linear scanning.

🧪 Auto DNS Type Check + Scoring

All DNS types (A, AAAA, MX, TXT, NS) are automatically tested and scored per server — same scoring system as the SlipNet scanner.

⚙️ New Advanced Section

Fully customizable scanning parameters:

• Minimum proxy ping threshold for proxy test
• DNS connection timeout
• Proxy end-to-end test timeout
• Parallel proxy test count
• Custom shuffle steps
• Proxy test URL + expected response status code
• Set MTU (experimental OS-level MTU override)
• Query size for SlipNet (DNSTT / NoiseDNS)

🎨 UX Improvements

• Enhanced scan statistics — Redesigned stats display with clearer layout
• Better result table — Improved writing and formatting in the results table
• New proxy test status UI — Real-time proxy test feedback
• Better Filtered IP detection — More accurate identification of filtered IPs
• Log section always visible — Log panel is no longer toggleable; always shown during scans

🔧 Experimental: Set OS MTU

Scan with a specified MTU value for advanced network tuning.

⚡ Performance

• Significantly higher scan performance overall
• Auto detect auth method for SlipNet (DNSTT / NoiseDNS)

⚙️ Bug Fixes

• Fixed UI freeze after scanning large DNS ranges
• Fixed speed drop after 500K+ scanned IPs
• Fixed memory leak during long-running scans
• Updated dependencies to resolve Dependabot low-severity vulnerability alerts

✨ Features

• � Three Scan Modes — Slipstream (proxy test), SlipNet (DNSTT / NoiseDNS tunnels), DNS Scan (lightweight, no proxy/auth)
• 🔀 Bidirectional Multi-Range Scan — Scans from start and end of each IP range simultaneously with random shuffle for faster discovery
• 🧪 Auto DNS Type Scoring — All DNS types (A, AAAA, MX, TXT, NS) tested and scored automatically per server
• ⚙️ Advanced Settings — Customize proxy ping threshold, DNS timeout, proxy E2E timeout, parallel proxy count, shuffle steps, test URL, MTU, and query size
• 🔐 Security Testing — Detects hijacked, filtered, open resolver, and DNSSEC per server
• 🌐 Resolved IP Column — Tests each DNS server by resolving google.com, result shown in table
• 📡 ISP Detection — AS number and organisation name via ip-api.com
• 🌍 IPv4 / IPv6 Detection — Reports which IP versions each server supports
• 📶 EDNS0 Detection — Tests and displays EDNS0 extension support
• 🔌 Slipstream Rust Plus — Faster proxy testing with false-positive fixes and independent SOCKS5 test
• 🔗 SlipNet Support — DNSTT / NoiseDNS tunnel testing with SOCKS5 / SSH auth and auto-detected auth method
• 🧮 Smart Multi-key Sort — Auto-sorts by proxy pass → DNSSEC → ping for best servers first
• ⚡ High Performance — Asynchronous scanning with configurable concurrency
• ⏸️ Pause / Resume / Shuffle — Full live scan control
• 📊 Real-time Statistics — Live pass/fail/found counters updated throughout the scan
• 🔍 Smart DNS Detection — Detects working DNS servers even with NXDOMAIN / NODATA responses
• 🎲 Random Subdomain Support — Avoid cached responses with random subdomains
• 🌐 Multiple DNS Types — Supports A, AAAA, MX, TXT, NS records
• 📝 Always-on Log Panel — Log section is always visible during scans
• 🌍 Multi-Platform Auto-Download — Automatically downloads the correct Slipstream client for your platform
• 📥 Resume Downloads — Smart download resume on network interruptions with retry logic
• 💾 Auto-save Results — Automatic CSV export with per-server detail
• 📁 CIDR Management — Built-in Iran IPs + custom file picker
• 🚀 Memory Efficient — Streaming IP generation without loading all IPs into memory
• 🔔 Audio Alerts — Optional sparkle sound on successful proxy test
• 🔧 Experimental MTU — Set OS-level MTU for advanced network scanning

📋 Requirements

Python Version

• Python 3.11 or higher

Dependencies

# Core dependencies (always installed — works on every platform including Android/Termux)
textual>=0.47.0       # TUI framework
aiodns>=3.1.0         # Async DNS resolver
httpx[socks]>=0.25.0  # HTTP client with SOCKS5 support for proxy testing
loguru>=0.7.0         # Advanced logging

# Optional "full" extras (pip install pydns-scanner[full]) — desktop only
google-re2>=1.0       # Fast RE2 regex engine (falls back to stdlib re)
orjson>=3.9.0         # Fast JSON serialization (falls back to stdlib json)
pyperclip>=1.8.0      # Clipboard support (silently disabled when absent)

Optional

• Slipstream Client - For proxy testing functionality (5 concurrent tests)
  • Automatic Download: The application automatically detects your platform and downloads the correct client
  • Smart Detection: Detects existing installations (including legacy filenames)
  • Resume Support: Partial downloads are saved and can be resumed on retry
  • Supported platforms:
    • Linux (x86_64): slipstream-client-linux-amd64
    • Linux (ARM64): slipstream-client-linux-arm64
    • Windows (x86_64): slipstream-client-windows-amd64.exe
    • macOS (ARM64): slipstream-client-darwin-arm64
    • macOS (Intel): slipstream-client-darwin-amd64
    • Android (ARM64): slipstream-client-linux-arm64
  • Manual download available from: slipstream-rust-plus-deploy releases

📦 Bundled Slipstream Clients

Pre-compiled Slipstream client binaries (from the faster Fox-Fig/slipstream-rust-plus-deploy) are included in the slipstream-client/ folder for all platforms:

Platform	Path	Description
Linux x86_64	slipstream-client/linux/slipstream-client-linux-amd64	Linux x86_64 binary
Linux ARM64	slipstream-client/linux/slipstream-client-linux-arm64	Linux ARM64 binary (Raspberry Pi, ARM servers)
Android/Termux	slipstream-client/android/slipstream-client-linux-arm64	Android ARM64 (Termux compatible)
Windows	slipstream-client/windows/slipstream-client-windows-amd64.exe	Windows x86_64 executable
macOS ARM	slipstream-client/mac/slipstream-client-darwin-arm64	macOS Apple Silicon (M1/M2/M3/M4)
macOS Intel	slipstream-client/mac/slipstream-client-darwin-amd64	macOS Intel x86_64

⚠️ Windows Note: The Windows client requires OpenSSL DLLs (libcrypto-3-x64.dll and libssl-3-x64.dll) which are included in the slipstream-client/windows/ folder. When using automatic download, these DLLs are downloaded automatically alongside the Windows executable.

📥 All-in-One Archives

For convenience, compressed archives containing all platform binaries are available:

• slipstream-client/slipstream-client-all-platforms.tar.gz - Best compression (recommended)
• slipstream-client/slipstream-client-all-platforms.zip - Windows-friendly format

These archives include Linux, Windows, and macOS clients in a single download.

Optional

• SlipNet Client — For SlipNet (DNSTT / NoiseDNS) tunnel testing
  • Automatic Download: The application automatically detects your platform and downloads the correct SlipNet client
  • Smart Detection: Detects existing installations
  • Resume Support: Partial downloads are saved and can be resumed on retry
  • Supported platforms:
    • Linux (x86_64): slipnet-linux-amd64
    • Linux (ARM64): slipnet-linux-arm64
    • Windows (x86_64): slipnet-windows-amd64.exe
    • macOS (ARM64): slipnet-darwin-arm64
    • macOS (Intel): slipnet-darwin-amd64
  • Manual download available from: anonvector releases

📦 Bundled SlipNet Clients

Pre-compiled SlipNet client binaries (by anonvector) are included in the slipnet-client/ folder for all platforms:

Platform	Path	Description
Linux x86_64	slipnet-client/linux/slipnet-linux-amd64	Linux x86_64 binary
Linux ARM64	slipnet-client/linux/slipnet-linux-arm64	Linux ARM64 binary (Raspberry Pi, ARM servers)
Windows	slipnet-client/windows/slipnet-windows-amd64.exe	Windows x86_64 executable
macOS ARM	slipnet-client/mac/slipnet-darwin-arm64	macOS Apple Silicon (M1/M2/M3/M4)
macOS Intel	slipnet-client/mac/slipnet-darwin-amd64	macOS Intel x86_64

🚀 Installation

Method 1: Install from PyPI (Recommended)

The easiest way to install PYDNS Scanner:

Using pip

pip install pydns-scanner

Desktop — full extras (faster regex, clipboard, fast JSON)

pip install pydns-scanner[full]

Using uv (Faster)

uv pip install pydns-scanner        # core
uv pip install pydns-scanner[full]   # desktop extras

Android / Termux

pkg update && pkg install python
pip install pydns-scanner            # core only — always works on Termux
pydns-scanner

Note: On Android/Termux the optional C-extension packages (google-re2, orjson, pyperclip) are automatically skipped — the scanner falls back to stdlib equivalents with zero manual intervention.

Using Mirror (For Users with Limited Access to PyPI)

# Runflare Mirror
pip install pydns-scanner -i https://mirror-pypi.runflare.com/simple/ --trusted-host mirror-pypi.runflare.com

# Or Alibaba Cloud Mirror
pip install pydns-scanner -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

# Or TUNA Mirror
pip install pydns-scanner -i https://pypi.tuna.tsinghua.edu.cn/simple

Run after installation

pydns-scanner

---

Method 2: Run from Source (Manual)

If you want to run the code directly from the repository:

Step 1: Clone the Repository

git clone https://github.com/xullexer/PYDNS-Scanner.git
cd PYDNS-Scanner

Step 2: Install Dependencies

Using uv (Recommended - Fast!)

uv pip install -r requirements.txt

Using pip

pip install -r requirements.txt

Using Mirror (For Users with Limited Access to PyPI)

# Runflare Mirror
pip install -r requirements.txt -i https://mirror-pypi.runflare.com/simple/ --trusted-host mirror-pypi.runflare.com

# Or Alibaba Cloud Mirror
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

# Or TUNA Mirror
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Step 3: Run the Application

python -m python

---

🎮 Usage

Basic Usage

From PyPI:

pydns-scanner

From source:

python -m python

This will launch the interactive TUI where you can configure:

• CIDR File: Path to file containing IP ranges (CIDR notation)
• Domain: Domain to query (e.g., google.com)
• DNS Type: Record type (A, AAAA, MX, TXT, NS)
• Concurrency: Number of parallel workers (default: 100)
• Random Subdomain: Add random prefix to avoid cached responses
• Scan Mode: Choose Slipstream (proxy test), SlipNet (DNSTT/NoiseDNS), or DNS Scan (lightweight)

CIDR File Format

Create a text file with one CIDR range per line:

# Comments start with #
1.1.1.0/24
8.8.8.0/24
178.22.122.0/24
185.51.200.0/22

Example Workflow

1. Launch the application:

   python dnsscanner_tui.py
   

2. Configure scan parameters:

   • Click "📂 Browse" to select your CIDR file
   • Enter domain (e.g., google.com)
   • Set concurrency (recommended: 100-500)
   • Enable options as needed

3. Start scanning:

   • Click "🚀 Start Scan"
   • Watch real-time progress and results
   • Use "⏸ Pause" to pause the scan at any time
   • Use "▶ Resume" to continue from where you paused

4. View results:

   • Sorted by response time (fastest first)
   • Green = fast (<100ms)
   • Yellow = medium (100-300ms)
   • Red = slow (>300ms)

5. Save results:

   • Results are auto-saved to results/TIMESTAMP.csv
   • Press c or click "💾 Save Results" to save manually

⌨️ Keyboard Shortcuts

Key	When	Action
s	Config screen	Start scan
q	Anytime	Quit application
c	While scanning	Save results
p	While scanning	Pause scan
r	When paused	Resume scan
x	When paused	Shuffle remaining IPs

🎮 Control Buttons

During an active scan:

• ⏸ Pause - Pause the scan without losing progress
• ▶ Resume - Continue scanning from where you paused
• 💾 Save Results - Manually save current results
• 🛑 Quit - Exit the application

🎛️ Configuration

Logging

Logging is disabled by default to keep the interface clean and avoid unnecessary disk writes.

To enable logging, edit dnsscanner_tui.py:

# Configure logging (disabled by default)
logger.remove()  # Remove default handler to disable logging
# Uncomment the line below to enable file logging
logger.add(
    "logs/dnsscanner_{time}.log",
    rotation="50 MB",
    compression="zip",
    level="DEBUG",
)

When enabled:

• Logs are saved to logs/dnsscanner_TIMESTAMP.log
• Auto-rotate at 50 MB
• Compressed automatically (zip)
• Includes DEBUG level details

Concurrency Settings

Adjust based on your system and network:

• Low (50-100): Conservative, suitable for slower systems
• Medium (100-300): Balanced performance
• High (300-500): Fast scanning, requires good hardware
• Very High (500+): Maximum speed, may hit resource limits

Slipstream Testing

The scanner supports parallel Slipstream proxy testing with automatic download:

# In __init__ method
self.slipstream_max_concurrent = 5  # Max parallel proxy tests
self.slipstream_base_port = 10800   # Base port (uses 10800, 10801, 10802)

Auto-Download Features:

• Platform detection (Windows/Linux/macOS + architecture)
• Progress bar with download speed
• Resume on interruption (keeps .partial files)
• Retry with exponential backoff (up to 5 attempts)
• Legacy filename detection (slipstream-client.exe)

DNS Timeout

DNS queries timeout after 2 seconds:

# In _test_dns method
resolver = aiodns.DNSResolver(nameservers=[ip], timeout=2.0, tries=1)

📊 Output Format

Results are saved in CSV format (results/TIMESTAMP.csv). Columns adapt to which tests are enabled:

DNS,Ping (ms),IPv4/IPv6,TCP/UDP,Security,EDNS0,Resolved IP,ISP
8.8.8.8,12,IPv4/IPv6,TCP+UDP,DNSSEC,Yes,142.250.185.46,AS15169 Google LLC
1.1.1.1,15,IPv4/IPv6,TCP+UDP,DNSSEC,Yes,142.250.185.46,AS13335 Cloudflare Inc

Optional columns (Proxy Test, Security, EDNS0) are included only when the corresponding test is enabled in settings.

🔍 How It Works

DNS Detection Logic

The scanner considers a server as "working DNS" if:

1. Successful Response: Returns valid DNS answer in <2s
2. DNS Error Responses: Returns NXDOMAIN, NODATA, or NXRRSET in <2s
   • These errors mean the DNS server IS working, just the record doesn't exist

This approach catches more working DNS servers than tools that only accept successful responses.

Performance Optimizations

• Streaming IP Generation: IPs are generated on-the-fly from CIDR ranges
• Chunked Processing: Processes IPs in batches of 500
• Async I/O: Non-blocking DNS queries using aiodns
• Semaphore Control: Limits concurrent operations to prevent resource exhaustion
• Memory Mapping: Fast CIDR file reading using mmap when possible

Random Subdomain Feature

When enabled, queries use random prefixes:

original: google.com
random:   a1b2c3d4.google.com

Use case: Bypass cached DNS responses Requirement: Target domain should have wildcard DNS (*.example.com)

📂 Project Structure

PYDNS-Scanner/
├── README.md                          # English documentation
├── README-FA.md                       # Farsi documentation
├── README-ZH.md                       # Chinese documentation
├── RELEASE_NOTES.md                   # Release notes (EN / FA / ZH)
├── pyproject.toml                     # Python package configuration
├── requirements.txt                   # Python dependencies
├── pydns-scanner.spec                 # PyInstaller build spec
├── python/
│   ├── __init__.py                    # Package init
│   ├── __main__.py                    # Entry point (pydns-scanner CLI)
│   ├── dnsscanner_tui.py             # Main TUI application
│   ├── iran-ipv4.cidrs               # Sample Iranian CIDR file
│   ├── requirements.txt               # Python dependencies (source)
│   ├── scanner/                       # Modular scanner package
│   │   ├── __init__.py
│   │   ├── config_mixin.py           # Configuration mixin for TUI
│   │   ├── constants.py              # Shared constants
│   │   ├── extra_tests.py            # Security & EDNS0 tests
│   │   ├── ip_streaming.py           # Streaming IP generation from CIDR
│   │   ├── isp_cache.py              # ISP detection & caching
│   │   ├── proxy_testing.py          # Slipstream proxy testing
│   │   ├── results.py                # Result formatting & CSV export
│   │   ├── slipnet.py                # SlipNet (DNSTT/NoiseDNS) testing
│   │   ├── slipstream.py            # Slipstream client management
│   │   ├── utils.py                  # Utility functions
│   │   ├── widgets.py                # Custom TUI widgets
│   │   └── worker_pool.py           # Async worker pool
│   ├── slipstream-client/            # Bundled Slipstream binaries
│   │   ├── linux/
│   │   ├── windows/
│   │   ├── mac/
│   │   └── android/
│   └── slipnet-client/               # Bundled SlipNet binaries
│       ├── linux/
│       ├── windows/
│       └── mac/
├── results/                           # Scan results (auto-generated)
├── logs/                              # Application logs (when enabled)
└── static/                            # Static assets

🐛 Troubleshooting

"No module named 'textual'"

pip install textual

"File not found" error

• Ensure CIDR file path is correct
• Use absolute path or relative path from script location
• Use the built-in file browser (📂 Browse button)

Slow scanning

• Reduce concurrency value
• Check network bandwidth
• Verify DNS timeout settings

High memory usage

• The scanner uses streaming to minimize memory
• If issues persist, reduce chunk size in _stream_ips_from_file

Slipstream download fails

• Network issues: The app automatically retries up to 5 times with exponential backoff
• Resume: Partial downloads are saved as .partial files - just run again to resume
• Manual download: Download from slipstream-rust-plus-deploy releases
• Check logs: Enable logging (see Configuration section) for detailed error info
• Firewall: Ensure GitHub access is allowed

Slipstream not detected

• Check platform-specific directory exists (slipstream-client/windows/, etc.)
• Verify filename matches (supports both new and legacy names)
• For legacy installs: Use slipstream-client.exe (auto-detected)
• Enable logging to see detection process

Slipstream tests fail

• Verify executable has correct permissions (Linux/macOS: chmod +x)
• Check that ports 10800-10802 are available
• Review logs (if enabled) in logs/ directory
• Test connectivity to DNS servers manually

📝 Logging

Default: Disabled - No logs are created to keep your system clean.

To Enable Logging:

1. Edit python/dnsscanner_tui.py
2. Uncomment the logger.add() section
3. Logs saved to logs/dnsscanner_TIMESTAMP.log

Log Levels:

• DEBUG: Detailed DNS query results, download progress
• INFO: Scan progress and statistics
• WARNING: Non-critical issues, retry attempts
• ERROR: Critical failures, download errors

🌍 Finding CIDR Lists

Country IP Ranges

IPv4:

• https://www.ipdeny.com/ipblocks/data/aggregated/

IPv6:

• https://www.ipdeny.com/ipv6/ipaddresses/aggregated/

Usage Example

# Download Iran IPv4 ranges
wget https://www.ipdeny.com/ipblocks/data/aggregated/ir-aggregated.zone -O iran-ipv4.cidrs

# Use in scanner
python dnsscanner_tui.py
# Then select iran-ipv4.cidrs in the file browser

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

Development Setup

git clone https://github.com/xullexer/PYDNS-Scanner.git
cd PYDNS-Scanner/python
pip install -r requirements.txt
python dnsscanner_tui.py

📄 License

This project is licensed under the MIT License.

👨‍💻 Author

• GitHub: @xullexer

🙏 Acknowledgments

• Built with Textual by Textualize
• DNS resolution via aiodns
• Inspired by the need for efficient DNS server discovery
• Thanks to anonvector for developing the SlipNet CLI — the SlipNet client binaries bundled in this project are from their work
• Python codebase is now modular and easier to develop and maintain

📈 Performance Notes

Tested performance on various systems:

• Small scan (1,000 IPs): ~10-30 seconds
• Medium scan (50,000 IPs): ~5-10 minutes
• Large scan (1M+ IPs): ~1-3 hours

Results vary based on network speed, concurrency settings, and system resources.

🔐 Security Considerations

• Uses cryptographically secure random number generator (secrets.SystemRandom)
• No credentials or sensitive data are logged
• DNS queries are standard UDP/TCP port 53
• Slipstream proxy testing is optional and disabled by default

💝 Support the Project

If you find this project useful, consider supporting its development:

Cryptocurrency Donations

• Bitcoin (BTC)
  bc1qpya0kc2uh0mc08c7nuzrqkpsqjr36mrwscgpxr

• Solana (SOL)
  J1XzZfizQ6mgYiyxpLGWU52kHBF1hm2Tb9AZ5FaRj8tH

• Ethereum (ETH)
  0x26D9924B88e71b5908d957EA4c74C66989c253cb

• Binance Smart Chain (BNB/BSC)
  0x26D9924B88e71b5908d957EA4c74C66989c253cb

• Tron (TRX)
  TYBZFr8WUsjgfrXrqmrdF5EXPXo7QdimA8

• Ethereum Base
  0x26D9924B88e71b5908d957EA4c74C66989c253cb

• TON (Telegram Open Network)
  UQBcI_ZZGQq3fcNzTkL-zszgFR5HpRDLFHYRZffizriiScxJ

---

Happy Scanning! 🚀