Skip to content

Commit e5eeb2e

Browse files
TMHSDigitalclaude
andcommitted
Count only real REFUSED answers as refused, not socket errors (#377)
Classify counted any DNSError whose text held "refused" as the REFUSED rate-limit signal, so "connection refused" from a closed resolver port or a down resolver showed up as refused. Go's resolver reports RCODE REFUSED as "server misbehaving" and copies transport error text, so the only real REFUSED wording is this package's own: fixErr's for the RCODE and the DoH 429/503 error. Both now share one phrase, "refused the query", and Classify matches that instead of any "refused". Fixes #377 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 70b1c06 commit e5eeb2e

5 files changed

Lines changed: 40 additions & 9 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7171
- Less memory on large wordlists and busy scans: `-sources`, `-ct`, `-axfr` and `-permute` check their names against the wordlist without building a set as large as it (about 200 MB per feature and target on a 5M-line list), a `-simulate-zone` lab scan no longer keeps a count per queried name (about 170 MB on a 1M-line list), and a `CNAME` lookup reads a UDP answer into a buffer sized for the 1232-byte EDNS payload it advertises instead of 64 KB. Results are unchanged (#321).
7272

7373
### Fixed
74+
- A lookup is counted as `refused` only when the resolver answered with RCODE REFUSED or a DNS-over-HTTPS server shed load with HTTP 429 or 503. A socket error such as "connection refused", from a closed `-dns-server` port or a resolver that is down, used to be counted as `refused` too, so the verdict, the preflight error and the reliability guard pointed at rate limiting when the address was wrong; it is now counted as `other`, the same on every platform (#377).
7475
- The GitHub Action carries a time-boxed scan across runs. With `max-duration` and `baseline-artifact`, a run the budget stops saves its resume state in the baseline artifact, next to the previous results it still diffs against, and the next run continues that scan with `-resume` instead of starting from the first name again, so a large wordlist is worked through over several scheduled runs and the baseline is replaced once a run completes. The state is saved even when `fail-on` fails the step. A change to the action's inputs discards the state with a notice, as does subenum refusing to resume (for example a changed wordlist file), and a new scan starts. A new `resumed` output says whether the run continued a stopped scan. A later use of the action in the same job with the same `baseline-artifact` reads the copy the earlier use saved instead of the artifact list, which can lag an upload by seconds and made the later use start over or miss the baseline (#352).
7576
- The config file and `SUBENUM_W`/`SUBENUM_O` can set several `-w` wordlists or `-o` files, as the command line can. The config file takes a JSON array for `w` and `o`, one file per entry (`"o": ["names.txt", "jsonl:results.jsonl"]`), and for `sources`, as it already did for `exclude` and `type`; a string for `w` or `o` there or in the environment is a comma-separated list, as it is for the other list settings, where it used to become one path with commas in it. `-print-config` shows `w` and `o` as a JSON array, so one file whose name has a comma is told apart from two (#353).
7677
- A name whose lookup of one requested type timed out, was refused or failed while another type answered is no longer a plain found result with the records that came back. The whole lookup is tried again up to `-attempts`, and when the failed type never answers the result is marked partial: a `partial` field in JSON and JSONL, `PARTIAL` in text with `-show-records`, a `partial answers` line in the breakdown, and `Stats.Partial` in the library. Partial answers lower the run's verdict as failed lookups do (degraded at 1%), and `-diff-records` does not report a partial name as changed, since its missing records may only be a lookup that failed (#357).

‎docs/ARCHITECTURE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -279,7 +279,7 @@ Visually, this can be seen as:
279279

280280
### 4.3. DNS Resolution Errors
281281

282-
* **Lookup Failure**: When a DNS lookup fails, the error is classified (`NXDomain`, `Timeout`, `Refused`, `Other`, `Canceled`) and counted. NXDOMAIN is a definitive negative and is not treated as an infrastructure failure; this bucket also covers NODATA (the name exists but has no records of the requested types, such as `-type CNAME` on a name with only A records). Lookups cut short by cancellation (`Canceled`) are not counted at all, so an interrupt cannot inflate the failure rate. Timeouts, refusals, and other errors feed the reliability guard. The CLI always prints the per-outcome breakdown after `EventDone`.
282+
* **Lookup Failure**: When a DNS lookup fails, the error is classified (`NXDomain`, `Timeout`, `Refused`, `Other`, `Canceled`) and counted. `Refused` means the resolver answered with RCODE REFUSED (or a DoH server answered HTTP 429/503); a socket error such as "connection refused" from a closed port is `Other`. NXDOMAIN is a definitive negative and is not treated as an infrastructure failure; this bucket also covers NODATA (the name exists but has no records of the requested types, such as `-type CNAME` on a name with only A records). Lookups cut short by cancellation (`Canceled`) are not counted at all, so an interrupt cannot inflate the failure rate. Timeouts, refusals, and other errors feed the reliability guard. The CLI always prints the per-outcome breakdown after `EventDone`.
283283
* **Timeout Handling**: The user-specified timeout (`-timeout` flag) limits each per-type lookup, starting only after its rate-limit slots are granted, so queueing behind `-rate` never turns into a timeout. A lookup that exceeds it is classified as a timeout and retried if attempts remain.
284284
* **Resolver failures before scanning**: a failed preflight or an inconclusive wildcard check (without `-force`) emits `EventError`, followed by exactly one `EventDone` with `Stopped` set; the target counts as failed.
285285

‎internal/dns/resolver.go‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,13 +98,23 @@ func Classify(err error) Outcome {
9898
case de.IsTimeout:
9999
return OutcomeTimeout
100100
}
101-
if strings.Contains(strings.ToLower(de.Err), "refused") {
101+
// Go's resolver reports RCODE REFUSED as "server misbehaving" and
102+
// copies a transport error's text, so the only REFUSED wording that
103+
// reaches here is this package's own: fixErr's for the RCODE and the
104+
// DoH 429/503 one. A bare "refused" would also match a socket's
105+
// "connection refused" from a closed port or a resolver that is down,
106+
// which is not the rate-limit signal (#377).
107+
if strings.Contains(de.Err, refusedPhrase) {
102108
return OutcomeRefused
103109
}
104110
}
105111
return OutcomeOther
106112
}
107113

114+
// refusedPhrase is the wording every error this package raises for a refused
115+
// query carries, and the only text Classify counts as REFUSED.
116+
const refusedPhrase = "refused the query"
117+
108118
// ParseTypes parses a comma-separated record-type list (for example
109119
// "A,AAAA,CNAME") into a normalized, de-duplicated, uppercase slice.
110120
func ParseTypes(s string) ([]string, error) {
@@ -222,7 +232,7 @@ func (b *wireBudget) fixErr(err error) error {
222232
cp.Server = s
223233
}
224234
if b.refused.Load() && Classify(err) == OutcomeOther {
225-
cp.Err = "server refused the query (REFUSED)"
235+
cp.Err = "server " + refusedPhrase + " (REFUSED)"
226236
}
227237
return &cp
228238
}

‎internal/dns/resolver_test.go‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -171,15 +171,35 @@ func TestClassify(t *testing.T) {
171171
want: OutcomeTimeout,
172172
},
173173
{
174-
name: "refused",
175-
err: &net.DNSError{Err: "server refused", Name: "blocked.example.com"},
174+
// fixErr's wording for a response carrying RCODE REFUSED.
175+
name: "refused rcode",
176+
err: &net.DNSError{Err: "server refused the query (REFUSED)", Name: "blocked.example.com"},
176177
want: OutcomeRefused,
177178
},
178179
{
179-
name: "refused mixed case",
180-
err: &net.DNSError{Err: "REFUSED"},
180+
// The DoH 429/503 wording, as Go's resolver copies it (#114).
181+
name: "doh shedding load",
182+
err: &net.DNSError{Err: "DNS-over-HTTPS server refused the query (HTTP 429 Too Many Requests)"},
181183
want: OutcomeRefused,
182184
},
185+
{
186+
// A closed UDP port (ICMP port unreachable on Linux) is a socket
187+
// error, not the REFUSED rate-limit signal (#377).
188+
name: "udp connection refused",
189+
err: &net.DNSError{Err: "read udp 127.0.0.1:50000->127.0.0.1:5999: recvfrom: connection refused", Server: "127.0.0.1:5999"},
190+
want: OutcomeOther,
191+
},
192+
{
193+
// TCP fallback or DoT to a closed port (#377).
194+
name: "tcp connection refused",
195+
err: &net.DNSError{Err: "dial tcp 127.0.0.1:5999: connect: connection refused"},
196+
want: OutcomeOther,
197+
},
198+
{
199+
name: "windows connection refused",
200+
err: &net.DNSError{Err: "dial tcp 127.0.0.1:5999: connectex: No connection could be made because the target machine actively refused it."},
201+
want: OutcomeOther,
202+
},
183203
{
184204
name: "other dns error",
185205
err: &net.DNSError{Err: "server misbehaving", Name: "x.example.com"},

‎internal/dns/transport.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -440,8 +440,8 @@ func (c *dohConn) exchange(msg []byte) ([]byte, error) {
440440
case http.StatusOK:
441441
case http.StatusTooManyRequests, http.StatusServiceUnavailable:
442442
// The HTTP form of REFUSED: the server is shedding load. Worded so
443-
// Classify counts it as refused, the rate-limit signal (#114).
444-
return nil, fmt.Errorf("DNS-over-HTTPS server refused the query (HTTP %s)", resp.Status)
443+
// Classify counts it as refused, the rate-limit signal (#114, #377).
444+
return nil, fmt.Errorf("DNS-over-HTTPS server %s (HTTP %s)", refusedPhrase, resp.Status)
445445
default:
446446
return nil, fmt.Errorf("DNS-over-HTTPS server returned %s", resp.Status)
447447
}

0 commit comments

Comments
 (0)