Skip to content

Add a Cymru Annotator - #73

Merged
zakird merged 21 commits into
mainfrom
phillip/3-cymru-support
May 6, 2026
Merged

zakird merged 21 commits into
mainfrom
phillip/3-cymru-support

Conversation

@phillip-stephens

@phillip-stephens phillip-stephens commented May 4, 2026 •

Copy link
Copy Markdown
Contributor

Cymru offers IP Prefix and ASN information as a free API service. They recommend their DNS endpoints for efficient querying for multiple IPs.

While I used zdns as the dns resolve library for the UDP socket reuse, its caching functionality excludes records like TXT since they might pollute the iterative cache. The Cymru module will commonly need to query the same IP for common peers/origin ASes (On 10k random IPs, Hurricane Electric's ASN was queried over 3k times), so I added a simple, thread-safe LRU cache.

Example of typical usage:

printf "4.195.166.168" | ./zannotate --cymru   
```json
{
  "ip": "4.195.166.168",
  "cymru": {
    "origin_asns": [
      8075
    ],
    "peer_asns": [
      6939,
      6461
    ],
    "asn_details": {
      "8075": {
        "asn": 8075,
        "country_code": "US",
        "registry": "arin",
        "asn_allocation_date": "1997-03-31",
        "asn_description": "MICROSOFT-CORP-MSN-AS-BLOCK - Microsoft Corporation, US"
      },
      "6939": {
        "asn": 6939,
        "country_code": "US",
        "registry": "arin",
        "asn_allocation_date": "1996-06-28",
        "asn_description": "HURRICANE - Hurricane Electric LLC, US"
      },
      "6461": {
        "asn": 6461,
        "country_code": "US",
        "registry": "arin",
        "asn_allocation_date": "1996-04-22",
        "asn_description": "ZAYO-6461 - Zayo Bandwidth, US"
      }
    },
    "prefix_details": {
      "4.192.0.0/12": {
        "prefix": "4.192.0.0/12",
        "origin_asns": [
          8075
        ],
        "peer_asns": [
          6461,
          6939
        ],
        "country_code": "US",
        "registry": "arin",
        "allocation_date": "2020-07-07"
      }
    }
  }
}

Performance

10k Random IPs annotated

  • On Macbook w/ 20 ms ping to 1.1.1.1 - 1 min 10 sec
  • On Ubuntu server - 40 sec

Related Issues

Closes #3

@phillip-stephens
phillip-stephens marked this pull request as ready for review May 4, 2026 21:48
@phillip-stephens
phillip-stephens marked this pull request as draft May 5, 2026 00:34
@phillip-stephens
phillip-stephens marked this pull request as ready for review May 5, 2026 04:33

@zakird zakird left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JSON record IDs should generally be static for easier downstream processing. Would change into list.

We should also probably allow configuration of which Cymru DNS servers to check against instead of checking all of them. In some ases, people may not want ASN details or care about the peers.

Does origin ever provide multiple answers? That seems a bit odd offhand, but i suppose could happen

@phillip-stephens

Copy link
Copy Markdown
Contributor Author

Sounds good, I'll fix the JSON record IDs and add the ability to specify what Cymru endpoints to query.

Yeah, it surprised me too. Was doing final testing and realized some IPs had multiple origin ASNs depending on the prefix advertised and had to redo part of the parser.
Example

$ dig +short -t TXT 0.149.167.220.origin.asn.cymru.com

"140061 | 220.167.148.0/22 | CN | apnic | 2002-10-30"
"4134 | 220.167.128.0/17 | CN | apnic | 2002-10-30"
"140061 | 220.167.128.0/18 | CN | apnic | 2002-10-30"

@phillip-stephens
phillip-stephens requested a review from zakird May 6, 2026 02:39
@phillip-stephens

Copy link
Copy Markdown
Contributor Author

Alright, updated!

@zakird
zakird merged commit df29b11 into main May 6, 2026
3 checks passed
@zakird
zakird deleted the phillip/3-cymru-support branch May 6, 2026 04:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Cymru support

2 participants