Address03

Status: Final

Purpose

Verify that reverse PTR hostnames for nameserver IPs match the corresponding nameserver hostname.
Flag mismatch, missing reverse data, and no-response cases separately.

Preconditions And Inputs

Preconditions:
- A zone.Zone object is available.
- A recursor is available on the zone object.
Required inputs:
- Nameserver addresses from ApexNameservers .
- PTR lookup responses for each checked nameserver IP.
Profile/config knobs that affect behavior:
- resolver.defaults.parallel: controls PTR query task parallelism.

Algorithm And Decision Flow

Emit TEST_CASE_START.
Collect nameserver entries with ApexNameservers .
Build an ordered unique list by IP string:
- Keep the first (nsname, ip) seen for each unique IP.
For each unique IP, execute a PTR-check task (parallelized):
- Compute reverse lookup owner with dns.ReverseAddr.
- Send recursive PTR query.
- If response message exists and RCODE == NOERROR with at least one PTR answer:
  - Collect PTR target names.
  - Compare targets against expected nameserver name (nsname) case-insensitively.
  - If none match, emit NAMESERVER_IP_PTR_MISMATCH (nsname, ns_ip, names).
- Else if response message exists but PTR conditions above are not met, emit NAMESERVER_IP_WITHOUT_REVERSE (nsname, ns_ip).
- Else emit NO_RESPONSE_PTR_QUERY (domain).
After all tasks complete, if at least one IP was checked and no tag besides TEST_CASE_START was emitted, emit NAMESERVER_IP_PTR_MATCH.
Emit TEST_CASE_END.
When executed through AddressAll, this testcase runs only if Address02 produced NAMESERVERS_IP_WITH_REVERSE.

Per-IP PTR-vs-Name Match (steps 2-6)

Show diagram

collect nameserver IPs from ApexNameservers
 +- dedupe by IP string; first-seen (nsname, ip) wins
 |
 v
For each unique IP (parallel; fan-out = resolver.defaults.parallel):

   ptrQuery = dnsutil.ReverseAddr(ip)
    |
    v
   rec.Recurse(ptrQuery, PTR, IN)
    +- resp.Msg absent                       -> NO_RESPONSE_PTR_QUERY
    +- resp.Msg present
       +- RCODE == NOERROR and PTR records in answer
       |    +- collect PTR target names
       |    +- compare each to nsname (case-insensitive, normalized)
       |    +- any match?
       |        +- no  -> NAMESERVER_IP_PTR_MISMATCH (with sorted unique PTR names)
       |        +- yes -> (success; silent)
       +- otherwise (RCODE != NOERROR or no PTR records) -> NAMESERVER_IP_WITHOUT_REVERSE

After all tasks:
  at least one IP checked AND no failure tag emitted -> NAMESERVER_IP_PTR_MATCH
emit TEST_CASE_END

Module-level gating (in AddressAll):
  Address03 runs only when Address02 emitted NAMESERVERS_IP_WITH_REVERSE.

Emitted Tags (Possible Set)

Tag	Emitted when
`CNAME_CHAIN_TOO_LONG`	A discovered NS hostname’s CNAME chain exceeds `CNAMEMaxChainLength` while resolving its address.
`CNAME_TARGET_UNRESOLVED`	A discovered NS hostname’s CNAME chain forms a loop, breaks, or fails to resolve to an address.
`CNAME_TOO_MANY_RECORDS`	A single answer while resolving a discovered NS hostname carries more than `CNAMEMaxRecords` distinct CNAME RRs.
`NAMESERVER_IP_PTR_MATCH`	All checked IPs returned PTR answers that include their expected nameserver name.
`NAMESERVER_IP_PTR_MISMATCH`	PTR answers exist for an IP, but none matches the expected nameserver name.
`NAMESERVER_IP_WITHOUT_REVERSE`	PTR response is present but not successful (`RCODE != NOERROR`) or has no PTR record.
`NO_RESPONSE_PTR_QUERY`	PTR recursive query returned no response message.
`TEST_CASE_END`	Testcase completion marker is emitted.
`TEST_CASE_START`	Testcase start marker is emitted.

Tag Arguments

Tag	Argument key	Type	Meaning
`CNAME_CHAIN_TOO_LONG`	`query_name`	`string`	The NS hostname whose CNAME chain exceeded the depth bound.
`CNAME_TARGET_UNRESOLVED`	`query_name`	`string`	The NS hostname whose CNAME target could not be resolved.
`CNAME_TARGET_UNRESOLVED`	`cname_target`	`string`	The last attempted CNAME target.
`CNAME_TOO_MANY_RECORDS`	`query_name`	`string`	The NS hostname whose answer carried too many CNAME RRs.
`NAMESERVER_IP_PTR_MATCH`	`-`	`-`	No arguments.
`NAMESERVER_IP_PTR_MISMATCH`	`nsname`	`string`	Expected nameserver name for the checked IP (first-seen for that IP).
`NAMESERVER_IP_PTR_MISMATCH`	`ns_ip`	`string`	Checked nameserver IP address.
`NAMESERVER_IP_PTR_MISMATCH`	`names`	`string`	Slash-delimited PTR target names returned in answer.
`NAMESERVER_IP_WITHOUT_REVERSE`	`nsname`	`string`	Nameserver name associated with the checked IP.
`NAMESERVER_IP_WITHOUT_REVERSE`	`ns_ip`	`string`	Checked nameserver IP address.
`NO_RESPONSE_PTR_QUERY`	`domain`	`string`	PTR owner name queried.
`TEST_CASE_END`	`testcase`	`string`	Testcase display name (`Address03`).
`TEST_CASE_START`	`testcase`	`string`	Testcase display name (`Address03`).

Severity Levels Per Tag

Tag	Level	Notes
`CNAME_CHAIN_TOO_LONG`	`ERROR`	Default from `share/profile.json` (`test_levels.ADDRESS`).
`CNAME_TARGET_UNRESOLVED`	`ERROR`	Default from `share/profile.json` (`test_levels.ADDRESS`).
`CNAME_TOO_MANY_RECORDS`	`ERROR`	Default from `share/profile.json` (`test_levels.ADDRESS`).
`NAMESERVER_IP_PTR_MATCH`	`INFO`	Default from `share/profile.json` (`test_levels.ADDRESS`).
`NAMESERVER_IP_PTR_MISMATCH`	`NOTICE`	Default from `share/profile.json` (`test_levels.ADDRESS`).
`NAMESERVER_IP_WITHOUT_REVERSE`	`WARNING`	Default from `share/profile.json` (`test_levels.ADDRESS`).
`NO_RESPONSE_PTR_QUERY`	`WARNING`	Default from `share/profile.json` (`test_levels.ADDRESS`).
`TEST_CASE_END`	`DEBUG`	Default from `share/profile.json` (`test_levels.ADDRESS`).
`TEST_CASE_START`	`DEBUG`	Default from `share/profile.json` (`test_levels.ADDRESS`).

Differences From Upstream

Differences (Upstream vs Gonemaster):
- Upstream: describes consuming ADDRESS02 outcome data as input. Gonemaster: performs fresh PTR lookups inside Address03.
- Upstream: states ADDRESS03 depends on ADDRESS02 success. Gonemaster: enforces gating in AddressAll by requiring NAMESERVERS_IP_WITH_REVERSE from Address02.
Potential upstream report:
- no

Implementation Notes

The following behaviors are implementation choices, not mandated by protocol:

Module orchestration gating: Address03 runs only when Address02 emitted NAMESERVERS_IP_WITH_REVERSE. No DNS standard mandates this sequencing; it is a gonemaster-specific orchestration decision to skip PTR-match checks when no reverse data was found in the preceding testcase.
First-seen-wins deduplication: When multiple nameserver entries share the same IP, only the first-seen (nsname, ip) pair is retained for PTR checking. The protocol does not define how to handle nameserver IP collisions; first-seen is an implementation choice.
PTR name list delimiter: Multiple PTR target names in the names argument of NAMESERVER_IP_PTR_MISMATCH are joined with / (slash). This delimiter is an internal formatting choice with no protocol counterpart.

Edge Cases And Limitations

If ApexNameservers yields no IP addresses, only TEST_CASE_START and TEST_CASE_END are emitted.
Duplicate IPs are checked once; if multiple nameservers share an IP, only the first-seen nameserver name is evaluated for PTR-name match.
PTR target matching is case-insensitive and exact on normalized DNS name string.