9aa85d8e5d
CI / test (pull_request) Failing after 2m13s
- Rewrite README.md with overview, features, installation (go install +
build from source), quick start, full CLI flag reference table,
output section descriptions, project structure, and development guide
- Add package-level doc comments to all five internal packages:
config, dns, fingerprint, output, traverse (via doc.go or existing
package-declaration files)
- Add GoDoc comments on every exported type, constant, function, and
method across all packages:
- internal/config: Config struct fields, all Parse*/Default/Validate
- internal/dns: QueryConfig, Resolver, BasicResolver, CachingResolver,
ExchangeFunc, RootServer, RootDiscoveryConfig, DecodedResponse,
ResponseClassification, all exported helpers
- internal/fingerprint: Fingerprinter, New, NewWithTimeout, Query,
FingerprintAll
- internal/traverse: Traverser, TraverserConfig, TraversalResult,
Referral, ResolutionState, Response, ResponseType, InfoCache,
Stack, TraverserHooks, EventStage, TraversalEvent, EventHandler,
CircularReferralError, UnresolvableNameserverError
- internal/output: Format, Config, Formatter, SummaryStats,
NewFormatter, AttachHooks, RunTraversal, DefaultConfig,
ComputeSummary
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: multica-agent <github@multica.ai>
7.1 KiB
7.1 KiB
ExploreDNS
ExploreDNS is a command-line DNS reconnaissance and exploration tool that performs iterative DNS traversal from the root servers down to the target domain — the same way resolvers do, but with full visibility into every step.
Unlike a standard resolver query, ExploreDNS shows you the entire delegation path: which root server was queried, which TLD server was referred to, which authoritative server finally answered, and the probability that each path was followed. It also fingerprints nameservers via version.bind and detects CNAME chains, CNAME loops, and circular referrals.
Inspired by dnstraverse.
Features
- Full delegation path visibility — every referral hop from root to authoritative
- CNAME chain following and loop detection
- DNAME synthesis — generates implicit CNAME targets from DNAME records
- Server fingerprinting — queries
version.bindCHAOS TXT on all encountered servers - JSON output — machine-readable structured output for scripting and pipelines
- Fast mode — shared glue cache across branches (on by default)
- Configurable transport — UDP with TCP fallback, or TCP-only
- All 13 root servers — optionally query every root for maximum coverage
- IPv6 support — follow AAAA glue records when available
- Probability weighting — each result carries a probability so you know how authoritative it is
Installation
go install (recommended)
go install github.com/hits/ExploreDNS/cmd/exploredns@latest
Build from source
git clone https://github.com/hits/ExploreDNS.git
cd ExploreDNS
go build -o bin/exploredns ./cmd/exploredns
Or via the Makefile:
make build
The binary is placed at bin/exploredns.
Quick Start
# Basic A record traversal
exploredns www.example.com
# Query MX records
exploredns --type MX example.com
# JSON output for scripting
exploredns --json www.example.com | jq .summary
# Use all 13 root servers
exploredns --all-root-servers www.example.com
# TCP only (no UDP)
exploredns --allow-tcp --always-tcp www.example.com
# Quiet mode — results only, no headers
exploredns --quiet --no-show-progress --no-show-resolves --no-show-servers www.example.com
# Debug mode (shows config and traversal steps)
exploredns --debug www.example.com
# Library-level debug
exploredns -dd www.example.com
Examples
Basic traversal
$ exploredns www.example.com
ExploreDNS - exploring: www.example.com (type: A)
1 198.41.0.4 (A)
2 192.5.6.30 (A)
3 199.43.135.53 (A)
4 93.184.216.34 (A)
4 100% answered with 93.184.216.34
The following servers were encountered:
a.root-servers.net: 198.41.0.4
a.iana-servers.net: 199.43.135.53
a.gtld-servers.net: 192.5.6.30
Results:
4 100% answered with 93.184.216.34
Summary:
100% answered with 93.184.216.34
MX records
exploredns --type MX gmail.com
JSON output
exploredns --json www.example.com
{
"domain": "www.example.com",
"query_type": "A",
"results": [
{
"depth": 3,
"probability": 1,
"response_type": "answer",
"server": "93.184.216.34",
"answers": ["www.example.com. 3600 IN A 93.184.216.34"]
}
],
"servers": [
{"name": "a.root-servers.net", "ips": ["198.41.0.4"]},
{"name": "a.gtld-servers.net", "ips": ["192.5.6.30"]},
{"name": "a.iana-servers.net", "ips": ["199.43.135.53"]}
],
"summary": {
"answers": [{"rdata": "93.184.216.34", "probability": 1}]
}
}
All root servers
exploredns --all-root-servers www.example.com
Uses all 13 root servers. Each branch carries a probability of approximately 1/13.
Verbose mode
exploredns -v www.example.com
Adds bailiwick information to each progress line.
CLI Reference
Usage:
exploredns [flags] <domain>
Query Options
| Flag | Default | Description |
|---|---|---|
--type |
A |
Record type: A, AAAA, NS, CNAME, MX, TXT, SOA, PTR, ANY |
--root-server |
(auto) | Override the root server IP address |
--all-root-servers |
false |
Use all 13 root servers |
--root-aaaa |
false |
Include IPv6 addresses of root servers |
--follow-aaaa |
false |
Follow only AAAA glue records for referrals |
Transport Options
| Flag | Default | Description |
|---|---|---|
--udp-size |
2048 |
EDNS0 UDP payload size (512–4096) |
--allow-tcp |
true |
TCP fallback when UDP response is truncated |
--always-tcp |
false |
Always use TCP (requires --allow-tcp) |
--retries |
2 |
Number of retry attempts per query (0–10) |
Traversal Options
| Flag | Default | Description |
|---|---|---|
--max-depth |
20 |
Maximum referral depth (1–100) |
--fast |
true |
Fast mode: sibling branches share a glue cache |
Output Options
| Flag | Default | Description |
|---|---|---|
--verbose, -v |
false |
Verbose output (shows bailiwick on each line) |
--debug, -d |
false |
Application debug output to stderr |
-dd |
false |
Library-level debug (equivalent to -d -d) |
--quiet, -q |
false |
Suppress introductory banner |
--json |
false |
Output results as a single JSON document |
--show-progress / --no-show-progress |
on | Per-referral traversal progress lines |
--show-resolves / --no-show-resolves |
on | Nameserver address resolution detail |
--show-servers / --no-show-servers |
on | Encountered servers list |
--show-versions / --no-show-versions |
on | Server version.bind fingerprints |
--show-all-stats / --no-show-all-stats |
on | Per-result stats as they arrive |
--show-results / --no-show-results |
on | Terminal results section |
--show-summary-results / --no-show-summary-results |
on | Probability summary section |
Tip: Set
NO_COLOR=1in your environment to disable ANSI colour codes.
Output Sections
Traversal progress
1 198.41.0.4 (A)
2 192.5.6.30 (A)
Each line shows the hop number, the server IP, and the query type. Indentation reflects delegation depth.
Servers list
Lists every nameserver encountered, mapped to its IP address, with optional version.bind fingerprints.
Results
Terminal outcomes (answers, NXDOMAIN, SERVFAIL, etc.) for each leaf of the traversal tree.
Summary
Aggregates terminal results by response type, weighted by probability. Answer results are grouped by RDATA value.
Project Structure
cmd/exploredns/ CLI entry point and flag parsing
internal/config/ Config struct, validation, and usage text
internal/dns/ DNS query primitives, response decoding, root discovery
internal/traverse/ Iterative DNS tree traversal engine
internal/fingerprint/ DNS server version fingerprinting
internal/output/ Text and JSON output formatters
Development
make test # run tests
make lint # run go vet
make clean # remove build artifacts
To run tests with the race detector:
go test -race ./...
License
MIT