IP ASN History

August 10, 2023 · View on GitHub

IP ASN History is an open source project to figure out the ASN announcing an IP and the closest prefix announcing it at a specific date.

The default currently loads announces from CAIDA also RIPE dumps in MRT format.

IP ASN History is a complete open source project to run your own server locally.

If you don't want to run your own server, there is a public API operated by CIRCL.

Python client

See the PyIPASNHistory repository

API

The REST API has two entry points:

/meta (GET): returns meta informations about the information currently stored in the database

{
  "sources": [
    "caida"
  ],
  "expected_interval": {
    "first": "2018-05-12",
    "last": "2018-11-08"
  },
  "cached_dates": {
    "caida": {
      "v4": {
	"cached": [
	  "2018-04-26T12:00:00",
	  "2018-04-27T12:00:00",
		  //...
	  "2018-11-05T12:00:00",
	  "2018-11-06T12:00:00"
	],
	"missing": [
	  "2018-11-07"
	],
	"percent": 99.44444444444444
      },
      "v6": {
	"cached": [
	  "2018-04-26T12:00:00",
	  "2018-04-27T12:00:00",
		  //...
	  "2018-11-06T12:00:00",
	  "2018-11-07T12:00:00"
	],
	"missing": [],
	"percent": 100.0
      }
    }
  }
}

Note: the percentage will help 3rd party component to decide if they should query the service now or wait. It is expected to miss a few days and probably not important.

/ (POST/GET): Runs a query. (if you want to resolve more than 1000 IPs, use mass_cache and mass_query)

Parameters:

ip: (required) IP to lookup
source: (optional) Source to query (defaults to 'caida') - currently, only caida is supported
address_family: (optional) v4 or v6 (defaults to v4)
date: (optional) Exact date to lookup (defaults to most recent available)
first: (optional) First date in the interval
last: (optional) Last date in the interval
precision_delta: (optional) Max delta allowed between the date queried and the one we have in the database. Expects a dictionary to pass to timedelta. Example: {days=1, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0}

Response:

{
  "meta": {
    "source": "caida",
    "ip_version": "v4",
    "ip": "146.185.222.49"
  },
  "error": "Optional, only if there was an error",
  "info": "Optional, informational message if needed",
  "response": {
    "2018-11-01T12:00:00": {
      "asn": "44050",
      "prefix": "146.185.222.0/24"
    },
    "2018-11-02T16:00:00": {
      "asn": "44050",
      "prefix": "146.185.222.0/24"
    },
    "2018-11-03T12:00:00": {
      "asn": "44050",
      "prefix": "146.185.222.0/24"
    },
    "2018-11-04T12:00:00": {
      "asn": "44050",
      "prefix": "146.185.222.0/24"
    },
    "2018-11-05T12:00:00": {
      "asn": "44050",
      "prefix": "146.185.222.0/24"
    },
    "2018-11-06T12:00:00": {
      "asn": "44050",
      "prefix": "146.185.222.0/24"
    }
  }
}

Curl examples:

It works fine for single requests, if you have batches of IPs to lookup, use the python API and mass_cache mass_query.

curl https://bgpranking-ng.circl.lu/ipasn_history/?ip=8.8.8.8
curl "https://bgpranking-ng.circl.lu/ipasn_history/?ip=2001:db8:a0b:12f0::1&address_family=v6"

Note: The date returned may differ from the one queried: the system will figure out the closest available date to the one queried.

/mass_cache (POST): Caches a lot of queries at once, don't wait for the lookup.

Parameters: A list of dictionaries with the same parameters as the default query.

Response: A list of queries that IPASN History wasn't able to process.

Note: Use this path when you have lots of query to run and (>1000) in order to resolve all of them at once.
/mass_query (POST): Caches a lot of queries at once. Either wait for the lookup to be done, or pick the data from cache.

Parameters: A list of dictionaries with the same parameters as the default query.

Response: A list of responses as the default query.

Note: Use this path when you have lots of query to run and (>1000) in order to resolve all of them at once.

/asn_meta (POST): Returns meta informations about an ASN

Parameters: A list of dictionaries with the same parameters as the default query.

Response

{
  "meta": {
  "address_family": "v4",
  "asn": "137342",
  "source": "caida"
  },
  "response": {
    "2019-01-01T12:00:00": {
      "137342": {
        "ipcount": "512",
        "prefixes": [
          "180.214.250.0/24",
          "103.113.3.0/24"
        ]
      }
    }
  }
}

Installation

IMPORTANT: Use poetry

NOTE: Yes, it requires python3.8+. No, it will never support anything older.

Install redis

git clone https://github.com/antirez/redis.git
cd redis
git checkout 7.0
make
make test
cd ..

Note: If it fails, have a look at the documentation.

Install kvrocks

git clone https://github.com/KvrocksLabs/kvrocks.git
cd kvrocks
git checkout 2.5
./x.py build
cd ..

Note: If it fails, have a look at the documentation.

Install & run IP ASN History

git clone https://github.com/D4-project/IPASN-History.git
cd IPASN-History
poetry install
echo IPASNHISTORY_HOME="'`pwd`'" > .env
poetry shell
start

Shutdown IP ASN History

stop

(Optional) Build & install bgpdumpy, required to process dumps from RIPE

sudo apt install ca-certificates gcc make autoconf libbz2-dev zlib1g-dev libffi-dev
poetry install -E ripe