🔍 PeerGlass — Internet Resource Intelligence

Protocol note: PeerGlass uses RDAP (Registration Data Access Protocol — RFC 7480–7484). RDAP (RFC 7480–7484) is the IANA-mandated JSON successor to legacy plain-text WHOIS. Where you see "historical-whois" in source code or API responses, that is RIPE Stat's own name for their endpoint — it is not our protocol choice.

Query all 5 global Regional Internet Registries simultaneously using RDAP, validate routes via RPKI, inspect BGP routing visibility, trace full historical allocation timelines, discover IXP peering data via PeeringDB, and monitor network health — all from natural language in Claude or via REST API.

---

What Are the 5 RIRs?

Think of the internet's IP address space like a global land registry. IANA (the root) delegates large blocks to 5 regional bodies:

RIR	Region	Countries
🌍 AFRINIC	Africa	54
🌏 APNIC	Asia-Pacific	56 economies
🌎 ARIN	North America	USA, Canada, Caribbean
🌎 LACNIC	Latin America & Caribbean	33
🌍 RIPE NCC	Europe, Middle East, Central Asia	75+

---

Quick Start

Install

git clone https://github.com/duksh/peerglass
cd peerglass
pip install -e .

Configure MCP Clients (Claude and others)

PeerGlass runs as a standard MCP stdio server (mcp.run() in server.py), so any MCP-compatible AI client can use it — not just Claude Desktop.

For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "peerglass": {
      "command": "peerglass",
      "args": []
    }
  }
}

If peerglass is not in your PATH, use:

{
  "mcpServers": {
    "peerglass": {
      "command": "python",
      "args": ["/full/path/to/peerglass/server.py"]
    }
  }
}

Restart Claude Desktop. All 17 tools become immediately available.

Start the REST API

uvicorn api:app --host 0.0.0.0 --port 8000 --reload

Interactive docs at: http://localhost:8000/docs

---

Example Queries (Natural Language in Claude)

Phase 1 — Registry lookups:

"Who owns the IP address 185.220.101.1?"
"What is the abuse contact for 8.8.8.8?"
"Who is AS13335 registered to?"
"Are all 5 RIR RDAP servers online right now?"

Phase 2 — Routing security:

"Is the route 1.1.1.0/24 via AS13335 RPKI valid?"
"Is 8.8.8.0/24 currently visible in the global BGP table?"
"What prefixes is AS15169 (Google) announcing right now?"
"Find all internet resources registered to Cloudflare globally."

Phase 3 — Historical intelligence:

"Show me the full registration history of 8.8.8.0/24."
"Has the prefix 192.0.2.0/24 ever been transferred between organizations?"
"Give me the global IPv4 exhaustion stats for all 5 RIRs."
"Show me the prefix hierarchy for 1.1.1.0/24 — parent blocks and sub-assignments."

Phase 4 — Peering, IXPs, health & monitoring:

"Who does AS13335 (Cloudflare) peer with at internet exchanges?"
"List all IXPs where Google has a presence."
"Is the network for 1.1.1.0/24 currently healthy — any ROA issues or BGP anomalies?"
"Monitor AS13335 for changes since last baseline."

---

All 17 MCP Tools

Phase 1 — Registry Queries

Tool	Description	Cache TTL
rir_query_ip	Query all 5 RIRs for an IP address (parallel)	1 hour
rir_query_asn	Query all 5 RIRs for an ASN (parallel)	1 hour
rir_get_abuse_contact	Find abuse contact for any IP globally	1 hour
rir_server_status	Health check all 5 RDAP servers	live
rir_cache_stats	View query cache state and TTLs	live

Phase 2 — Routing Intelligence

Tool	Description	Cache TTL
rir_check_rpki	Validate RPKI/ROA status for prefix + ASN	15 min
rir_check_bgp_status	Check BGP visibility for a prefix or ASN	5 min
rir_get_announced_prefixes	List all BGP-announced prefixes for an ASN	5 min
rir_audit_org	Audit all IP/ASN resources for an organization	6 hours

Phase 3 — Historical Intelligence

Tool	Description	Cache TTL
rir_prefix_history	Full ownership timeline for any prefix or ASN	12 hours
rir_detect_transfers	Detect cross-org / cross-RIR resource transfers	12 hours
rir_ipv4_stats	Global IPv4/IPv6/ASN dashboard + optional delegated IPv4 block listing (include_blocks, filters, pagination)	24 hours
rir_prefix_overview	Prefix hierarchy: parent, children, BGP status	1 hour

Phase 4 — Peering, IXPs, Health & Monitoring

Tool	Description	Cache TTL
rir_get_peering_info	PeeringDB peering data + BGP neighbours for an ASN	1 hour
rir_lookup_ixps	Search Internet Exchange Points globally	6 hours
rir_network_health	RPKI + BGP + RDAP health composite check	5 min
rir_change_monitor	Detect changes since last baseline (delta report)	live

---

REST API — 15 Endpoints

PeerGlass exposes every tool as a REST endpoint, allowing integration with dashboards, scripts, and CI/CD pipelines — no Claude required.

Method	Endpoint	Description
GET	/v1/ip/{ip}	RDAP lookup for an IP address
GET	/v1/asn/{asn}	RDAP lookup for an ASN
GET	/v1/abuse/{ip}	Abuse contact for any IP
GET	/v1/rpki?prefix=...&asn=...	RPKI validation
GET	/v1/bgp/{resource}	BGP visibility status
GET	/v1/announced/{asn}	Announced prefixes for an ASN
GET	/v1/org?name=...	Audit all resources for an org name
GET	/v1/history/{resource}	Prefix/ASN ownership history
GET	/v1/transfers/{resource}	Transfer detection
GET	/v1/stats/ipv4	Global IPv4/IPv6/ASN stats
GET	/v1/overview/{prefix}	Prefix hierarchy overview
GET	/v1/peering/{asn}	Peering info from PeeringDB
GET	/v1/ixp	IXP search and listing
GET	/v1/health/{resource}	Composite network health check
GET	/v1/monitor/{resource}	Change monitoring (delta)

Quick example:

# Look up who owns 1.1.1.1
curl http://localhost:8000/v1/ip/1.1.1.1

# Validate RPKI for Cloudflare's prefix
curl "http://localhost:8000/v1/rpki?prefix=1.1.1.0/24&asn=AS13335"

# Get BGP peers for Google
curl http://localhost:8000/v1/peering/AS15169

# List AFRINIC delegated IPv4 blocks (allocated + Ghana), paginated
curl "http://localhost:8000/v1/stats/ipv4?rir=AFRINIC&include_blocks=true&status=allocated&country=GH&limit=5&offset=0&format=json"

Interactive docs (Swagger UI): http://localhost:8000/docs

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                    PEERGLASS                            │
│                                                         │
│   Claude (LLM)              REST Clients                │
│       │ MCP / stdio              │ HTTP                 │
│       ▼                          ▼                      │
│   server.py (17 tools)      api.py (15 endpoints)       │
│       │                          │                      │
│       └──────────┬───────────────┘                      │
│                  ▼                                       │
│           rir_client.py  ── All async HTTP calls         │
│                  │                                       │
│       ┌──────────┼──────────────────┐                   │
│       ▼          ▼                  ▼                   │
│  normalizer.py  formatters.py    cache.py               │
│  (unify RDAP)   (markdown/JSON)  (TTL tiers)            │
│       │                                                  │
│       ▼                                                  │
│    models.py  (Pydantic v2 data models)                  │
└─────────────────────────────────────────────────────────┘

External APIs called at runtime:
  ├── RDAP:    rdap.afrinic.net / rdap.apnic.net / rdap.arin.net
  │            rdap.lacnic.net  / rdap.db.ripe.net
  ├── RPKI:    rpki.cloudflare.com
  ├── BGP:     stat.ripe.net (bgp-state, announced-prefixes,
  │            routing-status, asn-neighbours, historical-whois)
  ├── IXP:     peeringdb.com/api/net, /api/ix, /api/netixlan
  ├── Stats:   NRO Extended Delegation Stats (all 5 RIRs)
  └── Routing: data.iana.org/rdap/ (IANA bootstrap)

How Parallel Queries Work

asyncio.gather() fires all 5 RIR queries at exactly the same time:

  AFRINIC ──── responds in 1.1s ──── 404 Not Found
  APNIC   ──── responds in 0.9s ──── ✅ 200 OK  ← authoritative
  ARIN    ──── responds in 1.2s ──── 404 Not Found
  LACNIC  ──── responds in 1.4s ──── 404 Not Found
  RIPE    ──── responds in 0.8s ──── 404 Not Found

Total wall-clock time: ~1–2s (parallel) vs ~6–8s (sequential)

---

Testing

PeerGlass has two separate test suites serving different purposes. You should run both — they catch different categories of problems.

┌─────────────────────────────────────────────────────────────┐
│                   TESTING PYRAMID                           │
│                                                             │
│      🔺 INTEGRATION TESTS  (test_integration.py)            │
│      /\   Real internet. Real APIs. Real data.              │
│     /  \  Proves the product actually works end-to-end.     │
│    /────\  Run this on your machine or a GCP VM.            │
│                                                             │
│   🔺 UNIT / STATIC TESTS  (test_peerglass.py)              │
│   /\   In-memory. No network. Instant.                      │
│  /  \  Proves code structure, branding, and wiring.         │
│ /────\  Runs anywhere including CI/CD.                      │
└─────────────────────────────────────────────────────────────┘

---

Test 1 — Static / Unit Tests (test_peerglass.py)

What it checks:

#	Test	What It Verifies
1	Compile check	All 7 .py files parse without syntax errors
2	Branding audit	No stale legacy product/server identity strings
3	RDAP endpoints	All 5 RIR RDAP URLs are present and correct
4	Protocol header	Accept: application/rdap+json is set
5	User-Agent	Updated to peerglass/1.0.0
6	MCP server name	"peerglass"
7	Tool count	Exactly 17 @mcp.tool() decorators in server.py
8	REST endpoints	All 15 routes present in api.py
9	FastAPI runtime	TestClient hits 3 endpoints in-memory, validates responses
10	README	PeerGlass branding, 17 tools, RDAP note all present

How to run:

cd peerglass
python test_peerglass.py

Expected output:

============================================================
PEERGLASS — COMPLETE TEST SUITE
============================================================
1. COMPILE CHECK
   ✅ server.py  ✅ rir_client.py  ✅ formatters.py
   ✅ models.py  ✅ cache.py  ✅ normalizer.py  ✅ api.py

2. BRANDING AUDIT — no stale WHOIS identity strings
   ✅ server.py  ✅ rir_client.py  ✅ README.md  ...

...

✅ ALL TESTS PASSED — 0 errors
  Python files: 7  |  MCP tools: 17  |  REST endpoints: 15
  Protocol: RDAP throughout (RFC 7480-7484)
  Branding: PeerGlass throughout
============================================================

When to run: Before every commit. Runs in under 3 seconds. No internet required.

---

Test 2 — Integration Tests (test_integration.py)

What it checks:

Real HTTP calls to external internet registries/data providers using well-known, stable test fixtures (Cloudflare AS13335, Google AS15169, 1.1.1.0/24). Every test asserts on actual response data — not just that the server responded.

#	Test	API Called	Fixture	Assertion
1	RDAP reachability	All 5 RIRs	1.1.1.1	HTTP 200 or 404 (both mean server is up)
2	RDAP IP lookup	APNIC	1.1.1.1	objectClassName=ip network, startAddress=1.1.1.0
3	RDAP ASN lookup	ARIN	AS13335	objectClassName=autnum, name contains CLOUDFLARE
4	RPKI validation	RIPE Stat	1.1.1.0/24 AS13335	status=ok, validation status is valid
5	BGP status	RIPE Stat	1.1.1.0/24	Prefix visible to RIS peers, origin ASN present
6	Announced prefixes	RIPE Stat	AS13335	>= 5 prefixes, mix of IPv4 + IPv6
7	Historical data	RIPE Stat	AS15169	status=ok, historical object versions returned
8	PeeringDB network	PeeringDB	AS13335	Network record found, peering policy present
9	IANA Bootstrap	IANA	AS13335	Mapped to correct RDAP service URL
10	AFRINIC RDAP	AFRINIC	102.176.0.0	objectClassName=ip network, African country code
11	ASN neighbours	RIPE Stat	AS13335	Upstream / peer ASN list returned
12	PeeringDB IXPs	PeeringDB	global	IXP list with name and country
13	IANA consistency	IANA/ICANN	IPv4 + IPv6 + ASN bootstrap files	All 5 RIR service URLs present

How to run:

# On your local machine or a GCP VM (requires internet access)
cd peerglass
python test_integration.py

Expected output (passing):

============================================================
  PEERGLASS — LIVE INTEGRATION TEST SUITE
  Real HTTP calls. No mocks. No fakes.
============================================================
  Time: 2026-02-20 14:00:00 UTC
  APIs: RIPE · ARIN · APNIC · LACNIC · AFRINIC · RIPE Stat · PeeringDB · IANA

────────────────────────────────────────────
  TEST 1 — RDAP Server Reachability (all 5 RIRs)
────────────────────────────────────────────
   ✅ PASS  RIPE RDAP reachable      HTTP 404
   ✅ PASS  ARIN RDAP reachable      HTTP 404
   ✅ PASS  APNIC RDAP reachable     HTTP 200
   ✅ PASS  LACNIC RDAP reachable    HTTP 404
   ✅ PASS  AFRINIC RDAP reachable   HTTP 404

...

============================================================
  SUMMARY
  Checks run   : 48
  ✅ Passed    : 47
  ❌ Failed    : 0
  ⚠️  Skipped  : 1
  Duration     : ~20-40s

  🎉 ALL TESTS PASSED — PeerGlass live APIs confirmed working!
============================================================

When to run:

• Before a release
• After any change to rir_client.py (the HTTP layer)
• After any change to the external API URLs or parameters
• On a schedule (e.g. daily cron on a GCP VM) to detect API changes upstream

Why this cannot run in CI/CD without configuration: The integration tests require outbound internet access to external APIs (RIPE, ARIN, APNIC, LACNIC, AFRINIC, RIPE Stat, PeeringDB, IANA). Standard CI runners (GitHub Actions free tier) have internet access, so these tests can run there. Restricted sandboxes (Anthropic Claude environment, some corporate proxies) will block the outbound calls and every test will fail with 403 Forbidden — this is expected behaviour of the sandbox, not a bug in PeerGlass.

---

Understanding Test Results

Why does RDAP return 404 and still pass?

APNIC owns 1.1.1.0/24 (Cloudflare's block). If you ask RIPE for 1.1.1.1:

  You:  GET https://rdap.db.ripe.net/ip/1.1.1.1
  RIPE: HTTP 404

This 404 is RIPE saying "I know about this IP but it's not mine."
The server is alive and working correctly. 404 = server reachable.
200 = server reachable AND it's the authoritative RIR for that IP.
Both are valid success states for the reachability test.

Why does Test 7 sometimes SKIP?

RIPE Stat's historical-whois endpoint has variable coverage. For some ASNs it returns rich history; for others the objects array is empty. An empty array is a valid API response — the skip is logged to distinguish "no data" from "API broken".

---

Running Both Suites Together

cd peerglass

# Step 1: Always run static tests first (fast, catches code errors)
python test_peerglass.py
echo "Exit code: $?"

# Step 2: Only run integration tests if static tests pass
if [ $? -eq 0 ]; then
    python test_integration.py
fi

---

Verification — Source-Pinned Retrieval vs Model Recall

If you want to verify that PeerGlass is deterministic and source-pinned (real API retrieval) rather than model recall, run this quick check.

1. Ask ChatGPT to fetch all 5 RIR RDAP endpoints for 1.1.1.1 and return raw JSON only.
2. Repeat the exact same prompt multiple times.
3. Compare ChatGPT output against direct endpoint results below.

Use this prompt in ChatGPT:

For IP 1.1.1.1, query these exact RDAP endpoints and return ONLY JSON:

- AFRINIC: https://rdap.afrinic.net/rdap/ip/1.1.1.1
- APNIC: https://rdap.apnic.net/ip/1.1.1.1
- ARIN: https://rdap.arin.net/registry/ip/1.1.1.1
- LACNIC: https://rdap.lacnic.net/rdap/ip/1.1.1.1
- RIPE: https://rdap.db.ripe.net/ip/1.1.1.1

Output schema per RIR:
{
  "rir": "...",
  "url": "...",
  "http_status": ...,
  "objectClassName": "... or null",
  "handle": "... or null",
  "error": "... or null"
}

Do not summarize. Do not infer.

Ground-truth script (direct endpoint calls):

python - <<'PY'
import asyncio
import json
import httpx

ENDPOINTS = {
    "AFRINIC": "https://rdap.afrinic.net/rdap/ip/1.1.1.1",
    "APNIC": "https://rdap.apnic.net/ip/1.1.1.1",
    "ARIN": "https://rdap.arin.net/registry/ip/1.1.1.1",
    "LACNIC": "https://rdap.lacnic.net/rdap/ip/1.1.1.1",
    "RIPE": "https://rdap.db.ripe.net/ip/1.1.1.1",
}

async def query_one(client, rir, url):
    try:
        r = await client.get(url, timeout=20)
        content_type = r.headers.get("content-type", "")
        data = r.json() if "json" in content_type else {}
        return {
            "rir": rir,
            "url": url,
            "http_status": r.status_code,
            "objectClassName": data.get("objectClassName"),
            "handle": data.get("handle"),
            "error": None,
        }
    except Exception as exc:
        return {
            "rir": rir,
            "url": url,
            "http_status": None,
            "objectClassName": None,
            "handle": None,
            "error": str(exc),
        }

async def main():
    headers = {
        "Accept": "application/rdap+json",
        "User-Agent": "peerglass/verification",
    }
    async with httpx.AsyncClient(headers=headers, follow_redirects=True) as client:
        results = await asyncio.gather(*[
            query_one(client, rir, url) for rir, url in ENDPOINTS.items()
        ])
    print(json.dumps(results, indent=2))

asyncio.run(main())
PY

If ChatGPT outputs are inconsistent or fail to fetch while direct calls are stable, that difference is exactly why PeerGlass uses deterministic source-pinned retrieval.

---

Adding Your Own Integration Tests

The test_integration.py script is designed to be extended. Each test follows this pattern:

async def test_your_thing():
    section("TEST N — Short description")
    print("  What API, what fixture, what you expect")

    url = "https://example-api.com/endpoint"
    params = {"resource": "your-fixture", "sourceapp": "peerglass-test"}
    headers = {"Accept": "application/json", "User-Agent": "peerglass/1.0.0 (integration-test)"}

    try:
        async with httpx.AsyncClient(timeout=25.0) as client:
            resp = await client.get(url, params=params, headers=headers)

        if resp.status_code != 200:
            fail("API returned 200", f"HTTP {resp.status_code}"); return

        data = resp.json()
        value = data.get("some", {}).get("field", "")

        ok("Field is what I expected", f"value='{value}'") if value == "expected" else fail("Field check", f"Got '{value}'")

    except Exception:
        fail("API call failed", traceback.format_exc()[-120:])

Then add it to the main() coroutine:

async def main():
    ...
    await test_your_thing()   # ← add here
    ...

---

External APIs Used

API	Purpose	Cache TTL
All 5 RIR RDAP endpoints	IP/ASN registration data (RDAP JSON)	1 hr
data.iana.org/rdap/	Bootstrap: which RIR owns which IP/ASN range	permanent
rpki.cloudflare.com	RPKI/ROA validation (Validated ROA Payloads)	15 min
stat.ripe.net/data/bgp-state	BGP routing table visibility	5 min
stat.ripe.net/data/announced-prefixes	Prefixes announced by an ASN	5 min
stat.ripe.net/data/asn-neighbours	BGP peer/upstream/downstream ASNs	1 hr
stat.ripe.net/data/historical-whois	RDAP object change history (RIPE's naming)	12 hr
stat.ripe.net/data/allocation-history	Allocation lifecycle events	12 hr
stat.ripe.net/data/prefix-overview	Prefix hierarchy metadata	1 hr
stat.ripe.net/data/routing-status	Routing status and visibility	5 min
peeringdb.com/api/net	Network peering policies	1 hr
peeringdb.com/api/ix	Internet Exchange Point directory	6 hr
peeringdb.com/api/netixlan	Network-to-IXP membership records	1 hr
NRO Extended Delegation Stats	Authoritative IPv4/IPv6/ASN allocation counts (all 5 RIRs)	24 hr

---

Phase 3 Data Sources Explained

RIPE Stat historical-whois

Records every change ever made to an RDAP object: when the org field changed, when the status changed, when a new maintainer was added. Used by rir_prefix_history and rir_detect_transfers. The name "historical-whois" is RIPE Stat's own endpoint naming — PeerGlass uses RDAP protocol throughout.

Coverage: Best for RIPE NCC resources. Partial for other RIRs.

RIPE Stat allocation-history

Logs the full allocation lifecycle: when a block was first allocated from the RIR pool, when it was sub-allocated to an ISP, when it was returned.

NRO Extended Delegation Stats

Published daily by each RIR as a pipe-delimited text file. Contains every single IP and ASN record ever created, with current status. Authoritative source for rir_ipv4_stats.

RIPE Stat prefix-overview / less-specifics / more-specifics

Three APIs queried in parallel to build the prefix hierarchy tree for rir_prefix_overview.

---

Use Case Workflows

BGP Hijack Investigation

1. rir_query_ip(suspicious_ip)         → Who registered this IP?
2. rir_check_bgp_status(prefix)        → Which ASN is announcing it right now?
3. rir_check_rpki(prefix, asn)         → Is the announcement RPKI-valid?
4. rir_prefix_overview(prefix)         → Any unexpected more-specifics?
5. rir_detect_transfers(prefix)        → Did this block recently change hands?

M&A Due Diligence

1. rir_audit_org(company_name)         → What IP blocks does this company own?
2. rir_prefix_history(each_prefix)     → When were they acquired?
3. rir_detect_transfers(each_prefix)   → Were any transferred recently?
4. rir_get_announced_prefixes(asn)     → What are they actively routing?

Peering & IXP Analysis

1. rir_get_peering_info(asn)           → Where does this network peer?
2. rir_lookup_ixps(city or ixp_name)  → Find IXPs in a region
3. rir_network_health(asn)             → Is the network healthy?
4. rir_change_monitor(asn)             → Any changes since last check?

Policy Research / ISOC Report

1. rir_ipv4_stats()                    → Full global IPv4/IPv6/ASN dashboard
2. rir_ipv4_stats(rir_filter="AFRINIC")→ Africa-specific detail
3. Compare ipv6_total_prefixes across  → IPv6 adoption rates by region

---

IPv4 Exhaustion Context

RIR	IPv4 Free Pool Exhausted
APNIC	15 April 2011
RIPE NCC	14 September 2012
ARIN	24 September 2015
LACNIC	June 2020
AFRINIC	2020–2021

All RIRs now operate under transfer policies. IPv4 addresses trade on the secondary market. rir_ipv4_stats tracks remaining pools in real time.

---

License

MIT