GitHub - hoxtxnDev/HXDNS-Python

📋 Table of Contents / Índice

EN	ES
1. Features	1. Características
2. Ghost Protocol	2. Ghost Protocol
3. Installation	3. Instalación
4. Usage	4. Uso
5. Examples	5. Ejemplos
6. Output	6. Salida
7. Testing	7. Pruebas
8. Compatibility	8. Compatibilidad
9. Disclaimer	9. Descargo

🚀 Features · Características

#	EN	ES
1	Subdomain enumeration via wordlist brute-force	Enumeración de subdominios por diccionario
2	Full record resolution: A, AAAA, MX, NS, TXT, CNAME, SOA	Resolución completa de registros DNS
3	Zone transfer (AXFR) against all NS servers	Transferencia de zona AXFR
4	Reverse PTR lookup for discovered IPs	Búsqueda inversa PTR
5	Concurrent resolution via `ThreadPoolExecutor`	Resolución concurrente por hilos
6	Structured JSON output for pipelines	Salida JSON estructurada
7	Ghost Protocol evasion — bypass AI/software detection	Protocolo Fantasma — evade detección IA/software
8	DNS server fingerprinting (BIND, Unbound, PowerDNS, etc.)	Fingerprinting de servidores DNS
9	Zero external dependencies (stdlib only)	Cero dependencias externas
10	Semantic exit codes	Códigos de salida semánticos

👻 Ghost Protocol · Protocolo Fantasma

hxdns is the only stdlib DNS recon tool with a built-in evasion engine that bypasses AI/software-based DNS scan detection.

hxdns es la unica herramienta DNS recon con motor de evasion incorporado que evita la deteccion por IA/software.

Techniques / Técnicas

Technique	Flag	Effect
🎲 Random TXID	`--stealth` (auto)	Non-deterministic transaction IDs per query
⏱️ Timing Jitter	`--jitter SEC`	Random delay 0..SEC between queries — breaks temporal patterns
🔀 Wordlist Shuffle	`--shuffle`	Non-sequential subdomain scanning — bypasses pattern detection
🎭 Decoy Queries	`--decoys`	Interleaves queries to google.com, cloudflare.com, etc. — blends with legit traffic
🔄 Type Polymorphism	`--stealth` (auto)	Alternates A/AAAA randomly per subdomain — varies query profile
🔬 Server Fingerprint	`--stealth` (auto)	Detects BIND, Unbound, PowerDNS, dnsmasq, Cloudflare, Google DNS
🛡️ Full Evasion	`--stealth`	Activates ALL techniques at once

How it works / Cómo funciona

Normal scan:     sub1.domain.com → sub2.domain.com → sub3.domain.com  (sequential, predictable)
Stealth scan:    sub9.domain.com → decoy(google.com) → sub3.domain.com → decoy(cloudflare.com)
                 → sub1.domain.com → [random delay 0.7s] → sub7.domain.com  (shuffled, obfuscated)

Each query uses a random transaction ID, follows a non-deterministic timing pattern, and is interleaved with legitimate traffic — making the scan indistinguishable from normal DNS activity.

Usage / Uso

# Quick stealth (auto-configured)
python hxdns.py -d example.com -w wordlist.txt --stealth

# Custom evasion
python hxdns.py -d example.com -w wordlist.txt --jitter 0.5 --shuffle --decoys

# Aggressive but stealthy
python hxdns.py -d example.com -w wordlist.txt --jitter 0.3 --shuffle --threads 200

📦 Installation · Instalación

# Clone / Clonar
git clone https://github.com/hoxtxnDev/HXDNS-Python.git
cd hxdns

# No dependencies needed! Just run.
# Sin dependencias. Solo ejecutar.
python hxdns.py --help

✅ Zero dependencies. Only Python 3.8+ required.
✅ Cero dependencias. Solo Python 3.8+ requerido.

🔧 Usage · Uso

python hxdns.py -d <DOMAIN> [OPTIONS]

Arguments / Argumentos

Argument	EN	ES	Default
`-d` `--domain`	Target domain or IP	Dominio o IP objetivo	required
`-w` `--wordlist`	Subdomain wordlist path	Ruta al diccionario	`None`
`--resolvers`	Comma-separated DNS servers	Servidores DNS separados por coma	`8.8.8.8,1.1.1.1,9.9.9.9`
`--threads`	Concurrent threads	Hilos concurrentes	`50`
`--timeout`	Query timeout in seconds	Timeout por consulta	`2.0`
`--reverse`	Enable PTR reverse lookup	Activar PTR inverso	`False`
`--output`	Output format: `text` or `json`	Formato de salida	`text`
`-v` `--verbose`	Verbose output to stderr	Salida detallada a stderr	`False`
`--stealth`	Full evasion mode (shuffle + jitter 1s + decoys)	Modo evasion total	`False`
`--jitter SEC`	Random delay 0..SEC between queries	Retardo aleatorio 0..SEG	`0.0`
`--shuffle`	Randomize wordlist order	Aleatorizar orden del diccionario	`False`
`--decoys`	Interleave decoy queries	Intercalar consultas señuelo	`False`

💻 Examples · Ejemplos

Basic scan · Escaneo básico

python hxdns.py -d example.com

With wordlist · Con diccionario

python hxdns.py -d example.com -w subdomains.txt --threads 100

JSON output · Salida JSON

python hxdns.py -d example.com --resolvers 8.8.8.8,1.1.1.1 --output json

Reverse PTR · PTR inverso

python hxdns.py -d 192.168.1.1 --reverse

Stealth scan · Escaneo sigiloso (Ghost Protocol)

python hxdns.py -d example.com \
  -w subdomains.txt \
  --stealth \
  -v

Custom evasion · Evasión personalizada

python hxdns.py -d example.com \
  -w subdomains.txt \
  --jitter 0.5 \
  --shuffle \
  --decoys \
  --threads 100

Full scan · Escaneo completo

python hxdns.py -d example.com \
  -w /usr/share/wordlists/subdomains.txt \
  --threads 200 \
  --timeout 3 \
  --resolvers 8.8.8.8,1.1.1.1,9.9.9.9 \
  --reverse \
  --output json \
  -v

📄 Output · Salida

Text format (default)

+----------------------------------------------------+
|                    hxdns  v1.0.0                   |
|           DNS Reconnaissance - Seguridad DNS       |
|              (c) 2026 @hoxtxnDev - MIT             |
+----------------------------------------------------+

  [*] Target / Objetivo  : example.com
  [*] Wordlist           : -

  > A (2)
    example.com                              93.184.216.34
    example.com                              2606:2800:220:1:248:1893:25c8:1946

  > MX (1)
    example.com                              0 .

  > NS (2)
    example.com                              a.iana-servers.net
    example.com                              b.iana-servers.net

  > SOA (1)
    example.com                              ns.icann.org noc.dns.icann.org

  > Subdomains (3):
    * www.example.com
    * mail.example.com
    * ftp.example.com

-------------------------------------------------------
  [+] Scan complete: 12.45s - 9 records

JSON format

{
  "target": "example.com",
  "records": [
    {
      "hostname": "example.com",
      "record_type": "A",
      "value": "93.184.216.34",
      "source": "resolution"
    }
  ],
  "subdomains": ["www.example.com", "mail.example.com"],
  "axfr_success": [],
  "errors": [],
  "duration_s": 12.45,
  "dns_server": "Unbound (score:2)",
  "evasion_active": true,
  "isp": "",
  "total_records": 8
}

Exit codes · Códigos de salida

Code	Meaning (EN)	Significado (ES)
`0`	Findings present	Hallazgos encontrados
`1`	Fatal error — nothing resolved	Error fatal — nada resuelto
`2`	Clean run, no results	Escaneo limpio sin resultados
`130`	Interrupted by user (Ctrl+C)	Interrumpido por el usuario

🧪 Testing · Pruebas

Syntax check / Verificación de sintaxis

python -c "import py_compile; py_compile.compile('hxdns.py', doraise=True)"

Quick smoke test / Prueba rápida

# JSON output (fast, no wordlist)
python hxdns.py -d example.com --timeout 2 --output json

# Text output with verbose
python hxdns.py -d example.com --timeout 2 -v

Test with wordlist (if available)

# Create a minimal test wordlist
echo -e "www\nmail\nftp\napi" > test_words.txt

# Run brute-force
python hxdns.py -d example.com -w test_words.txt --threads 10

Known working domains for testing

Domain	Purpose
`example.com`	ICANN reserved — safe for testing
`google.com`	Real-world DNS (has all record types)
`nonexistent-domain-xyz123456789.com`	Empty result (exit 2)
`127.0.0.1`	Reverse PTR (localhost)

Exit code testing / Prueba de códigos de salida

python hxdns.py -d nonexistent-domain-xyz123456789.com --timeout 1
echo "Exit: $?"   # → 2 (clean, no results)

python hxdns.py -d google.com --timeout 2
echo "Exit: $?"   # → 0 (findings present)

Test results / Resultados de pruebas

┌─────────────────────────────────────────────────────┐
│                T E S T   R E S U L T S                          │
│             Resultados de pruebas · 2026-06-18               │
└─────────────────────────────────────────────────────┘

  12/12 unit tests:  ✅ PASS  (0 failed)

  Test      Description                          Status
  ─────────────────────────────────────────────────────
  1         DNSWire.build_query                  ✅  26 bytes
  2         parse_resolvers IP filter            ✅  invalid → filtered
  3         DNSRecord dataclass                  ✅  hostname/type/value
  4         ScanResult dataclass + to_dict       ✅  evasion_active field
  5         DNSWire.parse_response empty         ✅  []
  6         DNSWire.parse_response header only   ✅  []
  7         Resolver.query non-existent          ✅  list (empty)
  8         print_header output                  ✅  banner + target
  9         print_report output                  ✅  records + subdomains
  10        CLI --help                           ✅  Ghost Protocol options
  11        GhostProtocol.pre_query              ✅  random TXID (None)
  12        fingerprint_server                   ✅  BIND 9 detected

  Integration tests (live DNS):
  ─────────────────────────────────────────────────────
  example.com   → 10 records  (A, AAAA, MX, NS, TXT, SOA)  ✅
  google.com    → 16 records  (A, AAAA, MX, NS, SOA)       ✅
  non-existent  →  0 records  (exit 2)                      ✅
  example.com   → 10 records  (--stealth mode)              ✅

  All tests passed. No regressions.

🔌 Compatibility · Compatibilidad

Platform	Status	Notes
Python 3.8+	✅ Full	All features work
Python 3.7	⚠️ Limited	Remove `from __future__ import annotations`
Windows	✅ Full	Tested on 10/11 — Server 2019+
Linux	✅ Full	Tested on Ubuntu 20.04+, Debian, Arch
macOS	✅ Full	Tested on 12+ (Monterey)
Docker	✅ Full	See Docker section below
Termux (Android)	✅ Full	Python 3.11+ via `pkg install python`
WSL	✅ Full	Windows Subsystem for Linux
BSD	✅ Likely	Not tested, but stdlib should work

Docker

FROM python:3.12-alpine
COPY hxdns.py /usr/local/bin/hxdns
RUN chmod +x /usr/local/bin/hxdns
ENTRYPOINT ["hxdns"]

docker build -t hxdns .
docker run --rm hxdns -d example.com

ASCII-safe output

All output uses only ASCII characters for maximum terminal compatibility.
Works on any terminal emulator — including cmd.exe, PowerShell, xterm, PuTTY, serial consoles.

  ╔══════════════════════════════════════════════════════════════════╗
  ║                     D I S C L A I M E R                        ║
  ║                 D E S C A R G O   D E                          ║
  ║               R E S P O N S A B I L I D A D                    ║
  ╚══════════════════════════════════════════════════════════════════╝

  EN: This tool is intended for authorized security testing
  and educational purposes only. The author takes no
  responsibility for any misuse or damage caused by this
  tool. Unauthorized scanning of systems you do not own or
  have explicit permission to test is illegal in many
  jurisdictions.

  ES: Esta herramienta es para pruebas de seguridad
  autorizadas y fines educativos. El autor no se hace
  responsable por el mal uso o daños causados. Escanear
  sistemas sin autorización explícita es ilegal.

  By using this software you agree to:
  * Use it only on systems you own or have permission to test
  * Comply with all applicable laws and regulations
  * Not use it for any malicious or harmful purposes

  Al usar este software aceptas:
  * Usarlo solo en sistemas propios o con permiso explícito
  * Cumplir con todas las leyes y regulaciones aplicables
  * No usarlo para fines maliciosos o dañinos

📚 Version History / Historial de versiones

Version	Date	Changes
v1.1.0	2026-06-18	Ghost Protocol evasion engine — stealth, jitter, shuffle, decoys, fingerprinting
v1.0.0	2026-06-18	Initial release — core features

🤝 Contribute · Contribuir

hxdns is open-source and welcomes contributions of all kinds:

Area	EN	ES
🐛 Bugs	Open an issue with reproduction steps	Abre un issue con pasos para reproducir
💡 Ideas	Feature requests via GitHub Issues	Solicitudes de funcionalidad
🔧 Code	PRs reviewed within 72h	PRs revisados dentro de 72h
📖 Docs	Translations, examples, typos	Traducciones, ejemplos, erratas
🧪 Testing	Add test cases for edge scenarios	Añadir casos de prueba

# Contribute in 3 steps / Contribuye en 3 pasos
git clone https://github.com/hoxtxnDev/HXDNS-Python.git
cd hxdns
# ... hack, hack, hack ...
git commit -m "feat: your contribution"
git push origin main

💬 Questions? Open a Discussion
💬 ¿Preguntas? Abre un Discussion

  ╔════════════════════════════════════════════════╗
  ║     hxdns  ·  © 2026  @hoxtxnDev  ·  MIT     ║
  ║         Made with 👁️ for the security community        ║
  ╚════════════════════════════════════════════════╝

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
hxdns.py		hxdns.py

Latest commit

History

Folders and files

Repository files navigation