Prerequisites

Python Environment

It’s easiest to create a new python environment for bdrmapIT. Anything capable of creating and isolating a python environment will work, but all examples assume Anaconda. First, install Anaconda according to the instructions there. Then, create the environment to install the bdrmapIT packages. Here, the environment name bdrmapit is used, but any name works.

# create python environment
conda create -n bdrmapit 'python<=3.9'
# activate the new environment
conda activate bdrmapit

cython currently prevents using python >= 3.9

Required Packages

All required packages can be installed from the requirements file or by installing the bdrmapit package via pip.

Optional Packages

There is one optional package that makes retrieving datasets easier.

1. retrieve_external – package for retrieving publicly available CAIDA datasets, RIR delegations, and BGP route announcements

Python Environment

Make sure to install all dependencies in this environement, whether installing packages with pip or source code.

Installing bdrmapIT

Install Using pip

It is possible to install bdrmapIT and the required repositories using pip and python3: pip install -U bdrmapit.

Compilation From Source

There are several packages involved in running bdrmapIT. Some are required, and some are optional for added convenience. The source code repository resides at https://github.com/alexmarder/bdrmapit.

Clone the bdrmapIT repository, and compile the cython code.

git clone https://github.com/alexmarder/bdrmapit
cd bdrmapit
# install required packages
pip install -r requirements.txt
# compile cython code and build package
python setup.py sdist bdist_wheel build_ext
# install using developer mode, will install the bdrmapit and traceparser scripts
pip install -e .

Scripts

Regardless of the installation method, a script will be installed into the python environment. This script, bdrmapit can be called from the command line when inside the python environment.

Running bdrmapIT

Create Prefix to AS

Run the scripts as described here.

Retrieving Datasets

A lot of datasets go into bdrmapIT’s inferences. All of it can be retrieved using the retrieve_external package, but it is not necessary to use it for some or all of the datasets. The examples here assume that the retrieve_external package is use. Information is provided in the retrieve_external repo.

Providing Arguments to bdrmapIT

There are now several ways to provide arguments to the bdrmapit script. To pass them at the command line, use the -h argument to see the command line options. After selecting one of the subcommands, use the -h argument to the arguments specific to that subcommand. Using a configuration file is still possible, and the options are listed below.

Configuration File

Due to the many input file, it might be easier to provide a JSON configuration file to provide the runtime parameters. The JSON file uses the schema described in schema.json, which uses the JSON Schema format. As a sample, the following could be in a configuration file:

{
    "$schema": "schema.json",
    "ip2as": "ip2as.prefixes",
    "as2org": {
        "as2org": "as2org-file"
    },
    "as-rels": {
        "rels": "rels-file",
        "cone": "cone-file"
    },
    "warts": {
        "files": "warts.files"
    },
    "atlas": {
        "files-list": ["atlas_file.json.bz2"]
    },
    "processes": 3
}

warts.files is a file containing warts filenames (line separated), and atlas_file.json.bz2 is a RIPE Atlas traceroute file. Of course, individual files and a file with filenames could be supplied for warts, atlas, or both. Only use atlas-odd if you know why you’re using it.

//: # (

:—————-

:———-

:———————————————————————————–

)

//: # (

-o, –output

Required

Output filename for sqlite3 output.

)

//: # (

-c, –config

Required

JSON configuration file in accordance with schema.json

)

//: # (

-n, –nodes-as

Optional

Filename for output in the CAIDA nodes.as style

)

//: # (

-g, –graph

Optional

Graph pickle object created by –graph-only

)

//: # (

–graph-only

Optional

Create graph pickle object, save pickle in file specified by -o/–output, and exit

)

Output

The output is an sqlite3 file with a table named annotation. The table has the following fields,

Field	Type	Description
addr	TEXT	Interface address
asn	INT	Operating AS for the router on which addr resides (router annotation)
org	TEXT	AS2Org mapping for asn
conn_asn	INT	Operating AS for router connected to addr (interface annotation)
conn_org	TEXT	AS2Org mapping for conn_asn

Warning: oversimplification coming, but a brief explanation of what the annotations represent. Every interface is used on a router. asn indicates the network that operates that router. Every interface is also used to connect to at least one other router. conn_asn indicates the network that operates that router or routers. To look for inferred interdomain links, look for addr where asn ≠ conn_asn.

Unusual Output

A small number of routers might receive annotations with invalid AS numbers in the asn column:

ASN	Explanation
0	Address has no covering prefix in the prefix-to-AS mappings, and insufficient information in the graph to derive an ASN
-1	Should be rare; occurs when bdrmapIT failed to assign the router an annotation
<= -100	IXP public peering address with insufficient graph information for an AS annotation

All outputs will likely contain some amount of these invalid ASNs, but it should be relatively rare.