IP to ASN Web Service - Container Images¶

Debian-based container images for the IP to ASN Web Service. Two variants are published to one registry.

Features¶

• Two variants: Original (minimal) and Fork (extended with bulk lookups, ASN listing, subnet enumeration).
• API responses in JSON, plaintext, or HTML formats.
• Based on pavo-asm/iptoasn-webservice.

Usage¶

Pull the images¶

Why a fork variant? The fork — maintained by @rda0 — is a drop-in compatible superset of the original. It adds bulk IP lookups, direct ASN queries, listings of all ASNs, and subnet enumeration for a given ASN. Use Original for a minimal surface; choose Fork when you need richer discovery workflows or automation against AS/ASN data.

Run the service locally¶

podman run -d -p 53661:53661 registry.gitlab.com/niclas-zone/ctr/iptoasn-webservice:latest
podman run -d -p 53661:53661 registry.gitlab.com/niclas-zone/ctr/iptoasn-webservice:latest-fork

API Documentation¶

Original variant¶

Routes¶

• GET /v1/as/ip/<ip address> — Lookup provided IP address.
• GET /v1/as/ip — Lookup requester's IP address, prioritized as X-Real-IP → X-Forwarded-For → request IP.

JSON Response¶

curl -H 'Accept: application/json' http://localhost:53661/v1/as/ip/8.8.8.8

Fork variant¶

Routes¶

• GET /v1/as/ip/<ip address> — Lookup provided IP address.
• GET /v1/as/ip — Lookup requester's IP address.
• PUT /v1/as/ips — Bulk lookup provided list of IP addresses.
• GET /v1/as/n/<as number> — Lookup provided AS number.
• GET /v1/as/ns — Returns all known AS numbers.
• GET /v1/as/n/<as number>/subnets — Returns all known subnets of a given AS number.

JSON Response¶

curl -H 'Accept: application/json' http://localhost:53661/v1/as/ip/8.8.8.8

Returns JSON:

{
  "announced": true,
  "as_country_code": "US",
  "as_description": "GOOGLE - Google LLC",
  "as_number": 15169,
  "first_ip": "8.8.8.0",
  "ip": "8.8.8.8",
  "last_ip": "8.8.8.255"
}

HTML Response¶

curl http://localhost:53661/v1/as/ip/8.8.8.8

Returns a formatted HTML page with the IP information.

Plaintext Response¶

curl -H 'Accept: text/plain' http://localhost:53661/v1/as/ip/8.8.8.8

Returns:

15169 | 8.8.8.0-8.8.8.255 | US | GOOGLE

Bulk IP — JSON¶

echo '["8.8.8.8","8.8.4.4"]' \
  | curl -H "Accept: application/json" -X PUT --json @- http://localhost:53661/v1/as/ips

Returns JSON array with results for each IP.

Bulk IP — Plaintext¶

echo -e '8.8.8.8\n8.8.4.4' \
  | curl -H "Accept: text/plain" -X PUT --data-binary @- http://localhost:53661/v1/as/ips

Or with explicit begin/end markers:

echo -e 'begin\n8.8.8.8\n8.8.4.4\nend' \
  | curl -H "Accept: text/plain" -X PUT --data-binary @- http://localhost:53661/v1/as/ips

Unannounced IPs¶

{
  "announced": false,
  "ip": "127.0.0.1"
}

AS Number Lookup¶

ASNs can be provided as 15169 or AS15169.

curl -H 'Accept: application/json' http://localhost:53661/v1/as/n/15169

Plaintext:

curl -H 'Accept: text/plain' http://localhost:53661/v1/as/n/15169

Response: 15169 | US | GOOGLE

AS Numbers Listing¶

curl -sH 'Accept: text/plain' http://localhost:53661/v1/as/ns | rg -S google

AS Subnets Lookup¶

curl -H 'Accept: application/json' http://localhost:53661/v1/as/n/15169/subnets

Returns all IP subnets of a given AS in CIDR format.

Note: These subnets are not necessarily identical to the currently announced BGP prefixes; multiple announced prefixes may be represented by a single subnet here. To query announced prefixes, see RIPE's announced-prefixes API.

Attribution¶

Parts of the Fork variant documentation are adapted from @rda0's project: https://github.com/rda0/iptoasn-webservice

Author¶

Niclas Heinz

Contributing¶

Contributions are welcome! Please open an issue or submit a merge request if you have suggestions or improvements.

License¶

This project is licensed under the MIT License. See LICENSE for details.