Containerised microservice to provide an HTTP JSON API for IPNetDB databases.
This service is designed to be built as a container and deployed in a containerised application stack or with container orchestration such as with docker-compose or kubernetes. It provides an HTTP-based JSON API to query IPNetDB network information databases from https://ipnetdb.com/
NOTE: IPNetDB databases are free for open source use but they are not free for commercial or closed source use. Please make sure you read the licence on https://ipnetdb.com/ to make sure you are compliant before using this container! You may need to pay for a licence or add attribution to your project.
The IPNetDB databases are not bundled with this container. They are downloaded directly from IPNetDB.
You can either build this container yourself:
$ make containerOr you can pull a tagged container image directly from here:
ghcr.io/meeb/ipnetdb-service:v0.1.1
IPNetDB-Service has no configurable environment variables. The container only opens an HTTP server on TCP port 80. You can run it via docker with:
$ docker run --rm --name ipnetdb-service -p 80:80 ghcr.io/meeb/ipnetdb-service:v0.1.1Or for example in a compose stack:
ipnetdb-service:
image: ghcr.io/meeb/ipnetdb-service:v0.1.1
container_name: ipnetdb-service
restart: unless-stopped
ports:
- 80:80IPNetDB-Service is suitable to be used with multiple replicas and in Kubernetes or other container orchestration clusters.
On start the IPNetDB-Service container will download the latest IPNetDB databases from https://ipnetdb.com/ . This may take a minute or two and the service will not be available until this start-up task is complete.
At a random time every Monday the IPNetDB databases will be automatically updated and reloaded. The container should be self-maintaining and require no operations time to maintain other than monitoring the healthcheck.
The embedded API server is built on nginx with OpenResty and is capable of very high throughput.
The HTTP API has 4 endpoints, listed below. If you query any other URL,
including the / root resource, you will see a help page with a
404/Not Found status code.
Performs a healthcheck on the container and returns a {"health": "ok"}
along with a 200/OK status code if the container is healthy. Any other
response means the container is not healthy.
$ curl -s http://ipnetdb-service/healthcheck | jq
{
"health": "ok"
}Returns the currently loaded IPNetDB database index in JSON format. This
response is identical to the JSON file at https://ipnetdb.com/latest.json
and can be used to determine if the databases currently loaded in the
container are up to date. Returns either a 200/OK response if an index
is available or a 404/Not Found if no index is loaded.
$ curl -s http://ipnetdb-service/index | jq
{
"prefix": {
"url": "https://cdn.ipnetdb.net/ipnetdb_prefix_latest.mmdb",
"file": "ipnetdb_prefix_latest.mmdb",
"date": "2021-12-26",
"sha256": "4f740044b16336c07127a124470da4f1fec57586b8bbece952ca85d3d9e78bea",
"bytes": 127849480
},
"asn": {
"url": "https://cdn.ipnetdb.net/ipnetdb_asn_latest.mmdb",
"file": "ipnetdb_asn_latest.mmdb",
"date": "2021-12-26",
"sha256": "7659820d2eba672f6b9bc553eccf638690c5ca6cfb1ca12ac254349d893f171f",
"bytes": 27796664
}
}Fetches information on an any IPv4 or IPv6 address. Returns either a 200/OK
status and information on the IP address or a 404/Not Fouind status if the IP
has no information in the database. Response is always in JSON. The following
fields are always returned:
query: The IP address that was queried
type: The type of query issued, set to the string "ip" for IP queries
status: Either "found" or "not found"
result: A JSON object of the results of the query if found
See https://ipnetdb.com/ for more details on the result fields returned.
$ curl -s http://ipnetdb-service/ip/1.1.1.1 | jq
{
"result": {
"allocation": "1.1.1.0/24",
"allocation_cc": "AU",
"allocation_registry": "apnic",
"allocation_status": "assigned",
"as": 13335,
"as_cc": "US",
"as_entity": "Cloudflare, Inc.",
"as_name": "CLOUDFLARENET",
"as_private": false,
"as_registry": "arin",
"prefix_asset": {},
"prefix_assignment": "assigned portable",
"prefix_bogon": false,
"prefix_entity": "APNIC and Cloudflare DNS Resolver project",
"prefix_name": "APNIC-LABS",
"prefix_origins": [
13335
],
"prefix_registry": "apnic",
"prefix": "1.1.1.0/24"
},
"query": "1.1.1.1",
"status": "found",
"type": "ip"
}An example query for an IPv6 address:
$ curl -s http://localhost/ip/2001:4860:4860::8888 | jq
{
"result": {
"allocation": "2001:4860::/32",
"allocation_cc": "US",
"allocation_registry": "arin",
"allocation_status": "allocated",
"as": 15169,
"as_cc": "US",
"as_entity": "Google LLC",
"as_name": "GOOGLE",
"as_private": false,
"as_registry": "arin",
"prefix_asset": {},
"prefix_assignment": "",
"prefix_bogon": false,
"prefix_entity": "",
"prefix_name": "",
"prefix_origins": [
15169
],
"prefix_registry": "",
"prefix": "2001:4860::/32"
},
"query": "2001:4860:4860::8888",
"status": "found",
"type": "ip"
}An example query to an IP address not in the databases:
$ curl -s http://ipnetdb-service/ip/0.0.0.0 | jq
{
"result": {},
"query": "0.0.0.0",
"status": "not found",
"type": "ip"
}Fetches information on an any autonomous systems number. Returns either a
200/OK status and information on the ASN or a 404/Not Fouind status if the
ASN has no information in the database. Response is always in JSON. The
following fields are always returned:
query: The ASN that was queried
type: The type of query issued, set to the string "as" for ASN queries
status: Either "found" or "not found"
result: A JSON object of the results of the query if found
See https://ipnetdb.com/ for more details on the result fields returned.
$ curl -s http://ipnetdb-service/as/12345 | jq
{
"result": {
"name": "AS12345",
"cc": "IT",
"entity": "General Software s.r.l.",
"in_use": true,
"ipv4_prefixes": [
"212.47.32.0/19"
],
"as": 12345,
"ipv6_prefixes": {},
"peers": [
28716
],
"private": false,
"registry": "ripe",
"status": "allocated"
},
"query": "12345",
"status": "found",
"type": "as"
}An example query to an ASN not in the databases:
$ curl -s http://localhost/as/0 | jq
{
"result": {},
"query": "0",
"status": "not found",
"type": "as"
}All properly formatted and sensible pull requests, issues and comments are welcome.