217 lines
5.8 KiB
Markdown
217 lines
5.8 KiB
Markdown
# Prefix Geography Plan
|
|
|
|
## Goal
|
|
|
|
Make Earth BGP incidents `prefix-centric` instead of `collector-centric`.
|
|
|
|
The map should primarily answer:
|
|
|
|
- where a prefix-related event is likely centered
|
|
- which regions the prefix is likely associated with
|
|
- which collectors observed the event as evidence
|
|
|
|
It should not continue to imply that the event is located at the collector itself unless no better geography is available.
|
|
|
|
## Why Current Geography Is Not Enough
|
|
|
|
Current incident geography can still collapse back to collector-derived regions because:
|
|
|
|
1. `prefix_scope` is currently built mostly from observed collector regions and historical observation regions.
|
|
2. `origin_asn_profile` currently comes from `peeringdb_network`, which is useful for ASN footprint hints but not sufficient as a primary prefix location source.
|
|
3. `collector centroid` is still a common fallback and therefore dominates sparse incidents.
|
|
|
|
This makes Earth feel like a collector map with event decorations instead of a prefix impact map.
|
|
|
|
## Data Source Layers
|
|
|
|
Prefix geography should be built from four layers, ordered by confidence.
|
|
|
|
### Layer 1. Prefix-to-country / prefix-to-region
|
|
|
|
This is the primary source layer and the current missing piece.
|
|
|
|
Recommended sources:
|
|
|
|
1. `IPtoASN / IPtoCountry`
|
|
- URL: <https://iptoasn.com/>
|
|
- Good fit for this project because it provides downloadable IPv4/IPv6 range-to-ASN and range-to-country mappings.
|
|
- Best use:
|
|
- map a prefix to country code
|
|
- enrich prefixes with coarse regional placement
|
|
|
|
2. `OpenGeoFeed`
|
|
- URL: <https://opengeofeed.org/faq/>
|
|
- Best use:
|
|
- override coarse country mappings when the prefix holder publishes a geofeed
|
|
- provide a more realistic deployment/service region than whois-style registration country
|
|
|
|
### Layer 2. Registry allocation fallback
|
|
|
|
Use these only as fallback signals, not as a ground-truth physical location.
|
|
|
|
Candidate inputs:
|
|
|
|
- RIR delegated stats
|
|
- `inetnum` / `inet6num` whois
|
|
|
|
Best use:
|
|
|
|
- detect registration country / allocation region
|
|
- provide fallback when no direct prefix geolocation dataset is available
|
|
|
|
### Layer 3. ASN footprint hints
|
|
|
|
Existing in this project:
|
|
|
|
- `peeringdb_network`
|
|
- `peeringdb_facility`
|
|
- `peeringdb_ixp`
|
|
|
|
Best use:
|
|
|
|
- derive ASN city/country footprint
|
|
- identify likely exchange/facility regions
|
|
- act as secondary evidence when prefix-specific geography is unavailable
|
|
|
|
### Layer 4. Observation evidence
|
|
|
|
Existing in this project:
|
|
|
|
- `RIPE RIS Live`
|
|
- `CAIDA BGPStream Backfill`
|
|
|
|
Best use:
|
|
|
|
- prove who observed the event
|
|
- derive affected observation regions
|
|
- support impact evidence
|
|
|
|
This should remain the final fallback and evidence layer, not the primary event geography.
|
|
|
|
## Recommended Geography Priority
|
|
|
|
The backend should compute incident geography with this order:
|
|
|
|
1. `prefix_geography`
|
|
- prefix-to-country / region / geofeed-backed result
|
|
2. `asn_region`
|
|
- ASN organization / facility / IXP footprint
|
|
3. `collector_centroid`
|
|
- observed collector regions only as final fallback
|
|
|
|
Returned GeoJSON should keep exposing the selected mode through:
|
|
|
|
- `geography_mode = prefix_geography | asn_region | collector_centroid`
|
|
|
|
## Proposed Backend Changes
|
|
|
|
### 1. Add a dedicated prefix geography dataset
|
|
|
|
New datasource candidates:
|
|
|
|
- `ip2asn_prefix_geo`
|
|
- optionally `opengeofeed_prefix_geo`
|
|
|
|
Suggested storage model:
|
|
|
|
- keep downloaded rows in `CollectedData` first for speed of integration
|
|
- later move to a dedicated table if lookup volume grows
|
|
|
|
Minimum normalized fields:
|
|
|
|
- `range_start`
|
|
- `range_end`
|
|
- `prefix`
|
|
- `country`
|
|
- `continent`
|
|
- `asn`
|
|
- `as_name`
|
|
- `source`
|
|
- `confidence`
|
|
|
|
### 2. Add prefix geography enrichment
|
|
|
|
Extend:
|
|
|
|
- `backend/app/services/bgp_enrichment.py`
|
|
|
|
New enrichment payload should include:
|
|
|
|
- `prefix_geography`
|
|
- `country`
|
|
- `continent`
|
|
- `regions`
|
|
- `source`
|
|
- `confidence`
|
|
|
|
This should be separate from the current `prefix_scope`.
|
|
|
|
Suggested distinction:
|
|
|
|
- `prefix_scope`
|
|
- observation-derived scope hint
|
|
- `prefix_geography`
|
|
- prefix-centric geography estimate
|
|
|
|
### 3. Update incident visualization geography selection
|
|
|
|
Extend:
|
|
|
|
- `backend/app/api/v1/visualization.py`
|
|
|
|
Selection order:
|
|
|
|
1. `prefix_geography.regions`
|
|
2. ASN geography hints from PeeringDB-derived profile
|
|
3. observation-derived `affected_regions`
|
|
|
|
### 4. Keep evidence visible in the frontend
|
|
|
|
Earth should distinguish:
|
|
|
|
- event center = prefix geography estimate
|
|
- evidence lines / collectors = observation proof
|
|
|
|
This keeps the event meaningful for non-expert users without losing collector evidence.
|
|
|
|
## Earth UX Result
|
|
|
|
After this change, a user should see:
|
|
|
|
- an incident marker near the estimated affected prefix region
|
|
- collectors as supporting evidence, not as the event center itself
|
|
- cables / landing points / nearby infrastructure as weak correlation around the estimated region
|
|
|
|
This makes BGP incidents readable as “where the event is likely happening or affecting”, instead of “which station saw it”.
|
|
|
|
## Implementation Order
|
|
|
|
### Phase 1
|
|
|
|
1. Add `IPtoASN / IPtoCountry` datasource support
|
|
2. Normalize rows into lookup-friendly format
|
|
3. Enrich BGP events with `prefix_geography`
|
|
4. Switch incident geography priority to prefer `prefix_geography`
|
|
|
|
### Phase 2
|
|
|
|
5. Add `OpenGeoFeed` support
|
|
6. Let geofeed override coarse country-level prefix geography
|
|
7. Add confidence scoring per geography source
|
|
|
|
### Phase 3
|
|
|
|
8. Add RIR / whois fallback
|
|
9. Add better ASN regional footprint from PeeringDB facilities / IXPs
|
|
10. Refine Earth visual semantics for prefix geography vs observation evidence
|
|
|
|
## Recommendation
|
|
|
|
The best next engineering move is:
|
|
|
|
1. integrate `IPtoASN / IPtoCountry`
|
|
2. model `prefix_geography` separately from `prefix_scope`
|
|
3. only then continue refining incident map placement
|
|
|
|
Without this layer, any further Earth tuning will still be constrained by collector-centric data.
|