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

Launch the application:
```
python dnsscanner_tui.py
```
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
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
View results:
- Sorted by response time (fastest first)
- Green = fast (<100ms)
- Yellow = medium (100-300ms)
- Red = slow (>300ms)
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:

Successful Response: Returns valid DNS answer in <2s
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:

Edit python/dnsscanner_tui.py
Uncomment the logger.add() section
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! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.github		.github
.vscode		.vscode
python		python
static		static
.gitignore		.gitignore
LICENSE		LICENSE
README-FA.md		README-FA.md
README-ZH.md		README-ZH.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
hook-rich.py		hook-rich.py
pydns-scanner.spec		pydns-scanner.spec
pyproject.toml		pyproject.toml
requirements-full.txt		requirements-full.txt
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

PYDNS Scanner

🎉 What's New in v2.0.0

🌐 Three Scan Modes

🔀 New Scan Strategy — Bidirectional Multi-Range

🧪 Auto DNS Type Check + Scoring

⚙️ New Advanced Section

🎨 UX Improvements

🔧 Experimental: Set OS MTU

⚡ Performance

⚙️ Bug Fixes

✨ Features

📋 Requirements

Python Version

Dependencies

Optional

📦 Bundled Slipstream Clients

📥 All-in-One Archives

Optional

📦 Bundled SlipNet Clients

🚀 Installation

Method 1: Install from PyPI (Recommended)

Using pip

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

Using uv (Faster)

Android / Termux

Using Mirror (For Users with Limited Access to PyPI)

Run after installation

Method 2: Run from Source (Manual)

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Run the Application

🎮 Usage

Basic Usage

CIDR File Format

Example Workflow

⌨️ Keyboard Shortcuts

🎮 Control Buttons

🎛️ Configuration

Logging

Concurrency Settings

Slipstream Testing

DNS Timeout

📊 Output Format

🔍 How It Works

DNS Detection Logic

Performance Optimizations

Random Subdomain Feature

📂 Project Structure

🐛 Troubleshooting

"No module named 'textual'"

"File not found" error

Slow scanning

High memory usage

Slipstream download fails

Slipstream not detected

Slipstream tests fail

📝 Logging

🌍 Finding CIDR Lists

Country IP Ranges

Usage Example

🤝 Contributing

Development Setup

📄 License

👨‍💻 Author

🙏 Acknowledgments

📈 Performance Notes

🔐 Security Considerations

💝 Support the Project

Cryptocurrency Donations

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Packages