asndb 1.0.2

A simple Python CLI + library for looking up ASNs by IP or AS number. Uses BBOT.IO API.

ASNDB

A simple Python CLI + library for instant lookup of ASN data by IP address, AS number, or organization. Uses BBOT.IO API (asndb.api.bbot.io).

ASNs are automatically cached for instant lookups and minimal network traffic.

Installation

uv tool install asndb

# or quick run with uvx
uvx asndb

# or using pip
uv tool install asndb

Usage (CLI)

Note: anonymous queries are limited to 10/minute. If you need more, you can purchase an API key at the BBOT.IO Developer Portal. Export the key as an environment variable:

export BBOT_IO_API_KEY=<your_api_key>

IP Lookup

asndb ip 1.1.1.1

Output:

{
  "asn": 13335,
  "asn_name": "CLOUDFLARENET",
  "country": "US",
  "ip": "1.1.1.1",
  "org": "Cloudflare, Inc.",
  "org_id": "CLOUD14-ARIN",
  "rir": "ARIN",
  "subnets": [
    "1.0.0.0/24",
    "1.0.1.0/24"
  ]
}

AS Number Lookup

asndb asn 13335

Output:

{
  "asn": 13335,
  "asn_name": "CLOUDFLARENET",
  "country": "US",
  "ip": "1.1.1.1",
  "org": "Cloudflare, Inc.",
  "org_id": "CLOUD14-ARIN",
  "rir": "ARIN",
  "subnets": [
    "1.0.0.0/24",
    "1.0.1.0/24"
  ]
}

Organization Lookup

# Look up an organization
asndb org CLOUD14-ARIN

Output:

{
  "asns": [
    13335,
    14789,
    395747,
    394536
  ]
}

CLI Help

$ uv run asndb --help
                                                                                              
 Usage: asndb [OPTIONS] COMMAND [ARGS]...                                                     
                                                                                              
╭─ Options ──────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                    │
│ --show-completion             Show completion for the current shell, to copy it or         │
│                               customize the installation.                                  │
│ --help                        Show this message and exit.                                  │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────────╮
│ ip    Lookup ASN by IP address                                                             │
│ asn   Lookup ASN by AS number                                                              │
│ org   Get all the ASNs for an organization, by its registered organization ID, e.g.        │
│       GOGL-ARIN                                                                            │
╰────────────────────────────────────────────────────────────────────────────────────────────╯

Usage (Python)

from asndb import ASNDB

# Create a new ASNDB client
asndb = ASNDB()


# Look up an IP address
asn = asndb.lookup_ip_sync("1.1.1.1")
# {
#   "asn": 13335,
#   "asn_name": "CLOUDFLARENET",
#   "country": "US",
#   "ip": "1.1.1.1",
#   "org": "Cloudflare, Inc.",
#   "org_id": "CLOUD14-ARIN",
#   "rir": "ARIN",
#   "subnets": [
#     "1.0.0.0/24",
#     "1.0.1.0/24"
#   ]
# }

# Look up an AS number
asn = asndb.lookup_asn_sync(13335)
# {
#   "asn": 13335,
#   "asn_name": "CLOUDFLARENET",
#   "country": "US",
#   "ip": "1.1.1.1",
#   "org": "Cloudflare, Inc.",
#   "org_id": "CLOUD14-ARIN",
#   "rir": "ARIN",
#   "subnets": [
#     "1.0.0.0/24",
#     "1.0.1.0/24"
#   ]
# }

# Look up an organization
org = asndb.lookup_org_sync("CLOUD14-ARIN")
# {
#   "asns": [
#     13335,
#     14789,
#     395747,
#     394536
#   ]
# }

Environment Variables

You can customize the behavior of the ASNDB client by exporting the following environment variables:

• BBOT_IO_API_KEY: Your BBOT.IO API key.
• ASNDB_BASE_URL: The base URL of the ASNDB API (default: https://asndb.api.bbot.io/v1).
• ASNDB_TIMEOUT: The timeout for the ASNDB API requests (default: 60 seconds).
• ASNDB_CACHE_SIZE: The size of the cache for the ASNDB API requests (default: 10000).