Skip to content

Commit 661588e

Browse files
TMHSDigitalclaude
andcommitted
refactor(dns,scan): one resolve path and a dns.Lookup options value (#163)
Scan workers, scan.Verify, the wildcard near-miss probes and the preflight now share Config.resolve (test hook, else simulation, else the trusted resolver with retries), and settle() is the one rule that a cancelled lookup is not a failure. Run and Verify clamp Attempts to at least 1 once at the top instead of at each call site. The internal/dns lookup helpers take a dns.Lookup value (resolver, timeout, attempts, types, logger) instead of 6-7 positional parameters, so a swapped attempts/types argument no longer compiles; Simulation replaces SimulateResolve's positional seed and hit rate. pkg/subenum's public API is unchanged. The one behaviour change: a scan.Config built directly with Attempts 0 now makes one attempt instead of failing every lookup without a query (the CLI and pkg/subenum already defaulted it to 1). New TestVerifyResolvesLikeTheScan checks Verify and the scan agree in simulated, hooked and local-server modes with Attempts 0, 1 and 2. Fixes #163 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LpkeXSPwrzd7ZCuX3no7gD
1 parent c234c12 commit 661588e

19 files changed

Lines changed: 324 additions & 201 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2525

2626
### Fixed
2727
- On Windows, `-simulate-zone` labs and the test DNS server no longer fail to start about a quarter of the time with "no free UDP+TCP port pair": after a failed TCP bind the server retries on random ports instead of the next OS-assigned one, which stayed inside the same reserved port block (#204).
28+
- A `scan.Config` built directly with `Attempts: 0` now makes one attempt per name instead of passing preflight and then failing every lookup without a query. Scan workers, `scan.Verify` and the wildcard near-miss probes share one resolve path (test hook, simulation, or the trusted resolver), and the `internal/dns` lookup helpers take a `dns.Lookup` value (resolver, timeout, attempts, types, logger) instead of long positional parameter lists, so a swapped attempts/types argument no longer compiles (#163).
2829

2930
## [0.10.0] - 2026-11-08
3031

‎docs/ARCHITECTURE.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,13 @@ internal/scan/scope.go - -exclude patterns (ValidateExcludes, IsExcluded
6363
internal/scan/settings.go - Setting tokens and the one table naming each setting as flag, Config field and form label (Render, Names)
6464
internal/scan/verdict.go - Run-quality verdicts (Stats.Verdict, VerdictRank)
6565
internal/scan/verify.go - Verify: re-check names against the trusted resolver (used by -diff)
66-
internal/dns/resolver.go - NewResolver, ResolveTypes, ResolveDomainWithRetry, Classify,
67-
CheckWildcard, FingerprintWildcard, ParseTypes
66+
internal/dns/resolver.go - NewResolver, Lookup (ResolveTypes, Resolve, CheckWildcard,
67+
FingerprintWildcard), Classify, ParseTypes
6868
internal/dns/transport.go - UDP (TCP fallback), DNS over TLS and DNS over HTTPS dialers
6969
internal/dns/pool.go - Pool: the -r resolver pool (health benching, canaries, second opinions)
7070
internal/dns/ratelimit.go - RateLimiter, WithLimiter (per-wire-query pacing)
7171
internal/dns/takeover.go - TakeoverProvider, TakeoverHint (dangling or takeover-prone CNAMEs)
72-
internal/dns/simulate.go - SimulateResolve (seeded synthetic DNS)
72+
internal/dns/simulate.go - Simulation.Resolve (seeded synthetic DNS)
7373
internal/output/writer.go - Thread-safe Writer (results to stdout, diagnostics to stderr)
7474
internal/output/file.go - File: atomically replaced -o results file
7575
internal/output/summary.go - Summary / TargetSummary, WriteSummaryFile
@@ -135,16 +135,16 @@ tools/wordlist-gen.go - Standalone wordlist generator
135135
* **Flagging**: every contradiction counts against the member; three take it out of rotation for the rest of the run. If every member is flagged, the trusted resolver answers alone.
136136

137137
Per-member counts appear in the run-quality report.
138-
* **Lookups**: `dns.ResolveTypes` performs one lookup per requested record type (A and AAAA via `LookupIP`, CNAME via `LookupCNAME`; default `dns.DefaultTypes`, A and AAAA) and returns typed `dns.Record{Type, Value}` results, the time spent, and the most severe error. Each type gets its own timeout, so a slow A answer cannot starve AAAA or CNAME. Names are queried as absolute (trailing dot) so resolv.conf search suffixes never multiply queries. `dns.ResolveWithLog` adds verbose per-lookup lines through a `dns.Logf` callback (the package never writes to stderr itself; `dns.StderrLogf` is the unsynchronized fallback). `dns.ResolveDomain` is a convenience wrapper that reports only whether A/AAAA records exist.
139-
* **Retries and classification**: `dns.ResolveDomainWithRetry` calls `ResolveWithLog` up to the `-attempts` count with a short linear backoff, and returns the records plus a `dns.Outcome`: `OutcomeFound`, `OutcomeNXDomain`, `OutcomeTimeout`, `OutcomeRefused`, `OutcomeOther`, or `OutcomeCanceled`. `dns.Classify` maps a resolver error onto an outcome. NXDOMAIN (including NODATA, a name with no records of the requested types) is definitive and not retried; any infrastructure failure on one type outranks a not-found answer on another, so a SERVFAIL is never mistaken for NXDOMAIN.
140-
* **Rate limiting**: `dns.RateLimiter` hands out evenly spaced reservations; `dns.WithLimiter` attaches it to a context. `ResolveTypes` reserves one slot per query a lookup is expected to send (one for A or AAAA, three for CNAME, since Go's `LookupCNAME` sends A, AAAA and CNAME queries) before that lookup's timeout starts. A per-lookup `wireBudget` travels on the context into the `Dial` hook: Go's resolver dials once per query, so any dial beyond the reserved slots (Go's own internal retries) waits for another slot. `-rate` therefore bounds queries on the wire, including retries, wildcard probes and the preflight. The same hook notices REFUSED responses, which Go reports only as "server misbehaving", and names the server actually dialed in errors.
138+
* **Lookups**: a `dns.Lookup` value names the resolver, per-type timeout, attempt count, record types and verbose logger, and the lookup helpers are its methods, so a swapped argument cannot compile. `Lookup.ResolveTypes` performs one lookup per requested record type (A and AAAA via `LookupIP`, CNAME via `LookupCNAME`; default `dns.DefaultTypes`, A and AAAA) and returns typed `dns.Record{Type, Value}` results, the time spent, and the most severe error. Each type gets its own timeout, so a slow A answer cannot starve AAAA or CNAME. Names are queried as absolute (trailing dot) so resolv.conf search suffixes never multiply queries. `Lookup.Logf` receives verbose per-lookup lines (the package never writes to stderr itself; `dns.StderrLogf` is the unsynchronized fallback).
139+
* **Retries and classification**: `Lookup.Resolve` looks the name up `Lookup.Attempts` times at most (at least once) with a short linear backoff, and returns the records plus a `dns.Outcome`: `OutcomeFound`, `OutcomeNXDomain`, `OutcomeTimeout`, `OutcomeRefused`, `OutcomeOther`, or `OutcomeCanceled`. `dns.Classify` maps a resolver error onto an outcome. NXDOMAIN (including NODATA, a name with no records of the requested types) is definitive and not retried; any infrastructure failure on one type outranks a not-found answer on another, so a SERVFAIL is never mistaken for NXDOMAIN.
140+
* **Rate limiting**: `dns.RateLimiter` hands out evenly spaced reservations; `dns.WithLimiter` attaches it to a context. `Lookup.ResolveTypes` reserves one slot per query a lookup is expected to send (one for A or AAAA, three for CNAME, since Go's `LookupCNAME` sends A, AAAA and CNAME queries) before that lookup's timeout starts. A per-lookup `wireBudget` travels on the context into the `Dial` hook: Go's resolver dials once per query, so any dial beyond the reserved slots (Go's own internal retries) waits for another slot. `-rate` therefore bounds queries on the wire, including retries, wildcard probes and the preflight. The same hook notices REFUSED responses, which Go reports only as "server misbehaving", and names the server actually dialed in errors.
141141
* **Wildcard detection**: probes resolve random 32-character hex labels (`dns.RandomLabel`) under a domain for the scan's record types, each with the scan's `-attempts`, on the trusted resolver. If any probe resolves, the domain is a wildcard and the union of the answers is its fingerprint.
142-
* `dns.FingerprintWildcard` checks the scan root, whose fingerprint filters every result. It starts with five probes. If the fingerprint grew after the first probe (a wildcard served from a rotating CDN or load-balancer pool), it keeps probing until the fingerprint has not grown for max(8, 4 x its size) consecutive probes, up to 128 probes in all, so the whole address pool is learned rather than the few addresses the first probes happened to see.
143-
* `dns.CheckWildcard` is the cheap variant used for each new parent in a recursive scan: two probes, no saturation.
142+
* `Lookup.FingerprintWildcard` checks the scan root, whose fingerprint filters every result. It starts with five probes. If the fingerprint grew after the first probe (a wildcard served from a rotating CDN or load-balancer pool), it keeps probing until the fingerprint has not grown for max(8, 4 x its size) consecutive probes, up to 128 probes in all, so the whole address pool is learned rather than the few addresses the first probes happened to see.
143+
* `Lookup.CheckWildcard` is the cheap variant used for each new parent in a recursive scan: two probes, no saturation.
144144
* **Inconclusive**: a check is conclusive only when every probe ended found or NXDOMAIN/NODATA. Any timeout, refusal or other failure ends the check with an error wrapping `dns.ErrWildcardInconclusive`, which callers must never treat as "no wildcard": the scan stops unless `-force` is set, and then it runs without a fingerprint to filter with.
145145
* The worker's near-miss revalidation (see 2.4) keeps adding to the fingerprint during the scan when a rotating pool shows addresses the probes missed.
146-
* **Simulation**: `dns.SimulateResolve` derives a deterministic result from the name and the `-seed`, with `-hit-rate` percent of names resolving to synthetic records, so the same seed reproduces the same scan. No packets are sent.
147-
* **Interactions**: Workers call `dns.ResolveDomainWithRetry` (or `dns.SimulateResolve` under `-simulate`) and use the returned records and outcome; the records become an `EventResult`, the outcome feeds the `Stats` counters and the reliability guard.
146+
* **Simulation**: `dns.Simulation.Resolve` derives a deterministic result from the name and the `-seed`, with `-hit-rate` percent of names resolving to synthetic records, so the same seed reproduces the same scan. No packets are sent.
147+
* **Interactions**: Workers, `scan.Verify` and the near-miss probes resolve a name through one entry point, `Config.resolve` (the test hook, else `dns.Simulation.Resolve` under `-simulate`, else `Lookup.Resolve` on the trusted resolver); workers layer the `-r` pool on top. They use the returned records and outcome; the records become an `EventResult`, the outcome feeds the `Stats` counters and the reliability guard.
148148

149149
### 2.4. Concurrency Management (`internal/scan`)
150150

@@ -208,7 +208,7 @@ The flow of data through the `subenum` application can be summarized as follows:
208208
4. **Preflight**: Inside `scan.Run` the apex is resolved once (with retries, skipped in simulation mode). Any outcome other than Found or NXDOMAIN emits `EventError` naming the resolver and returns.
209209
5. **Wildcard detection**: `dns.FingerprintWildcard` probes random labels under the target (skipped in simulation mode). If the check is inconclusive the scan stops, unless `-force` is set, in which case it scans without filtering and says so in a `NoticeWildcard` notice. If a wildcard is detected, a `NoticeWildcard` notice is emitted and the scan stops unless `-force` is set; with `-force`, later results matching the fingerprint are filtered.
210210
6. **Dispatch**: The dispatcher generates `prefix.target` jobs lazily from the root expansion, deduplicated through a visited set, and feeds the internal `jobs` channel. It does not close `jobs` until no candidates remain and the pending counter drains to zero, or the context is cancelled.
211-
7. **Resolution**: Worker goroutines read jobs and call `dns.ResolveDomainWithRetry` (or `dns.SimulateResolve`) for the requested record types; every wire query waits on the rate limiter.
211+
7. **Resolution**: Worker goroutines read jobs and call `Lookup.Resolve` (or `dns.Simulation.Resolve`) for the requested record types; every wire query waits on the rate limiter.
212212
8. **Result Emission**: A found result that is not a wildcard answer increments the found counter and is emitted as an `EventResult` with its typed records. Every completed lookup, success or failure, increments the matching `Stats` counter. The CLI `Writer` routes results to stdout and any `-o` file in the selected `-format`; the TUI renders them in its viewport. After `EventDone` the CLI prints the per-outcome breakdown to stderr and the TUI summary line shows the same counters.
213213
9. **Recursive Expansion** (optional): when `-recursive` is set and a resolved, non-wildcard job is below the `-depth` cap, the worker hands it back to the dispatcher over the `enqueue` channel, which adds an expansion for its children and grows the progress total.
214214
10. **Progress Tracking**: Workers update atomic counters; the ticker goroutine emits `EventProgress` once per second.

‎docs/DEVELOPER_GUIDE.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -106,13 +106,13 @@ subenum/
106106
│ │ ├── ct.go # Certificate Transparency (crt.sh) client for -ct
107107
│ │ └── ct_test.go
108108
│ ├── dns/
109-
│ │ ├── resolver.go # NewResolver, ResolveTypes, ResolveDomainWithRetry, Classify,
110-
│ │ │ # CheckWildcard, FingerprintWildcard, ParseTypes
109+
│ │ ├── resolver.go # NewResolver, Lookup (ResolveTypes, Resolve, CheckWildcard,
110+
│ │ │ # FingerprintWildcard), Classify, ParseTypes
111111
│ │ ├── transport.go # UDP (TCP fallback), DNS over TLS, DNS over HTTPS dialers
112112
│ │ ├── pool.go # Pool: the -r resolver pool (benching, canaries, second opinions)
113113
│ │ ├── ratelimit.go # RateLimiter, WithLimiter (per-wire-query pacing)
114114
│ │ ├── takeover.go # TakeoverProvider, TakeoverHint (dangling CNAMEs)
115-
│ │ ├── simulate.go # SimulateResolve (seeded synthetic DNS)
115+
│ │ ├── simulate.go # Simulation.Resolve (seeded synthetic DNS)
116116
│ │ ├── testdns_test.go # Table-driven wrapper over internal/dnstest
117117
│ │ └── *_test.go # Resolver, transport, pool, rate, takeover, simulation tests
118118
│ ├── dnsserver/ # Scriptable loopback DNS server (UDP, TCP, DoT, DoH)
@@ -254,7 +254,7 @@ func TestGuideResolveOutcomes(t *testing.T) {
254254

255255
for _, tc := range testCases {
256256
t.Run(tc.name, func(t *testing.T) {
257-
_, got := ResolveDomainWithRetry(context.Background(), r, tc.domain, timeout, nil, 1, []string{"A"})
257+
_, got := Lookup{Resolver: r, Timeout: timeout, Attempts: 1, Types: []string{"A"}}.Resolve(context.Background(), tc.domain)
258258
if got != tc.want {
259259
t.Errorf("%s: outcome = %v, want %v", tc.domain, got, tc.want)
260260
}

‎internal/dns/pool.go‎

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -349,7 +349,7 @@ func (p *Pool) Disagree(a PoolAnswer, trusted Outcome) {
349349
// checkCanary asks m about a known-existing name when a check is due: always
350350
// while m is untrusted, else every poolCanaryEvery lookups. An NXDOMAIN
351351
// answer is a contradiction. Failed checks change nothing.
352-
func (p *Pool) checkCanary(ctx context.Context, m *PoolResolver, timeout time.Duration, types []string) {
352+
func (p *Pool) checkCanary(ctx context.Context, m *PoolResolver, l Lookup) {
353353
m.mu.Lock()
354354
due := !m.canaryBusy && (!m.trusted || m.sinceCanary >= poolCanaryEvery)
355355
if due {
@@ -360,13 +360,15 @@ func (p *Pool) checkCanary(ctx context.Context, m *PoolResolver, timeout time.Du
360360
return
361361
}
362362
name := p.canary()
363-
if name == "" || p.reserve(ctx, m, len(types)) != nil {
363+
if name == "" || p.reserve(ctx, m, len(l.Types)) != nil {
364364
m.mu.Lock()
365365
m.canaryBusy = false
366366
m.mu.Unlock()
367367
return
368368
}
369-
_, o := ResolveDomainWithRetry(ctx, m.resolver, name, timeout, nil, 1, types)
369+
quiet := m.lookup(l)
370+
quiet.Logf = nil
371+
_, o := quiet.Resolve(ctx, name)
370372
m.mu.Lock()
371373
m.canaryBusy = false
372374
if o == OutcomeFound || o == OutcomeNXDomain {
@@ -380,15 +382,17 @@ func (p *Pool) checkCanary(ctx context.Context, m *PoolResolver, timeout time.Du
380382
}
381383
}
382384

383-
// Resolve looks domain up through the pool, up to attempts times, each
384-
// attempt on a different healthy resolver where possible. An NXDOMAIN from a
385+
// Resolve looks domain up through the pool, up to l.Attempts times, each
386+
// attempt on a different healthy resolver where possible. l.Resolver is
387+
// unused: each attempt is one lookup on a member's own resolver, with
388+
// l.Timeout, l.Types and l.Logf. An NXDOMAIN from a
385389
// member that has not passed a canary check is asked of a second member; if
386390
// that one finds the name, its answer is returned and the first member is
387391
// recorded as contradicted for the caller's Disagree.
388-
func (p *Pool) Resolve(ctx context.Context, domain string, timeout time.Duration, logf Logf, attempts int, types []string) PoolAnswer {
392+
func (p *Pool) Resolve(ctx context.Context, l Lookup, domain string) PoolAnswer {
389393
var last *PoolResolver
390394
outcome := OutcomeOther
391-
for attempt := 0; attempt < max(attempts, 1); attempt++ {
395+
for attempt := 0; attempt < max(l.Attempts, 1); attempt++ {
392396
if ctx.Err() != nil {
393397
return PoolAnswer{Outcome: OutcomeCanceled}
394398
}
@@ -397,18 +401,18 @@ func (p *Pool) Resolve(ctx context.Context, domain string, timeout time.Duration
397401
return PoolAnswer{Outcome: OutcomeOther, NoResolver: true}
398402
}
399403
last = m
400-
p.checkCanary(ctx, m, timeout, types)
401-
if p.reserve(ctx, m, len(types)) != nil {
404+
p.checkCanary(ctx, m, l)
405+
if p.reserve(ctx, m, len(l.Types)) != nil {
402406
return PoolAnswer{Outcome: OutcomeCanceled}
403407
}
404408
var recs []Record
405-
recs, outcome = ResolveDomainWithRetry(ctx, m.resolver, domain, timeout, logf, 1, types)
409+
recs, outcome = m.lookup(l).Resolve(ctx, domain)
406410
p.report(m, outcome)
407411
switch outcome {
408412
case OutcomeFound:
409413
return PoolAnswer{Records: recs, Outcome: outcome, Addr: m.Addr, member: m}
410414
case OutcomeNXDomain:
411-
return p.secondOpinion(ctx, m, domain, timeout, logf, types)
415+
return p.secondOpinion(ctx, m, l, domain)
412416
case OutcomeCanceled:
413417
return PoolAnswer{Outcome: outcome, Addr: m.Addr, member: m}
414418
}
@@ -417,7 +421,7 @@ func (p *Pool) Resolve(ctx context.Context, domain string, timeout time.Duration
417421
}
418422

419423
// secondOpinion confirms an untrusted member's NXDOMAIN with another member.
420-
func (p *Pool) secondOpinion(ctx context.Context, m *PoolResolver, domain string, timeout time.Duration, logf Logf, types []string) PoolAnswer {
424+
func (p *Pool) secondOpinion(ctx context.Context, m *PoolResolver, l Lookup, domain string) PoolAnswer {
421425
nx := PoolAnswer{Outcome: OutcomeNXDomain, Addr: m.Addr, member: m}
422426
m.mu.Lock()
423427
trusted := m.trusted
@@ -426,17 +430,23 @@ func (p *Pool) secondOpinion(ctx context.Context, m *PoolResolver, domain string
426430
return nx
427431
}
428432
other := p.pickHealthy(m)
429-
if other == nil || p.reserve(ctx, other, len(types)) != nil {
433+
if other == nil || p.reserve(ctx, other, len(l.Types)) != nil {
430434
return nx
431435
}
432-
recs, o := ResolveDomainWithRetry(ctx, other.resolver, domain, timeout, logf, 1, types)
436+
recs, o := other.lookup(l).Resolve(ctx, domain)
433437
p.report(other, o)
434438
if o == OutcomeFound {
435439
return PoolAnswer{Records: recs, Outcome: o, Addr: other.Addr, member: other, contradicted: m}
436440
}
437441
return nx
438442
}
439443

444+
// lookup is l as one try on m's resolver.
445+
func (m *PoolResolver) lookup(l Lookup) Lookup {
446+
l.Resolver, l.Attempts = m.resolver, 1
447+
return l
448+
}
449+
440450
// Stats returns a snapshot of every member's accounting, in pool order.
441451
func (p *Pool) Stats() []ResolverStats {
442452
out := make([]ResolverStats, 0, len(p.members))

0 commit comments

Comments
 (0)