Contributing to as-overlay

January 3, 2026 · View on GitHub

Great, you want to contribute! Here's how:

Keep PRs small - Each entry is reviewed manually, so submit only a handful of entries at a time.

Contribution workflow

Find an AS - Browse missing.json to find an AS that needs data
Research - Look up the AS using primary sources (see Where to find data)
Add entry - Create an entry in overlay.json with the data found
Validate - Run the validation script locally to check formatting
Submit PR - Open a pull request with sources documented (see PR description requirements)

You tried to use an ipverse IP block list for a specific AS and found it empty or incorrect. This happens when the AS metadata is missing from public WHOIS data. By adding an overlay entry, you help make that AS's metadata available to everyone.

The auto-generated file missing.json lists all AS that need overlay entries:

{
  "as": [
    { "asn": 11636, "missing": "all" },
    { "asn": 58531, "missing": "country" }
  ]
}

The missing field indicates what's needed:

"all" - No metadata at all. These need complete metadata (handle, description, and country code).
"country" - Has metadata but missing country code. These only need a country code added.

Note: This file is auto-generated. Do not include it in your PR - only overlay.json should be modified.

Field definitions

Fields must appear in this exact order:

Field	Required	Description
`asn`	Yes	The AS number
`handle`	No*	AS handle/name (uppercase, no spaces, keep it short)
`description`	No*	Network description (concise and factual)
`countryCode`	Yes	ISO 3166-1 alpha-2 country code
`reason`	Yes	`missing` (adding data that doesn't exist), `inferred-fix` (fixing inferred metadata - never for authoritative data), or `internal` (maintainer-only, do not use)

*Handle and description must be specified together - one cannot appear without the other.

Research

Where to find data

IRR databases (RADb)
PeeringDB
BGP AS path analysis (inferring location from upstream/peer relationships)

Important: Avoid citing ASN lookup aggregators (ipinfo.io, Team Cymru, etc.) - use primary sources instead.

AI-assisted research

A SKILL.md file is available for use with AI coding assistants. It provides structured guidance for researching missing AS entries, including which sources to check and how to trace prefix ownership.

Important: You must manually review the research results before submission. You are responsible for:

Verifying all sources cited actually contain the claimed data
Confirming the country code and organization name are correct
Ensuring the data is current and not stale
Checking that cited URLs are valid and accessible

Do not submit unverified AI-generated content. PRs with incorrect or fabricated data will be rejected.

Local validation

# Install dependencies
pip install pycountry

# Validate changes
python scripts/validate.py

All pull requests are automatically validated via GitHub Actions.

PR description requirements

Include sources showing where the data was obtained.

Examples

Full metadata

For an AS with "missing": "all" (no metadata at all):

{
  "asn": 64512,
  "handle": "ACME-NET",
  "description": "Acme Corporation",
  "countryCode": "US",
  "reason": "missing"
}

Fix inferred metadata

For an AS with incorrect inferred metadata:

{
  "asn": 64512,
  "handle": "ACME-NET",
  "description": "Acme Corporation",
  "countryCode": "US",
  "reason": "inferred-fix"
}

Country code only

For an AS with "missing": "country" (has metadata, missing country):

{
  "asn": 64512,
  "countryCode": "US",
  "reason": "missing"
}

Example PR description

Adding AS64512 - missing from WHOIS but actively announcing prefixes

Active announcements: https://github.com/example/ipverse-data/blob/main/as.csv shows AS64512
IRR: RADb shows aut-num AS64512 with descr "Acme Corporation"
PeeringDB: https://www.peeringdb.com/asn/64512 confirms US location

What NOT to do

Change handle/description when origin is authoritative - only overlay missing or inferred data
Add entries based on personal naming preferences
Add AS that are not announcing prefixes
Use inferred-fix for authoritative metadata
Use internal

You waive all copyright and related rights to your contribution
Your contribution becomes part of the public domain
Anyone can use, modify, and distribute your contribution without restriction
No attribution is required (though sources should still be documented in PRs)

This ensures the data remains freely available for everyone to use without legal restrictions.

Why CC0?

CC0 is used because factual AS metadata should be freely accessible to the entire internet community. This license:

Removes all legal barriers to using the data
Allows unrestricted commercial and non-commercial use
Ensures the data can be integrated into any system or database
Is standard practice for public infrastructure data projects

Contributor affirmations

By submitting a contribution, you affirm that:

You have the right to contribute the data - The information you're submitting is either publicly available, factual data that you have the right to share
The data is factual and publicly verifiable - AS metadata should be based on public sources like IRR databases, PeeringDB, BGP looking glasses, and RIR records
You're not submitting proprietary or confidential information - Only contribute data that is publicly available or can be publicly verified