ExploreDNS/README.md

ExploreDNS

ExploreDNS is a comprehensive DNS traversal tool that explores every possible resolution path for a domain — from the root servers all the way down — just like a real iterative resolver, but without stopping at the first answer. It follows every referral exhaustively, collates all results, and presents them in a structured, human-readable (or JSON) report.

Inspired by the classic dnstraverse Ruby tool, ExploreDNS is a modern Go rewrite that produces a self-contained binary with no runtime dependencies.

---

Features

• Full iterative traversal — queries root servers and follows every referral branch, mirroring real resolver behaviour
• All root servers — optionally query all 13 root server sets in parallel
• No-glue resolution — automatically resolves nameserver addresses when referrals lack glue records
• DNS server fingerprinting — identifies server software via version.bind CHAOS queries
• Multiple output formats — coloured text tree and machine-readable JSON
• Configurable transport — UDP/TCP, EDNS0 buffer size, retries, timeouts
• Fast mode — shares glue across branches for speed; disable for independent paths
• CNAME tracking — follows CNAME chains and detects loops

---

Installation

Pre-built binary

Download the latest release binary for your platform from the Releases page.

Build from source

Requires Go 1.21 or later.

git clone https://gitea.hansenits.com.au/hits/ExploreDNS.git
cd ExploreDNS
make build          # produces bin/exploredns

go install

go install github.com/hits/ExploreDNS/cmd/exploredns@latest

---

Quick Start

# Basic A record traversal
exploredns www.example.com

# MX records for a domain
exploredns --type MX example.com

# Use all 13 root server sets
exploredns --all-root-servers www.example.com

# JSON output
exploredns --json www.example.com

# Quiet (results only)
exploredns --quiet www.example.com

# Debug mode
exploredns --debug www.example.com

# Library-level debug (very verbose)
exploredns --dd www.example.com

# Force TCP
exploredns --allow-tcp --always-tcp www.example.com

# Disable fast mode (independent paths per branch)
exploredns --fast=false www.example.com

# Increase traversal depth limit
exploredns --max-depth 30 www.example.com

---

CLI Reference

Usage:
  exploredns [flags] <domain>

Query Options:
  --type <TYPE>           Record type to query (default: A)
                          Supported: A, AAAA, NS, CNAME, MX, TXT, SOA, PTR, ANY
  --root-server <IP>      Override the root server IP address
  --all-root-servers      Query all 13 root server sets (default: false)
  --root-aaaa             Include IPv6 addresses for root servers (default: false)
  --follow-aaaa           Only follow AAAA addresses for referrals (default: false)

Transport Options:
  --udp-size <N>          EDNS0 UDP buffer size, 512–4096 (default: 2048)
  --allow-tcp             Fall back to TCP on truncation (default: true)
  --always-tcp            Always use TCP (requires --allow-tcp)
  --retries <N>           Per-server retry count, 0–10 (default: 2)

Traversal Options:
  --max-depth <N>         Maximum referral depth, 1–100 (default: 20)
  --fast / --fast=false   Share glue cache across branches (default: true)

Output Options:
  --json                  Emit results as JSON instead of text
  --verbose, -v           Show extra detail in text output
  --debug, -d             Enable application debug messages (stderr)
  --dd                    Enable library-level debug messages (very verbose)
  --quiet, -q             Suppress header and supplementary information
  --show-progress         Show live traversal progress (default: true)
  --no-show-progress      Hide traversal progress
  --show-resolves         Show glue-resolution steps (default: true)
  --no-show-resolves      Hide glue-resolution steps
  --show-servers          Show which servers were queried (default: true)
  --no-show-servers       Hide server list
  --show-versions         Show DNS server software versions (default: true)
  --no-show-versions      Hide server versions
  --show-all-stats        Show query statistics (default: true)
  --no-show-all-stats     Hide statistics
  --show-results          Show per-branch query results (default: true)
  --no-show-results       Hide per-branch results
  --show-summary-results  Show deduplicated summary section (default: true)
  --no-show-summary-results  Hide summary section

---

Output Formats

Text (default)

Coloured, hierarchical tree output showing each traversal branch, the servers queried, referrals followed, and final answers. Disable colour by setting the NO_COLOR environment variable.

JSON (--json)

Structured JSON array of traversal results. Suitable for piping into jq or ingesting into other tools. Each element contains the referral metadata, the responding server, the response type, and the decoded DNS records.

---

Comparison with dnstraverse

Feature	dnstraverse (Ruby)	ExploreDNS (Go)
Language	Ruby	Go
Self-contained binary	No	Yes
All root servers	Yes	Yes
No-glue resolution	Yes	Yes
JSON output	No	Yes
Server fingerprinting	Yes	Yes
CNAME loop detection	Partial	Yes
Active development	Dormant	Active

---

Project Structure

cmd/exploredns/        CLI entry point and flag parsing
internal/config/       Configuration types, validation, and usage text
internal/dns/          DNS query layer, root discovery, transport
internal/traverse/     Core traversal engine, referral resolution, caching
internal/fingerprint/  DNS server version fingerprinting (version.bind CHAOS)
internal/output/       Result formatting — text tree and JSON renderers
internal/integration/  End-to-end integration tests

---

Development

make build   # compile binary to bin/exploredns
make test    # run all unit and integration tests
make lint    # run go vet
make clean   # remove build artefacts

Run a single package's tests:

go test ./internal/traverse/...

---

Architecture Overview

main → config.Parse → traverse.NewTraverser → traverse.Traverse
                                   │
                         ┌─────────▼──────────┐
                         │  Stack (BFS/DFS)   │
                         │  Referral queue    │
                         └─────────┬──────────┘
                                   │ per referral
                         ┌─────────▼──────────┐
                         │ processReferral    │
                         │  ├─ resolveGlue   │  (no-glue NS resolution)
                         │  └─ queryServer   │  (dns.Query)
                         └─────────┬──────────┘
                                   │
                     ┌─────────────▼──────────────┐
                     │  Response classifier        │
                     │  Answer / Referral /        │
                     │  CNAME / NXDOMAIN /         │
                     │  SERVFAIL / Error           │
                     └─────────────┬──────────────┘
                                   │
                         ┌─────────▼──────────┐
                         │  output.Formatter  │
                         │  (text | JSON)     │
                         └────────────────────┘

The traversal engine (internal/traverse) maintains a work stack of Referral objects. Each referral represents a single query to a single set of nameservers. When a response contains further referrals, child Referral objects are pushed onto the stack and processed in turn.

The InfoCache is used to store glue records discovered during traversal. In fast mode (default), a single root cache is shared across all branches so that glue discovered early is reused. In non-fast mode, each branch gets its own independent cache.

---

License

MIT — see LICENSE.