You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 661588e
Browse filesBrowse the repository at this point in the historyBrowse files
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
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
25
25
26
26
### Fixed
27
27
- 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).
***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.
136
136
137
137
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.
141
141
***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.
144
144
***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.
145
145
* 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.
148
148
149
149
### 2.4. Concurrency Management (`internal/scan`)
150
150
@@ -208,7 +208,7 @@ The flow of data through the `subenum` application can be summarized as follows:
208
208
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.
209
209
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.
210
210
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.
212
212
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.
213
213
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.
214
214
10.**Progress Tracking**: Workers update atomic counters; the ticker goroutine emits `EventProgress` once per second.
0 commit comments