pyresolvers 1.0.0__py3-none-any.whl

pyresolvers/__init__.py

@@ -0,0 +1,28 @@
+"""
+PyResolvers - High-Performance DNS Resolver Validation & Speed Testing
+
+Modern async DNS validator with speed testing and ordering.
+
+Example:
+    >>> from pyresolvers import Validator
+    >>> validator = Validator()
+    >>> results = validator.validate_by_speed(['1.1.1.1', '8.8.8.8'])
+    >>> for server, latency in results:
+    ...     print(f"{server}: {latency:.2f}ms")
+
+High concurrency:
+    >>> validator = Validator(concurrency=100)
+    >>> results = validator.validate_by_speed(large_list)
+
+Async usage:
+    >>> import asyncio
+    >>> results = await validator.validate_by_speed_async(servers)
+"""
+
+from __future__ import annotations
+
+from .lib.core.__version__ import __version__
+from .validator import ValidationResult, Validator
+
+__all__ = ['Validator', 'ValidationResult', '__version__']
+__version__ = __version__

pyresolvers/__main__.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""PyResolvers CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import sys
+from typing import Any, List
+
+from .lib.core.input import InputHelper, InputParser
+from .lib.core.output import Level, OutputHelper
+from .validator import Validator
+
+
+def handle_interrupt(signum: int, frame: Any) -> None:
+    os._exit(0)
+
+
+def output_results(validator: Validator, targets: List[str], args: Any, out: OutputHelper) -> None:
+    """Output validation results."""
+    fmt = args.output_format
+
+    if fmt == 'json':
+        result = validator.to_json(targets, args.min_speed, args.max_speed)
+        count = json.loads(result).get('count', 0)
+        out.terminal(Level.INFO, 0, f"Found {count} valid servers")
+        if not args.silent:
+            print(f"\n{result}")
+        if args.output:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(result)
+
+    elif fmt == 'text-with-speed':
+        result = validator.to_text(targets, args.min_speed, args.max_speed, True)
+        lines = [l for l in result.strip().split('\n') if l]
+        out.terminal(Level.INFO, 0, f"Found {len(lines)} valid servers")
+        if not args.silent:
+            for line in lines:
+                if parts := line.split():
+                    out.terminal(Level.ACCEPTED, parts[0], parts[1] if len(parts) > 1 else "")
+        if args.output:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(result)
+
+    else:  # text
+        results = validator.validate_by_speed(targets, args.min_speed, args.max_speed)
+        out.terminal(Level.INFO, 0, f"Found {len(results)} valid servers")
+
+        if results and not args.silent:
+            for server, latency in results:
+                out.terminal(Level.ACCEPTED, server, f"{latency:.2f}ms")
+
+        if args.output:
+            text = validator.to_text(targets, args.min_speed, args.max_speed)
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(text)
+        elif args.silent:
+            for server, _ in results:
+                print(server, flush=True)
+
+
+def main() -> None:
+    signal.signal(signal.SIGINT, handle_interrupt)
+
+    args = InputParser().parse(sys.argv[1:])
+    out = OutputHelper(args)
+    out.print_banner()
+
+    targets = list(InputHelper.return_targets(args))
+    out.terminal(Level.INFO, 0, f"Testing {len(targets)} servers")
+
+    if args.max_speed:
+        out.terminal(Level.INFO, 0, f"Max speed filter: {args.max_speed}ms")
+    if args.min_speed:
+        out.terminal(Level.INFO, 0, f"Min speed filter: {args.min_speed}ms")
+
+    validator = Validator(
+        baseline_domain=args.rootdomain,
+        query_prefix=args.query,
+        concurrency=int(args.threads),
+        timeout=int(args.timeout),
+        use_fast_timeout=False,  # Disabled for maximum coverage
+        verbose=args.verbose
+    )
+
+    try:
+        out.terminal(Level.INFO, 0, "Establishing baseline...")
+        output_results(validator, targets, args, out)
+    except RuntimeError as e:
+        out.terminal(Level.ERROR, 0, str(e))
+        sys.exit(1)
+    except KeyboardInterrupt:
+        out.terminal(Level.ERROR, 0, "Interrupted")
+        sys.exit(130)
+    except Exception as e:
+        out.terminal(Level.ERROR, 0, f"Error: {str(e)}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pyresolvers/lib/core/__version__.py

@@ -0,0 +1,2 @@
+__version__ = '1.0.0'
+

pyresolvers/lib/core/input.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Command-line argument parsing and input handling."""
+
+from __future__ import annotations
+
+import sys
+from argparse import ArgumentParser
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import urlopen
+from urllib.error import URLError, HTTPError
+
+
+class InputHelper:
+    """Helper for processing input targets."""
+
+    @staticmethod
+    def process_targets(parser, arg):
+        """Process targets from URL or file."""
+        if InputHelper.validate_url(arg):
+            targets = InputHelper.process_url(parser, arg)
+        else:
+            filename = InputHelper.validate_filename(parser, arg)
+            if filename:
+                targets = InputHelper.process_file(filename)
+
+        if not targets:
+            raise ValueError("No targets provided or empty list")
+        return targets
+
+    @staticmethod
+    def validate_url(string):
+        """Check if string is a valid URL."""
+        try:
+            result = urlparse(string)
+            return bool(result.scheme)
+        except Exception:
+            return False
+
+    @staticmethod
+    def validate_filename(parser, arg):
+        """Validate and resolve file path."""
+        try:
+            path = Path(arg).expanduser().resolve()
+            if not path.is_file():
+                parser.error(f"File {arg} does not exist or is not a valid URL")
+            return str(path)
+        except Exception as e:
+            parser.error(f"Invalid file path: {e}")
+
+    @staticmethod
+    def process_url(parser, url):
+        """Fetch targets from URL."""
+        try:
+            with urlopen(url, timeout=30) as response:
+                if response.status != 200:
+                    parser.error(f"HTTP {response.status} from {url}")
+                content = response.read().decode('utf-8')
+                return content.split()
+        except HTTPError as e:
+            parser.error(f"HTTP {e.code} from {url}")
+        except URLError as e:
+            parser.error(f"Failed to fetch {url}: {e.reason}")
+        except Exception as e:
+            parser.error(f"Error fetching {url}: {e}")
+
+    @staticmethod
+    def process_file(path):
+        """Load targets from file."""
+        with open(path, 'r', encoding='utf-8') as f:
+            return [line.strip() for line in f if line.strip()]
+
+    @staticmethod
+    def check_positive(parser, arg):
+        """Validate positive integer."""
+        try:
+            value = int(arg)
+            if value <= 0:
+                parser.error(f"{arg} must be a positive integer")
+            return arg
+        except ValueError:
+            parser.error(f"{arg} is not a valid integer")
+
+    @staticmethod
+    def return_targets(arguments):
+        """Return final target list with exclusions applied."""
+        targets = set()
+        exclusions = set()
+
+        if arguments.target:
+            targets.add(arguments.target)
+        else:
+            targets.update(arguments.target_list)
+
+        if arguments.exclusion:
+            exclusions.add(arguments.exclusion)
+        elif arguments.exclusions_list:
+            exclusions.update(arguments.exclusions_list)
+
+        targets -= exclusions
+
+        if not targets:
+            raise ValueError("No targets remaining after exclusions")
+        return targets
+
+
+class InputParser:
+    """Command-line argument parser."""
+
+    def __init__(self):
+        self._parser = self.setup_parser()
+
+    def parse(self, argv):
+        """Parse command-line arguments."""
+        return self._parser.parse_args(argv)
+
+    @staticmethod
+    def setup_parser():
+        """Setup argument parser."""
+        parser = ArgumentParser(description='DNS Resolver Validator with Speed Testing')
+
+        targets = parser.add_mutually_exclusive_group(required=False)
+        targets.add_argument('-t', dest='target', help='Target DNS server IP')
+        targets.add_argument(
+            '-tL', dest='target_list',
+            default="https://public-dns.info/nameservers.txt",
+            type=lambda x: InputHelper.process_targets(parser, x),
+            help='File or URL with DNS server IPs (default: public-dns.info)'
+        )
+
+        exclusions = parser.add_mutually_exclusive_group()
+        exclusions.add_argument('-e', dest='exclusion', help='Exclude specific server')
+        exclusions.add_argument(
+            '-eL', dest='exclusions_list',
+            type=lambda x: InputHelper.process_targets(parser, x),
+            help='File or URL with servers to exclude'
+        )
+
+        parser.add_argument('-o', '--output', help='Output file for results')
+        parser.add_argument('-r', dest='rootdomain', default="bet365.com",
+                          help='Root domain for testing (default: bet365.com)')
+        parser.add_argument('-q', dest='query', default="dnsvalidator",
+                          help='Query prefix for NXDOMAIN testing')
+        parser.add_argument('-threads', dest='threads', default=5,
+                          type=lambda x: InputHelper.check_positive(parser, x),
+                          help='Max concurrent threads (default: 5)')
+        parser.add_argument('-timeout', dest='timeout', default=600,
+                          type=lambda x: InputHelper.check_positive(parser, x),
+                          help='Timeout in seconds (default: 600)')
+        parser.add_argument('--no-color', dest='nocolor', action='store_true',
+                          help='Disable colored output')
+
+        output_types = parser.add_mutually_exclusive_group()
+        output_types.add_argument('-v', '--verbose', dest='verbose', action='store_true',
+                                help='Enable verbose output')
+        output_types.add_argument('--silent', dest='silent', action='store_true',
+                                help='Only output valid server IPs')
+
+        parser.add_argument('--format', dest='output_format', default='text',
+                          choices=['text', 'json', 'text-with-speed'],
+                          help='Output format (default: text)')
+        parser.add_argument('--max-speed', dest='max_speed', type=float,
+                          help='Max response time in ms (filter slower servers)')
+        parser.add_argument('--min-speed', dest='min_speed', type=float,
+                          help='Min response time in ms (filter faster servers)')
+
+        return parser

pyresolvers/lib/core/output.py

@@ -0,0 +1,66 @@
+"""Output formatting and terminal display."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from time import localtime, strftime
+from typing import Any, Union
+
+from colorclass import Color, disable_all_colors
+
+from pyresolvers.lib.core.__version__ import __version__
+
+
+class Level(IntEnum):
+    """Log level enumeration."""
+    VERBOSE, INFO, ACCEPTED, REJECTED, ERROR = range(5)
+
+
+class OutputHelper:
+    """Formatted terminal output handler."""
+
+    _FORMATS = {
+        Level.VERBOSE: Color('{autoblue}[VERBOSE]{/autoblue}'),
+        Level.INFO: Color('{autoyellow}[INFO]{/autoyellow}'),
+        Level.ACCEPTED: Color('{autogreen}[ACCEPTED]{/autogreen}'),
+        Level.REJECTED: Color('{autored}[REJECTED]{/autored}'),
+        Level.ERROR: Color('{autobgyellow}{autored}[ERROR]{/autored}{/autobgyellow}')
+    }
+    _SEP = "=" * 55
+
+    def __init__(self, arguments: Any) -> None:
+        if getattr(arguments, 'nocolor', False):
+            disable_all_colors()
+        self.verbose = getattr(arguments, 'verbose', False)
+        self.silent = getattr(arguments, 'silent', False)
+        self.output = getattr(arguments, 'output', None)
+
+    def print_banner(self) -> None:
+        """Print application banner."""
+        if not self.silent:
+            print(f"{self._SEP}\npyresolvers v{__version__} - DNS Resolver Validator\n{self._SEP}", flush=True)
+
+    def terminal(self, level: Level, target: Union[str, int], message: str = "") -> None:
+        """Print formatted message."""
+        if level == Level.VERBOSE and not self.verbose:
+            return
+
+        if self.silent:
+            if level == Level.ACCEPTED:
+                print(target, flush=True)
+            return
+
+        leader = self._FORMATS.get(level, '[#]')
+        time_str = strftime("%H:%M:%S", localtime())
+
+        if target == 0 or target == "0":
+            print(f'[{time_str}] {leader} {message}', flush=True)
+        else:
+            print(f'[{time_str}] {leader} [{target}] {message}', flush=True)
+
+        if self.output and level == Level.ACCEPTED:
+            try:
+                with open(self.output, 'a', encoding='utf-8') as f:
+                    f.write(f"{target}\n")
+            except IOError:
+                pass

pyresolvers/validator.py

@@ -0,0 +1,342 @@
+#!/usr/bin/env python3
+"""High-performance async DNS resolver validation."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import string
+import time
+from dataclasses import asdict, dataclass
+from ipaddress import IPv4Address, IPv6Address, ip_address
+from typing import AsyncIterator, Dict, List, Optional, Tuple
+
+try:
+    import aiodns
+    AIODNS_AVAILABLE = True
+except ImportError:
+    AIODNS_AVAILABLE = False
+
+# Configuration
+TRUSTED_RESOLVERS = ["1.1.1.1", "8.8.8.8"]
+TEST_DOMAINS = ["bet365.com", "telegram.com"]
+POISON_CHECK_DOMAINS = ["facebook.com", "paypal.com", "google.com", "bet365.com", "wikileaks.com"]
+BASELINE_DOMAIN = "bet365.com"
+QUERY_PREFIX = "dnsvalidator"
+DEFAULT_CONCURRENCY = 50
+DEFAULT_TIMEOUT = 5
+FAST_TIMEOUT = 1  # Quick timeout for dead server detection
+SUBDOMAIN_LENGTH = 10
+BATCH_SIZE = 100
+
+
+@dataclass
+class ValidationResult:
+    """DNS resolver validation result."""
+    server: str
+    valid: bool
+    latency_ms: float
+    error: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        return asdict(self)
+
+
+class Validator:
+    """High-performance async DNS resolver validator."""
+
+    def __init__(
+        self,
+        trusted_resolvers: Optional[List[str]] = None,
+        test_domains: Optional[List[str]] = None,
+        poison_check_domains: Optional[List[str]] = None,
+        baseline_domain: str = BASELINE_DOMAIN,
+        query_prefix: str = QUERY_PREFIX,
+        concurrency: int = DEFAULT_CONCURRENCY,
+        timeout: int = DEFAULT_TIMEOUT,
+        use_fast_timeout: bool = False,
+        batch_size: int = BATCH_SIZE,
+        verbose: bool = False
+    ) -> None:
+        if not AIODNS_AVAILABLE:
+            raise ImportError(
+                "aiodns required for Validator. Install with: pip install aiodns\n"
+                "Or: pip install -r requirements.txt"
+            )
+
+        self.trusted_resolvers = trusted_resolvers or TRUSTED_RESOLVERS
+        self.test_domains = test_domains or TEST_DOMAINS
+        self.poison_check_domains = poison_check_domains or POISON_CHECK_DOMAINS
+        self.baseline_domain = baseline_domain
+        self.query_prefix = query_prefix
+        self.concurrency = concurrency
+        self.timeout = timeout
+        self.use_fast_timeout = use_fast_timeout
+        self.batch_size = batch_size
+        self.verbose = verbose
+        self._baseline_ip = ""
+        self._baseline_data: Dict[str, Dict] = {}
+
+    @staticmethod
+    def _random_subdomain(length: int = SUBDOMAIN_LENGTH) -> str:
+        """Generate random subdomain for testing."""
+        return ''.join(random.choices(string.ascii_lowercase, k=length))
+
+    @staticmethod
+    def _is_valid_ip(ip_str: str) -> bool:
+        """Validate IPv4/IPv6 address format."""
+        try:
+            return isinstance(ip_address(ip_str), (IPv4Address, IPv6Address))
+        except ValueError:
+            return False
+
+    def _log(self, msg: str) -> None:
+        """Log message if verbose mode enabled."""
+        if self.verbose:
+            print(msg)
+
+    async def _setup_baseline_single(self, resolver_ip: str) -> bool:
+        """Setup baseline from single trusted resolver."""
+        self._log(f"[INFO] {resolver_ip} - Establishing baseline")
+        try:
+            resolver = aiodns.DNSResolver(nameservers=[resolver_ip], timeout=self.timeout)
+            data = {}
+
+            # Get baseline IP
+            result = await resolver.query(self.baseline_domain, 'A')
+            data["ip"] = self._baseline_ip = result[0].host
+
+            # Test domains in parallel
+            domain_tasks = [resolver.query(domain, 'A') for domain in self.test_domains]
+            domain_results = await asyncio.gather(*domain_tasks, return_exceptions=True)
+
+            data["domains"] = {}
+            for domain, result in zip(self.test_domains, domain_results):
+                if not isinstance(result, Exception):
+                    data["domains"][domain] = result[0].host
+
+            # NXDOMAIN check
+            try:
+                await resolver.query(self.query_prefix + self.baseline_domain, 'A')
+                data["nxdomain"] = False
+            except aiodns.error.DNSError:
+                data["nxdomain"] = True
+
+            self._baseline_data[resolver_ip] = data
+            return True
+        except Exception as e:
+            self._log(f"[ERROR] {resolver_ip} - {str(e)}")
+            return False
+
+    async def _setup_baseline(self) -> bool:
+        """Setup baseline from all trusted resolvers in parallel."""
+        tasks = [self._setup_baseline_single(ip) for ip in self.trusted_resolvers]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        success_count = sum(1 for r in results if r is True)
+        return success_count == len(self.trusted_resolvers)
+
+    async def _check_poisoning(self, resolver: aiodns.DNSResolver, server: str) -> Optional[str]:
+        """Check for DNS poisoning with parallel queries."""
+        subdomains = [f"{self._random_subdomain()}.{domain}" for domain in self.poison_check_domains]
+        tasks = [resolver.query(subdomain, 'A') for subdomain in subdomains]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        for subdomain, result in zip(subdomains, results):
+            if not isinstance(result, Exception):
+                self._log(f"[ERROR] {server} - Poisoning detected: {subdomain}")
+                return "DNS poisoning"
+        return None
+
+    async def _check_nxdomain_and_baseline(
+        self, resolver: aiodns.DNSResolver, server: str
+    ) -> Tuple[bool, bool, Optional[str]]:
+        """Combined NXDOMAIN and baseline validation check."""
+        subdomain = f"{self._random_subdomain()}.{self.baseline_domain}"
+
+        try:
+            # Check NXDOMAIN and baseline in parallel
+            nxdomain_task = resolver.query(subdomain, 'A')
+            baseline_task = resolver.query(self.baseline_domain, 'A')
+
+            nxdomain_result, baseline_result = await asyncio.gather(
+                nxdomain_task, baseline_task, return_exceptions=True
+            )
+
+            # NXDOMAIN should fail
+            has_nxdomain = isinstance(nxdomain_result, Exception)
+
+            # Baseline should match
+            baseline_matches = False
+            if not isinstance(baseline_result, Exception):
+                resolved_ip = baseline_result[0].host
+                baseline_matches = resolved_ip == self._baseline_ip
+
+            return has_nxdomain, baseline_matches, None
+
+        except Exception as e:
+            return False, False, f"Error: {str(e)}"
+
+    def _matches_baseline(self, has_nxdomain: bool) -> bool:
+        """Verify resolver matches baseline behavior."""
+        matches = sum(
+            1 for data in self._baseline_data.values()
+            if data.get("ip") == self._baseline_ip and data.get("nxdomain") == has_nxdomain
+        )
+        return matches == len(self.trusted_resolvers)
+
+    async def _validate_server(self, server: str) -> ValidationResult:
+        """Validate single DNS server with fast timeout."""
+        if not self._is_valid_ip(server):
+            return ValidationResult(server, False, -1, "Invalid IP")
+
+        self._log(f"[INFO] {server} - Validating...")
+        start = time.time()
+
+        # Use fast timeout for quick dead server detection
+        timeout = FAST_TIMEOUT if self.use_fast_timeout else self.timeout
+
+        try:
+            resolver = aiodns.DNSResolver(nameservers=[server], timeout=timeout)
+
+            # Check poisoning
+            error = await self._check_poisoning(resolver, server)
+            if error:
+                return ValidationResult(server, False, -1, error)
+
+            # If fast timeout worked, use full timeout for validation
+            if self.use_fast_timeout and timeout < self.timeout:
+                resolver = aiodns.DNSResolver(nameservers=[server], timeout=self.timeout)
+
+            # Combined NXDOMAIN and baseline check
+            has_nxdomain, baseline_matches, error = await self._check_nxdomain_and_baseline(resolver, server)
+            if error:
+                return ValidationResult(server, False, -1, error)
+
+            latency = (time.time() - start) * 1000
+            valid = baseline_matches and self._matches_baseline(has_nxdomain)
+
+            self._log(f"[{'OK' if valid else 'FAIL'}] {server} - {latency:.2f}ms")
+            return ValidationResult(server, valid, latency, None if valid else "Invalid")
+
+        except asyncio.TimeoutError:
+            return ValidationResult(server, False, (time.time() - start) * 1000, "Timeout")
+        except Exception as e:
+            return ValidationResult(server, False, (time.time() - start) * 1000, str(e))
+
+    async def _validate_batch(self, servers: List[str]) -> List[ValidationResult]:
+        """Validate batch of servers with concurrency limit."""
+        semaphore = asyncio.Semaphore(self.concurrency)
+
+        async def bounded_validate(server: str) -> ValidationResult:
+            async with semaphore:
+                return await self._validate_server(server)
+
+        tasks = [bounded_validate(server) for server in servers]
+        return await asyncio.gather(*tasks)
+
+    async def validate_async(self, servers: List[str]) -> List[ValidationResult]:
+        """Validate multiple DNS servers asynchronously."""
+        if not await self._setup_baseline():
+            raise RuntimeError("Baseline setup failed")
+
+        # Process in batches for memory efficiency
+        all_results = []
+        for i in range(0, len(servers), self.batch_size):
+            batch = servers[i:i + self.batch_size]
+            results = await self._validate_batch(batch)
+            all_results.extend(results)
+
+        return all_results
+
+    async def validate_by_speed_async(
+        self, servers: List[str], min_ms: Optional[float] = None, max_ms: Optional[float] = None
+    ) -> List[Tuple[str, float]]:
+        """Get valid servers ordered by speed."""
+        results = await self.validate_async(servers)
+
+        # Filter and sort
+        filtered = [
+            (r.server, r.latency_ms)
+            for r in results
+            if r.valid and r.latency_ms > 0
+        ]
+
+        if min_ms:
+            filtered = [(s, t) for s, t in filtered if t >= min_ms]
+        if max_ms:
+            filtered = [(s, t) for s, t in filtered if t <= max_ms]
+
+        return sorted(filtered, key=lambda x: x[1])
+
+    async def validate_streaming_async(
+        self, servers: List[str], min_ms: Optional[float] = None, max_ms: Optional[float] = None
+    ) -> AsyncIterator[Tuple[str, float]]:
+        """Stream valid servers as they're validated (memory efficient)."""
+        if not await self._setup_baseline():
+            raise RuntimeError("Baseline setup failed")
+
+        semaphore = asyncio.Semaphore(self.concurrency)
+
+        async def validate_and_filter(server: str) -> Optional[Tuple[str, float]]:
+            async with semaphore:
+                result = await self._validate_server(server)
+                if result.valid and result.latency_ms > 0:
+                    if (not min_ms or result.latency_ms >= min_ms) and \
+                       (not max_ms or result.latency_ms <= max_ms):
+                        return (result.server, result.latency_ms)
+                return None
+
+        # Process in batches and yield results
+        for i in range(0, len(servers), self.batch_size):
+            batch = servers[i:i + self.batch_size]
+            tasks = [validate_and_filter(server) for server in batch]
+            results = await asyncio.gather(*tasks)
+
+            for result in results:
+                if result is not None:
+                    yield result
+
+    async def to_json_async(
+        self, servers: List[str], min_ms: Optional[float] = None, max_ms: Optional[float] = None, pretty: bool = True
+    ) -> str:
+        """Export validation results as JSON."""
+        results = await self.validate_by_speed_async(servers, min_ms, max_ms)
+        output = {
+            "servers": [{"ip": s, "latency_ms": round(t, 2)} for s, t in results],
+            "count": len(results),
+            "filters": {"min_ms": min_ms, "max_ms": max_ms}
+        }
+        return json.dumps(output, indent=2 if pretty else None)
+
+    async def to_text_async(
+        self, servers: List[str], min_ms: Optional[float] = None, max_ms: Optional[float] = None, show_speed: bool = False
+    ) -> str:
+        """Export validation results as plain text."""
+        results = await self.validate_by_speed_async(servers, min_ms, max_ms)
+        if show_speed:
+            return '\n'.join(f"{s} {t:.2f}ms" for s, t in results)
+        return '\n'.join(s for s, _ in results)
+
+    # Sync wrappers for compatibility
+    def validate(self, servers: List[str]) -> List[ValidationResult]:
+        """Validate servers (sync wrapper)."""
+        return asyncio.run(self.validate_async(servers))
+
+    def validate_by_speed(
+        self, servers: List[str], min_ms: Optional[float] = None, max_ms: Optional[float] = None
+    ) -> List[Tuple[str, float]]:
+        """Get valid servers ordered by speed (sync wrapper)."""
+        return asyncio.run(self.validate_by_speed_async(servers, min_ms, max_ms))
+
+    def to_json(
+        self, servers: List[str], min_ms: Optional[float] = None, max_ms: Optional[float] = None, pretty: bool = True
+    ) -> str:
+        """Export as JSON (sync wrapper)."""
+        return asyncio.run(self.to_json_async(servers, min_ms, max_ms, pretty))
+
+    def to_text(
+        self, servers: List[str], min_ms: Optional[float] = None, max_ms: Optional[float] = None, show_speed: bool = False
+    ) -> str:
+        """Export as text (sync wrapper)."""
+        return asyncio.run(self.to_text_async(servers, min_ms, max_ms, show_speed))

pyresolvers-1.0.0.dist-info/METADATA

@@ -0,0 +1,386 @@
+Metadata-Version: 2.4
+Name: pyresolvers
+Version: 1.0.0
+Summary: High-performance async DNS resolver validation and speed testing library
+Home-page: https://github.com/PigeonSec/pyresolvers
+Author: Karl
+Author-email: 
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/PigeonSec/pyresolvers
+Project-URL: Documentation, https://github.com/PigeonSec/pyresolvers#readme
+Project-URL: Repository, https://github.com/PigeonSec/pyresolvers
+Project-URL: Bug Tracker, https://github.com/PigeonSec/pyresolvers/issues
+Keywords: dns,resolver,validation,speed-test,async,networking
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: aiodns>=3.1.0
+Requires-Dist: pycares>=4.0.0
+Requires-Dist: colorclass>=2.2.2
+Dynamic: home-page
+Dynamic: requires-python
+
+<div align="center">
+
+<img src="logo.webp" alt="PyResolvers Logo" width="200" height="200">
+
+# PyResolvers
+
+**High-Performance Async DNS Resolver Validation & Speed Testing**
+
+[![Tests](https://github.com/PigeonSec/pyresolvers/actions/workflows/test.yml/badge.svg)](https://github.com/PigeonSec/pyresolvers/actions/workflows/test.yml)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![PyPI version](https://img.shields.io/pypi/v/pyresolvers.svg)](https://pypi.org/project/pyresolvers/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+*Validate DNS resolvers, measure response times, identify the fastest servers*
+
+</div>
+
+---
+
+## Overview
+
+PyResolvers is a high-performance async Python library and CLI tool for validating DNS resolvers. It performs comprehensive validation (baseline comparison, poisoning detection, NXDOMAIN verification) and orders results by speed.
+
+### Features
+
+- ⚡ **High-Performance Async** - 2-3x faster than thread-based validators
+- 🚀 **Speed Testing** - Measures and orders resolvers by latency
+- 🔍 **Comprehensive Validation** - Multiple validation layers
+- 🛡️ **Poisoning Detection** - Identifies DNS hijacking
+- 📊 **Multiple Formats** - JSON, plain text, text+speed
+- 🎯 **Speed Filtering** - Filter by min/max latency thresholds
+
+### Performance
+
+| Method | Time (5 servers) | Improvement |
+|--------|------------------|-------------|
+| Original (unoptimized) | 5.36s | baseline |
+| **PyResolvers** | **2.32s** | **56.7% faster** ⚡ |
+| Speedup | | **2.31x** |
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/PigeonSec/pyresolvers.git
+cd pyresolvers
+python3 -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install -e .
+```
+
+**Or install from PyPI:**
+
+```bash
+pip install pyresolvers
+```
+
+**Requirements**: Python 3.8+, aiodns, pycares, colorclass
+
+---
+
+## Quick Start
+
+### Command Line
+
+```bash
+# Test single resolver
+pyresolvers -t 1.1.1.1
+
+# Test from file
+pyresolvers -tL dns_servers.txt
+
+# Get fastest resolvers (< 50ms)
+pyresolvers -tL resolvers.txt --max-speed 50 --format text-with-speed
+
+# Export as JSON
+pyresolvers -tL resolvers.txt --format json -o valid_dns.json
+```
+
+### Python Library
+
+```python
+from pyresolvers import Validator
+
+# Basic usage
+validator = Validator()
+servers = ['1.1.1.1', '8.8.8.8', '9.9.9.9']
+results = validator.validate_by_speed(servers)
+
+for server, latency in results:
+    print(f"{server}: {latency:.2f}ms")
+```
+
+```python
+# High concurrency for large lists
+validator = Validator(concurrency=100)
+results = validator.validate_by_speed(large_server_list, max_ms=100)
+```
+
+```python
+# Async usage
+import asyncio
+
+async def main():
+    validator = Validator(concurrency=200)
+    results = await validator.validate_by_speed_async(servers)
+    return results
+
+results = asyncio.run(main())
+```
+
+---
+
+## Examples
+
+### CLI Usage
+
+```bash
+# Speed filtering
+pyresolvers -tL resolvers.txt --min-speed 10 --max-speed 100
+
+# Silent mode (IPs only)
+pyresolvers -tL resolvers.txt --silent
+
+# Exclude specific servers
+pyresolvers -tL all_resolvers.txt -e 8.8.8.8
+
+# High performance (100 concurrent)
+pyresolvers -tL large_list.txt -threads 100
+```
+
+### Library Usage
+
+**Filter by Speed:**
+```python
+validator = Validator(concurrency=50)
+fast = validator.validate_by_speed(servers, max_ms=50)
+```
+
+**Detailed Results:**
+```python
+results = validator.validate(servers)
+for r in results:
+    if r.valid:
+        print(f"✓ {r.server}: {r.latency_ms:.2f}ms")
+    else:
+        print(f"✗ {r.server}: {r.error}")
+```
+
+**JSON Export:**
+```python
+json_output = validator.to_json(servers, max_ms=100, pretty=True)
+with open('valid_dns.json', 'w') as f:
+    f.write(json_output)
+```
+
+**Streaming (Memory Efficient):**
+```python
+async def process_huge_list():
+    validator = Validator(concurrency=100)
+    async for server, latency in validator.validate_streaming_async(servers):
+        print(f"{server}: {latency:.2f}ms")
+
+asyncio.run(process_huge_list())
+```
+
+### Cronjob Example
+
+**Bash Script:**
+```bash
+#!/bin/bash
+# /usr/local/bin/dns_monitor.sh
+
+API_URL="https://api.example.com/dns/update"
+OUTPUT_DIR="/var/lib/dns-monitor"
+
+mkdir -p "$OUTPUT_DIR"
+
+# Validate and save
+pyresolvers -tL https://public-dns.info/nameservers.txt \
+    --max-speed 100 \
+    --format json \
+    -o "$OUTPUT_DIR/resolvers.json"
+
+# Send to API
+curl -X POST "$API_URL" \
+    -H "Content-Type: application/json" \
+    -d @"$OUTPUT_DIR/resolvers.json"
+```
+
+**Crontab:**
+```cron
+# Run every 6 hours
+0 */6 * * * /usr/local/bin/dns_monitor.sh >> /var/log/dns-monitor.log 2>&1
+```
+
+---
+
+## API Reference
+
+### Validator
+
+High-performance async DNS validator.
+
+```python
+Validator(
+    trusted_resolvers: Optional[List[str]] = None,  # ["1.1.1.1", "8.8.8.8"]
+    test_domains: Optional[List[str]] = None,       # ["bet365.com", "telegram.com"]
+    poison_check_domains: Optional[List[str]] = None,
+    baseline_domain: str = "bet365.com",
+    query_prefix: str = "dnsvalidator",
+    concurrency: int = 50,                          # Async concurrency
+    timeout: int = 5,                               # DNS timeout (seconds)
+    use_fast_timeout: bool = False,                 # Fast dead server detection (optional speedup)
+    batch_size: int = 100,                          # Memory management
+    verbose: bool = False
+)
+```
+
+**Methods:**
+
+- `validate(servers)` → `List[ValidationResult]` - Validate servers
+- `validate_by_speed(servers, min_ms, max_ms)` → `List[Tuple[str, float]]` - Get valid servers ordered by speed
+- `to_json(servers, min_ms, max_ms)` → `str` - Export as JSON
+- `to_text(servers, min_ms, max_ms, show_speed)` → `str` - Export as text
+
+**Async Methods:**
+
+- `await validate_async(servers)` - Async validation
+- `await validate_by_speed_async(servers, min_ms, max_ms)` - Async speed validation
+- `async for server, latency in validate_streaming_async(servers)` - Async streaming
+
+### ValidationResult
+
+```python
+@dataclass
+class ValidationResult:
+    server: str
+    valid: bool
+    latency_ms: float
+    error: Optional[str] = None
+```
+
+---
+
+## CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-t SERVER` | Test single server |
+| `-tL FILE/URL` | Test from file or URL |
+| `-e SERVER` | Exclude server |
+| `-eL FILE/URL` | Exclude from file/URL |
+| `-r DOMAIN` | Baseline domain (default: bet365.com) |
+| `-threads N` | Concurrency (default: 5) |
+| `-timeout N` | Timeout seconds (default: 600) |
+| `-o FILE` | Output file |
+| `--format FORMAT` | text, json, text-with-speed |
+| `--max-speed MS` | Max latency filter (ms) |
+| `--min-speed MS` | Min latency filter (ms) |
+| `--silent` | Only output IPs |
+| `-v, --verbose` | Verbose output |
+| `--no-color` | Disable colors |
+
+---
+
+## Performance Tips
+
+- **Concurrency**: 50-100 for best performance on most systems
+- **Timeout**: Lower (3s) for speed, higher (10s+) for thoroughness
+- **Fast Timeout**: Enable (`use_fast_timeout=True`) for 30-50% speedup (may miss slow servers)
+- **Batch Size**: Increase for more memory, decrease for less
+- **Network**: Run from VPS to avoid ISP throttling
+
+### Optimization Features
+
+1. **Async I/O** - Non-blocking DNS queries with aiodns
+2. **Parallel Baseline** - Queries trusted resolvers simultaneously
+3. **Fast Timeout** - 1s initial timeout for dead server detection
+4. **Combined Queries** - Reduces DNS round trips
+5. **Batch Processing** - Memory-efficient for huge lists
+6. **Streaming** - Progressive results without holding all in memory
+
+---
+
+## How It Works
+
+1. **Baseline** - Query trusted DNS (Cloudflare, Google) for ground truth
+2. **Poisoning Check** - Test random subdomains to detect hijacking
+3. **NXDOMAIN** - Verify correct NXDOMAIN behavior
+4. **Baseline Compare** - Ensure responses match baseline
+5. **Speed Test** - Measure latency and order results
+
+---
+
+## Important Notes
+
+### Thread Count
+
+Keep concurrency reasonable (50-100) to avoid triggering rate limits. Very high concurrency may be blocked by ISPs or DNS providers.
+
+### Domain Selection
+
+Use **non-geolocated** domains for baseline (bet365.com works well). Avoid google.com, facebook.com as they return different IPs by location.
+
+---
+
+## Project Structure
+
+```
+pyresolvers/
+├── pyresolvers/
+│   ├── __init__.py          # Package exports
+│   ├── __main__.py          # CLI entry
+│   ├── validator.py         # Async validation
+│   └── lib/core/
+│       ├── input.py         # CLI args
+│       ├── output.py        # Formatting
+│       └── __version__.py
+├── requirements.txt
+├── setup.py
+└── README.md
+```
+
+---
+
+## License
+
+GNU General Public License v3.0 - see [LICENSE](LICENSE)
+
+---
+
+## Acknowledgments
+
+Based on [dnsvalidator](https://github.com/vortexau/dnsvalidator) by:
+- **James McLean** ([@vortexau](https://twitter.com/vortexau))
+- **Michael Skelton** ([@codingo_](https://twitter.com/codingo_))
+
+Enhanced with async architecture, speed testing, and performance optimizations by Karl.
+
+---
+
+<div align="center">
+
+**[⬆ back to top](#pyresolvers)**
+
+Made with ❤️ by Karl | Based on dnsvalidator by @vortexau & @codingo_
+
+</div>

pyresolvers-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pyresolvers/__init__.py,sha256=aIdA6BsOAIAGHqX_2P5xmOPe2BrY48u9GUM3muia1Ws,830
+pyresolvers/__main__.py,sha256=nmnFQoziQgqmeWgOJt5eNYzFNdzsOdprhJB7-rylxaQ,3385
+pyresolvers/validator.py,sha256=EpgDH40bb5vZlWSozUFIpQQtELuZR0HcIsMRk9gRl-c,13761
+pyresolvers/lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyresolvers/lib/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyresolvers/lib/core/__version__.py,sha256=eJIiVTKvshwRqBCzqfJOiJwmYYTZkPA-nQ1po_XxDO8,23
+pyresolvers/lib/core/input.py,sha256=JkRH5c9AsW_c5Isiy9b8LoCIAKlNQDOS1QJqF0Letmc,6362
+pyresolvers/lib/core/output.py,sha256=rFLLiPtQhS4od1oZjT4MnMDmSa3j1EfCIM1YePTuriU,2237
+pyresolvers-1.0.0.dist-info/METADATA,sha256=yGM0b7hcsYUwHAu_Upnc7evHb6TM0n6SwvdjC1u6a6A,10855
+pyresolvers-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyresolvers-1.0.0.dist-info/entry_points.txt,sha256=kkUh0xu55gO9WRwxiMbguLC4DEy3aHd7e5YDUTzdN6I,58
+pyresolvers-1.0.0.dist-info/top_level.txt,sha256=55wYsw2v1_vxEjWtRIdfEmB5yNCl3cNL-69tSLagC1k,12
+pyresolvers-1.0.0.dist-info/RECORD,,

pyresolvers-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyresolvers-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyresolvers = pyresolvers.__main__:main

pyresolvers-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyresolvers