Address01

Status: Final

Purpose

  • Classify authoritative nameserver IP addresses as globally reachable, documentation, local-use, or otherwise not globally reachable.
  • Detect the case where no nameserver address data is available.

Preconditions And Inputs

  • Preconditions:
    • A zone.Zone object is available.
    • A recursor is available on the zone object for Methodsv2 lookups.
  • Required inputs:
    • Delegation nameserver names and addresses from GetDelNSNamesAndIPs.
    • Zone-apex nameserver names and addresses from GetZoneNSNamesAndIPs.
    • Special-purpose address registry data (RFC 6890 section 2.2) via constants.FindSpecialAddress.
  • Profile/config knobs that affect behavior:
    • net.ipv4 and net.ipv6 may affect address discovery in Methodsv2 lookups.

Algorithm And Decision Flow

  1. Emit TEST_CASE_START.
  2. Query nameserver names/addresses using GetDelNSNamesAndIPs and GetZoneNSNamesAndIPs.
  3. Merge the two result sets, keep only entries with an address, and deduplicate by lowercase name/ip.
  4. If no addressed nameserver remains, emit A01_NO_NAME_SERVERS_FOUND, emit TEST_CASE_END, and return.
  5. Group items by IP address, then iterate IP groups in lexicographic IP string order.
  6. For each IP group, classify by the category of the most specific special-purpose block that contains the address, that is the longest matching prefix; a broader block defers to a more specific entry (RFC 6890 sections 2.2.2 and 2.2.3):
    • Documentation category -> add all name/ip pairs in group to documentation set.
    • Local-use categories (Private-Use, Loopback, Link Local, Link-Local, Unique-Local, Shared Address Space) -> add to local-use set.
    • Any other non-globally-reachable special range -> add to not-globally-reachable set.
    • Otherwise -> add to globally-reachable set.
  7. If globally-reachable set is non-empty, emit A01_GLOBALLY_REACHABLE_ADDR with servers; else emit A01_NO_GLOBALLY_REACHABLE_ADDR.
  8. Emit A01_DOCUMENTATION_ADDR if documentation set is non-empty.
  9. Emit A01_LOCAL_USE_ADDR if local-use set is non-empty.
  10. Emit A01_ADDR_NOT_GLOBALLY_REACHABLE if not-globally-reachable set is non-empty.
  11. Emit TEST_CASE_END.

Address Collection and Classification (steps 2-6)

gather NS items (GetDelNSNamesAndIPs + GetZoneNSNamesAndIPs)
 |
 +- per item: keep only if item.HasAddress
 +- dedupe by lower-case "name/ip" string
 |
 v
addressed NS count
 +- zero    -> emit A01_NO_NAME_SERVERS_FOUND
 |              emit TEST_CASE_END and return
 +- nonzero -> group by Address.String(); iterate IP keys in lex order
                 |
                 v
              FindSpecialAddress(ip)  (longest prefix, on group[0])
                +- no special-purpose block         -> globallyReachable
                +- block.Name contains "Documentation" -> documentationAddr
                +- isLocalUseCategory(block.Name)   -> localUseAddr
                |     ("Private-Use", "Loopback",
                |      "Link Local", "Link-Local",
                |      "Unique-Local", "Shared Address Space")
                +- !IsGloballyReachable(block)      -> notGloballyReachable
                +- otherwise                        -> globallyReachable

Aggregation and Final Emission (steps 7-11)

After classification, emit in fixed order:

1. globallyReachable
     non-empty -> A01_GLOBALLY_REACHABLE_ADDR     (servers)
     empty     -> A01_NO_GLOBALLY_REACHABLE_ADDR  (no args)

2. documentationAddr non-empty   -> A01_DOCUMENTATION_ADDR        (servers)
3. localUseAddr non-empty        -> A01_LOCAL_USE_ADDR            (servers)
4. notGloballyReachable non-empty -> A01_ADDR_NOT_GLOBALLY_REACHABLE (servers)

5. emit TEST_CASE_END

Emitted Tags (Possible Set)

TagEmitted when
A01_ADDR_NOT_GLOBALLY_REACHABLEAt least one nameserver IP is in a special-purpose range that is not globally reachable (RFC 8190 section 2.1) and not classified as documentation/local-use.
A01_DOCUMENTATION_ADDRAt least one nameserver IP is in a documentation-only range (RFC 5737 section 4, RFC 3849 section 3, RFC 9637 section 4).
A01_GLOBALLY_REACHABLE_ADDRAt least one nameserver IP is classified as globally reachable.
A01_LOCAL_USE_ADDRAt least one nameserver IP is in a local-use category, none of which is globally reachable (RFC 8190 section 2.1).
A01_NO_GLOBALLY_REACHABLE_ADDRNo nameserver IP is classified as globally reachable.
A01_NO_NAME_SERVERS_FOUNDNo nameserver with an address was discovered from delegation+zone sources.
CNAME_CHAIN_TOO_LONGA discovered NS hostname’s CNAME chain exceeds CNAMEMaxChainLength while resolving its address.
CNAME_TARGET_UNRESOLVEDA discovered NS hostname’s CNAME chain forms a loop, breaks, or fails to resolve to an address (RFC 1034 section 5.2.2).
CNAME_TOO_MANY_RECORDSA single answer while resolving a discovered NS hostname carries more than CNAMEMaxRecords distinct CNAME RRs.
TEST_CASE_ENDTestcase completion marker is emitted.
TEST_CASE_STARTTestcase start marker is emitted.

Tag Arguments

TagArgument keyTypeMeaning
A01_ADDR_NOT_GLOBALLY_REACHABLEserversarray<object>Structured {ns,address} object pairs in the non-globally-reachable set.
A01_DOCUMENTATION_ADDRserversarray<object>Structured {ns,address} object pairs in documentation ranges.
A01_GLOBALLY_REACHABLE_ADDRserversarray<object>Structured {ns,address} object pairs in globally reachable ranges.
A01_LOCAL_USE_ADDRserversarray<object>Structured {ns,address} object pairs in local-use ranges.
A01_NO_GLOBALLY_REACHABLE_ADDR--No arguments.
A01_NO_NAME_SERVERS_FOUND--No arguments.
CNAME_CHAIN_TOO_LONGquery_namestringThe NS hostname whose CNAME chain exceeded the depth bound.
CNAME_TARGET_UNRESOLVEDquery_namestringThe NS hostname whose CNAME target could not be resolved.
CNAME_TARGET_UNRESOLVEDcname_targetstringThe last attempted CNAME target.
CNAME_TOO_MANY_RECORDSquery_namestringThe NS hostname whose answer carried too many CNAME RRs.
TEST_CASE_ENDtestcasestringTestcase display name (Address01).
TEST_CASE_STARTtestcasestringTestcase display name (Address01).

Severity Levels Per Tag

TagLevelNotes
A01_ADDR_NOT_GLOBALLY_REACHABLEERRORDefault from share/profile.json (test_levels.ADDRESS).
A01_DOCUMENTATION_ADDRERRORDefault from share/profile.json (test_levels.ADDRESS).
A01_GLOBALLY_REACHABLE_ADDRINFODefault from share/profile.json (test_levels.ADDRESS).
A01_LOCAL_USE_ADDRERRORDefault from share/profile.json (test_levels.ADDRESS).
A01_NO_GLOBALLY_REACHABLE_ADDRERRORDefault from share/profile.json (test_levels.ADDRESS).
A01_NO_NAME_SERVERS_FOUNDCRITICALDefault from share/profile.json (test_levels.ADDRESS).
CNAME_CHAIN_TOO_LONGERRORDefault from share/profile.json (test_levels.ADDRESS).
CNAME_TARGET_UNRESOLVEDERRORDefault from share/profile.json (test_levels.ADDRESS).
CNAME_TOO_MANY_RECORDSERRORDefault from share/profile.json (test_levels.ADDRESS).
TEST_CASE_ENDDEBUGDefault from share/profile.json (test_levels.ADDRESS).
TEST_CASE_STARTDEBUGDefault from share/profile.json (test_levels.ADDRESS).

Differences From Upstream

  • Differences (Upstream vs Gonemaster):
    • Upstream: does not define a strict order for category tag emission. Gonemaster: emits A01_GLOBALLY_REACHABLE_ADDR/A01_NO_GLOBALLY_REACHABLE_ADDR before other category tags.
    • Upstream: does not require a specific servers presentation order. Gonemaster: deduplicates and lexicographically sorts servers values before emission.
  • Potential upstream report:
    • no

Edge Cases And Limitations

  • The testcase ignores nameserver entries that lack resolved IP addresses.
  • If all discovered addresses are reserved/non-global, A01_NO_GLOBALLY_REACHABLE_ADDR can be emitted together with one or more category error tags.
  • Multiple nameserver names sharing one IP are preserved as distinct name/ip entries in output lists.
  • An address in a block nested inside a broader one, such as AS112-v6 (2001:4:112::/48) inside IETF Protocol Assignments (2001::/23), is classified by the nested block and its globally reachable flag.