Home

Awesome

ASN Lookup Tool and Traceroute Server

Packaging status

Container support:

Docker Google Cloud

OS support:

Debian Ubuntu Kali Cent OS Red Hat Rocky Linux Fedora Arch Manjaro Alpine Linux openSUSE FreeBSD Nix macOS Windows Raspberry Pi

Table of contents:

Description

ASN / RPKI validity / BGP stats / IPv4v6 / Prefix / ASPath / Organization / IP reputation / IP geolocation / IP fingerprinting / Network recon / lookup tool / Web traceroute server.

This script serves the purpose of having a quick OSINT command line tool at disposal when investigating network data, which can come in handy in incident response scenarios as well (with features such as bulk geolocation and threat scoring).

It can be used as a recon tool by querying Shodan for data about any type of target (CIDR blocks/URLs/single IPs/hostnames). This will quickly give the user a complete breakdown about open ports, known vulnerabilities, known software and hardware running on the target, and more - without ever sending a single packet to the target. JSON output of the results, multiple simultaneous targets and IP list file inputs and are also supported. Click here for more information about Shodan scanning mode.

It can also be used as a web-based traceroute server, by running it in listening mode and launching lookups and traces from a local or remote browser (via a bookmarklet or custom search engine) or terminal (via curl, elinks or similar tools). Click here for more information about server mode functionality.

Furthermore, it can serve as a self-hosted lookup API endpoint and output JSON-formatted data while running in both interactive and server mode. Click here for more information about API mode functionality.

Features:

Screenshots for every lookup option are below.

The script uses the following services for data retrieval:

It also provides hyperlinks (in server mode) to the following external services when appropriate:

Requires Bash v4.2+. Tested on:

Screenshots

Generic usage

AS Path tracing

Network search by organization

Shodan scanning

Country IPv4/IPv6 CIDR mapping

Bulk Geolocation / country stats

Suggested ASNs search

Transit/Upstream lookup

Running the script from a container

To run the script without installing it locally, you have the following options:

Installation

This script requires BASH v4.2 or later. You can check your version by running from your shell:

bash -c 'echo $BASH_VERSION'

After installation, you can use the script by running the asn command.

Method 1: Install prerequisites + manual download

Note: this method is recommended as it will always get you the latest version of the script.

<details><summary><b>STEP 1. Install prerequisite packages</b></summary><p>

Some packages are required for full functionality:

</p></details> <details><summary><b>STEP 2. Script download and installation</b></summary><p>

Afterwards, to install the asn script from your shell to /usr/bin:

curl "https://raw.githubusercontent.com/nitefood/asn/master/asn" > /usr/bin/asn && chmod 0755 /usr/bin/asn

</p></details>

Method 2: Installing a packaged version of the script

Note: packages may not reflect the latest version, check Repology first.

Packaged versions of the tool are available for the following distributions:

<details><summary><b>Distribution list</b></summary><p> </p></details>

(Optional) Installing the asn server as a system service

Note: this step is optional, and these instructions are only for systemd-based Linux systems (most current major distributions).

To control the asn server with utilities like systemctl and service, and to enable it to automatically start at boot, follow these steps:

  1. create a new file called /etc/systemd/system/asn.service with the following content (make sure you edit the ExecStart line to match your installation path and desired startup options):
[Unit]
Description=ASN lookup and traceroute server
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=nobody
ExecStart=/usr/bin/asn -l 0.0.0.0

[Install]
WantedBy=multi-user.target
  1. Enable the CAP_NET_RAW capability for the mtr-packet binary: setcap cap_net_raw+ep $(which mtr-packet) Explanation: this will allow mtr-packet to create raw sockets (and thus perform traces) when launched as an unprivileged user (we're setting up the service to run as user nobody for added security), without the requirement of the setuid-root bit and without having to invoke mtr as root. A thorough explanation for this can be found here.
  2. Now you can refer to standard systemd utilities to perform service operations:
    • To start the service: systemctl start asn
    • To stop the service: systemctl stop asn
    • To check its status and latest logs: systemctl status asn
    • To follow its logging in real time: journalctl -f -u asn
    • To start the service automatically on boot: systemctl enable asn
    • To disable automatic start on boot: systemctl disable asn

API tokens

The script can be configured to make use of your API tokens to enhance its functionalities.

The currently supported API tokens are:

Geolocation API token (ipinfo.io)

<details><summary><b>Geolocation API token details</b></summary><p>

The geolocation provider of choice for single lookups (i.e. when not running bulk geolocation queries with the -g option) is ipinfo.io.

By default, the script uses the free (no API key) tier that supports up to 1,000 geolocation requests per day. In order to boost this limit (for free) to 50,000 requests per month, an API key token is required.

In order to obtain an API token, after signing up, the API token can be found in the token section of your reserved area. Once copied, the token should be written to one of the following files (parsed in that order):

$HOME/.asn/ipinfo_token or /etc/asn/ipinfo_token

The /etc-based file should be used when running asn in server mode. The $HOME-based file takes precedence if both files exist, and is ideal for user mode (that is, running asn interactively from the command line).

In order to do so, you can use the following command:

User mode:

TOKEN="<your_token_here>"; mkdir "$HOME/.asn/" && echo "$TOKEN" > "$HOME/.asn/ipinfo_token" && chmod -R 600 "$HOME/.asn/"

Server mode:

TOKEN="<your_token_here>"; mkdir "/etc/asn/" && echo "$TOKEN" > "/etc/asn/ipinfo_token" && chmod -R 700 "/etc/asn/" && chown -R nobody /etc/asn/

Either way, asn will pick up your token on the next run (no need to restart the service if running in server mode), and use it to query the ipinfo.io API.

</p></details>

IP reputation API token (IPQualityScore)

<details><summary><b>IP reputation API token details</b></summary><p>

The script will perform first-level IPv4/v6 reputation lookups using StopForumSpam, and in case of a match it will perform a second-level, in-depth threat analysis for targets and trace hops using the IPQualityScore API. The StopForumSpam API is free and requires no sign-up, and the service aggregates a huge amount of blacklist feeds.

Still, in order to use the IPQualityScore API for in-depth threat reporting, it's necessary to sign up for their service (it's free) and get an API token (it will be emailed to you on sign-up), which will entitle you to 5000 free lookups per month.

Once obtained, the api token should be written to one of the following files (parsed in that order):

$HOME/.asn/iqs_token or /etc/asn/iqs_token

The /etc-based file should be used when running asn in server mode. The $HOME-based file takes precedence if both files exist, and is ideal for user mode (that is, running asn interactively from the command line).

In order to do so, you can use the following command:

User mode:

TOKEN="<your_token_here>"; mkdir "$HOME/.asn/" && echo "$TOKEN" > "$HOME/.asn/iqs_token" && chmod -R 600 "$HOME/.asn/"

Server mode:

TOKEN="<your_token_here>"; mkdir "/etc/asn/" && echo "$TOKEN" > "/etc/asn/iqs_token" && chmod -R 700 "/etc/asn/" && chown -R nobody /etc/asn/

Either way, asn will pick up your token on the next run (no need to restart the service if running in server mode), and use it to query the IPQualityScore API.

Note: IPQualityScore is not queried by default for every target, but only for targets that get flagged as BAD by StopForumSpam. It's possible to override this behavior (and force IQS lookup for every target) by setting the IQS_ALWAYS_QUERY parameter to true in the preferences file. It is also possible to specify custom query settings through the IQS_CUSTOM_SETTINGS parameter.

</p></details>

BGP hijack and route leak incidents (Cloudflare Radar)

<details><summary><b>Cloudflare token details</b></summary><p>

When this token is available, an additional lookup will be enabled for autonomous system targets, in order to enumerate the BGP incidents (both BGP hijacks and BGP route leaks) involving the target ASN.

The script will use the Cloudfare Radar API to retrieve the amount of incidents involving the target ASN in the past 12 months. Additionally, it will report how many incidents saw the target ASN as a hijacker or as a victim.

The Cloudflare Radar API is free to use, but requires a registration. The steps are:

  1. Sign up for a free Cloudflare account and validate your email
  2. From the Cloudflare dashboard, go to My Profile > API Tokens.
  3. Select Create Token
  4. Choose the "Read Cloudflare Radar data" template
  5. Click Continue to summary (the default values are fine)
  6. Click Create token

Once obtained, the api token should be written to one of the following files (parsed in that order):

$HOME/.asn/cloudflare_token or /etc/asn/cloudflare_token

The /etc-based file should be used when running asn in server mode. The $HOME-based file takes precedence if both files exist, and is ideal for user mode (that is, running asn interactively from the command line).

In order to do so, you can use the following command:

User mode:

TOKEN="<your_token_here>"; mkdir "$HOME/.asn/" && echo "$TOKEN" > "$HOME/.asn/cloudflare_token" && chmod -R 600 "$HOME/.asn/"

Server mode:

TOKEN="<your_token_here>"; mkdir "/etc/asn/" && echo "$TOKEN" > "/etc/asn/cloudflare_token" && chmod -R 700 "/etc/asn/" && chown -R nobody /etc/asn/

Either way, asn will pick up your token on the next run (no need to restart the service if running in server mode), and use it to query the Cloudflare Radar API.

</p></details>

Usage

Syntax

asn [OPTIONS] [TARGET]

asn [-v] -l [SERVER OPTIONS]

where TARGET can be one of the following:

<u>Options</u>:

<u>Server Options</u>:

Note: Every option in server mode (after -l) is passed directly to the ncat listener. Refer to man ncat for more details on the available commands. Unless specified, the default IP:PORT values of 127.0.0.1:49200 (for IPv4) or [::1]:49200 (for IPv6) will be used (e.g. asn -l)

Default behavior:
Preferences file ($HOME/.asnrc)

Options defaults can be overridden by creating a file called .asnrc in the user's home directory. The following values are the defaults. Any (or all) of them can be specified in the settings file and adjusted to the user's preference:

ASN_LOGFILE="$HOME/asndebug.log"
MTR_TRACING=true
ADDITIONAL_INETNUM_LOOKUP=true
DETAILED_TRACE=false
MTR_ROUNDS=5
MAX_CONCURRENT_SHODAN_REQUESTS=10
SHODAN_SHOW_TOP_N=5
MONOCHROME_MODE=false
ASN_DEBUG=false
JSON_OUTPUT=false
JSON_PRETTY=false
DEFAULT_SERVER_BINDADDR_v4="127.0.0.1"
DEFAULT_SERVER_BINDADDR_v6="::1"
DEFAULT_SERVER_BINDPORT="49200"
IQS_ALWAYS_QUERY=false
IQS_CUSTOM_SETTINGS=""
Detailed mode (-d | DETAILED_TRACE=true)
Organization search (-o)
ASN suggest (-a)
Upstream/transit identification (-u)
Server mode (-l)

Notes

Organization data, IP Reputation, noise classification and IP fingerprinting
Geolocation

The script will perform IP and trace hop geolocation with this logic:

  1. Using the ipinfo.io service as a primary source of geolocation data. It offers extremely precise geolocation data based on a proprietary network of geographically distributed probes, and is extremely reliable
  2. Using the ip-api service as a fallback source of geolocation data
  3. Using the Prefix Whois service as a last-resort source of geolocation data
IP Classification

The script will use the ip-api, incolumitas.com, ipinfo.io and PeeringDB services to classify target IPs and trace hops into these categories:

IXP detection and unannounced prefixes

Running lookups from the browser

Prerequisite tools for server mode

Server mode requires two tools for its functionality: ncat and aha. Specifically, aha (the ANSI->HTML converter) v0.5+ is required. The ncat tool is contained inside the nmap package on older distributions (e.g. Ubuntu 18.04, Debian 9), while it is packaged as a standalone tool on newer ones.

Please refer to the installation section and run the appropriate commands to install the required packages for your operating system, and optionally to install the asn server as a systemd service.

Advantages of server mode

The main advantage of running lookups from the browser, is that every IP address and AS number gets converted into a hyperlink, allowing to perform subsequent lookups by simply clicking on them.

When looking up an URL/hostname/domain, quick WHOIS info and links to relevant external resources will be available in the results.

When looking up an AS number, all peering ASNs will be clickable. Also, if an AS peers at a public facility, PeeringDB info for that facility will be linked directly. Furthermore, additional external BGP information sources will be linked, directly for the target ASN.

Here are some examples:

srvmode_hostname_lookup

srvmode_whois

srvmode_asn_lookup

Server side

Once started in server mode, asn will spin up a custom webserver waiting for browser requests. This is what the server-side console looks like:

server_console

The server is now ready to accept browser requests (only from the local machine, in this case - since I've launched it with no command line switches, which defaults to listening on 127.0.0.1:49200. Refer to the usage section for more information about the available server options).

Client side

Visit this page in your browser and follow the instructions to copy the bookmarklet to your bookmarks toolbar:

bookmarklet_install

How it works

The bookmarklet is actually a small piece of Javascript code which will grab the hostname of the website you're currently visiting in the browser, and pass it to the server through a simple HTTP GET request. The server then proceeds to perform the lookup and traceroute (from its own viewpoint, just like it does when ran interactively from the command line), and feed the results to your browser through an HTML page, mimicking the effect of a scrolling terminal.

Note: The link you drag to the bookmarks bar is actually a minified (i.e.: compacted) version of the source javascript code, but for reference, here's the full source:

javascript:(function () {
   var asnserver = "localhost:49200";
   var target = window.location.hostname;
   var width = screen.width - screen.width / 7;
   var height= screen.height - screen.height / 4;
   var left = window.innerWidth / 2 - width / 2;
   var top = window.innerHeight / 2 - height / 2;
   window.open("http://" + asnserver + "/asn_lookup&" + target, "newWindow", "width=" + width + ",height=" + height + ",top=" + top + ",left=" + left);
})();

If you want to "un-minify" the actual bookmarklet code, you can refer to this site

Once the trace is finished, an option to share the output on termbin is given to the user. This makes for quick sharing of the traceroute or lookup output with other people:

termbin

termbin_2

Search engine setup

In order to take full advantage of having asn inside the browser, it is possible to configure it as a custom search engine for the browser search bar. This allows to leverage the server to search for ASNs, URLs, IPs, Hostnames, and so on, depending on the search string.

Generally speaking, this implies instructing the browser that when a certain keyword is prepended to a search, the following characters (the actual search string, identified by %s) have to be passed to a certain URL. The URL is then composed according to this logic, and opened just like a normal webpage.

I've used @asn for my keyword, but anything would do. In order to speed up things, one could very well use a shorter tag (e.g. #) that, when used in the address bar, automatically switches your search engine to the ASN Lookup server. Note that the leading @ sign is not mandatory, just handy since it doesn't get in the way of normal searches, but there's much freedom with that.

For quick reference, the location URL string to enter (for both Firefox and Chrome) is: http://127.0.0.1:49200/asn_lookup&%s. Of course that sends lookup requests to the locally running ASN server.

Here's how to add a search engine in Firefox and Chrome:

Firefox:

Afterwards, you will be able to run queries and traceroutes by simply entering, for example, @asn 8.8.8.8 in the browser's location bar.

Chrome:

  1. Right click the location bar and select <i>Manage search engines...</i>

    searchsetup_chrome_1

  2. Click Add:

    searchsetup_chrome_2

  3. Fill in the details as shown below:

    searchsetup_chrome_3

As usual, the keyword is entierly customizable to your preference.

Other browsers:

Running the server on an external host

Port forwarding

In order to access the server remotely, beside binding to 0.0.0.0 (or any other relevant IP address for your scenario), if the host is behind a NAT router, you'll need to forward the listening port (BIND_PORT) from the host/router outside IP to the actual machine where the ASN server is running on. It is a single TCP port (by default TCP/49200), and you can change it via the command line parameters (see Usage).

Textual browser client

It is possible to launch remote traces from another command line, and view the results directly in the terminal. All it takes is a compatible text browser, for example elinks (but you can download results for later reviewing even using curl or really anything else).

The script makes use of 8-bit ANSI colors for its output, so the command to launch a remote trace using elinks would be something like this:

elinks -dump -dump-color-mode 3 http://<ASN_SRV_IP>:49200/asn_lookup&8.8.8.8

Security considerations

The server logic in itself is very simple: the script implements a basic web server entirely in BASH, leveraging the fact that it can talk to a browser using the HTTP protocol and the HTML language, in a reasonably simple way.

The core behind it revolves around ncat, a very robust and stable netcat-like network tool. This is the actual "server" listening for incoming connection, and spawning connection handlers (that is, 'single-purpose' instances of the asn script itself) as clients connect.

If you decide to open it to the outside (i.e.: binding it to something that is not localhost, and launching traces from outside your local machine), please bear in mind that there is no authentication mechanism (yet) integrated into the code, so theoretically anybody with the right URL could spawn traceroutes from your server and view the results (bear in mind however that the server sanitizes user input by stripping any dangerous characters).

To contrast that, fortunately ncat implements a robust allow/deny logic (based both on command line parameters and files, a la /etc/hosts.allow and hosts.deny). The script supports passing parameters directly to ncat, therefore it's possible to make full use of its filtering capabilities and lock the server to a restricted range of trusted IPs.

The available options, and some usage examples, can be viewed by running asn -h.

Note: if you plan to run the server somewhere else than your local machine, remember to change the bookmarklet code and the custom search engine URL values to reflect the actual IP of the asn server. It is naturally possible to have multiple bookmarklets and search engine keywords to map to different ASN server instances.

For the bookmarklet, you'll need to change this value at the very beginning: var asnserver="localhost:49200" and make it point to the new address:port pair. No further change is required in the remaining JS code.

Shodan scanning (Recon Mode)

The tool can query Shodan's InternetDB API to look up informations regarding any type of targets when launched with the -s command line switch.

If the scan identifies any vulnerabilities, the NIST NVD API is queried in order to provide descriptions, any well known names and a link to learn more about the top ones.

Currently supported targets are:

Target types can be mixed and queried in a single run. Targets can be piped to the tool via standard input as well.

Usage Examples:

asn -s 1.1.1.1 8.8.8.8 9.9.9.9

asn -s https://www.google.com 8.8.8.0/24

asn -s < iplist

curl -s https://raw.githubusercontent.com/firehol/blocklist-ipsets/master/blocklist_de_bots.ipset | asn -s

Shodan scan results can be output in JSON mode by passing the -j or -J options.

Note: the Nmap tool is needed to use this feature, but note that no packets whatsoever are sent to the targets. Nmap is only required to break down CIDR blocks into single IPs (as a calculator tool).

Mapping the IP(v4/v6) address space of specific countries

The tool will search and display all IPv4 and IPv6 CIDR blocks allocated to a specific country when launched with the -c command line switch, plus some statistics.

Usage Examples:

asn -c germany

asn -c .de

# scan a random norwegian subnet for CVE/CPE/open ports/hostnames:
asn -jc .no | jq -r ".results[] | .ipv4[$RANDOM % .ipv4_blocks]" | asn -s

Bulk geolocation mode

In this mode the tool will extract all IPv4 and IPv6 addresses from the input data and geolocate them. Anycast detection and general stats (top IPv4/IPv6 addresses with number of occurrences, number of IPs per country etc.) are included in the output. Bulk geolocation is quicker than normal asn lookups (300 IP addresses can be parsed in ~5s), and its main use case is to extract, geolocate and calculate country/occurrence stats for any number of IPs from arbitrarily formatted data streams (e.g. server logs). JSON output and stdin input are supported.

Usage Examples:

asn -g 1.1.1.1 8.8.8.8

# geolocate webserver clients
asn -g < /var/log/apache2/access.log

# geolocate IPs that have logged in to the system
last | asn -g

JSON output and API mode

Locally (shell mode)

The tool can be instructed to output lookup results in JSON mode by using the -j (compact JSON) or -J (pretty-printed JSON) command line options:

<details><summary><i>Example 1 - IPv4 lookup</i></summary><p>
Command:

asn -J 8.8.8.8

Output:
{
  "target": "8.8.8.8",
  "target_type": "ipv4",
  "result": "ok",
  "reason": "success",
  "version": "0.78.0",
  "request_time": "2024-08-20T02:50:28",
  "request_duration": 5,
  "api_tokens": {
    "ipqualityscore": true,
    "ipinfo": true,
    "cloudflare": true
  },
  "result_count": 1,
  "results": [
    {
      "ip": "8.8.8.8",
      "ip_version": "4",
      "reverse": "dns.google",
      "org_name": "Google LLC",
      "net_range": "8.8.8.0/24",
      "net_name": "GOGL",
      "abuse_contacts": [
        "network-abuse@google.com"
      ],
      "routing": {
        "is_announced": true,
        "as_number": "15169",
        "as_name": "GOOGLE, US",
        "as_rank": "1788",
        "route": "8.8.8.0/24",
        "route_name": "",
        "roa_count": "1",
        "roa_validity": "valid"
      },
      "type": {
        "is_bogon": false,
        "is_anycast": true,
        "is_mobile": false,
        "is_proxy": false,
        "is_dc": true,
        "dc_details": {
          "dc_name": "Google LLC"
        },
        "is_ixp": false
      },
      "geolocation": {
        "city": "Mountain View",
        "region": "California",
        "country": "United States",
        "cc": "US"
      },
      "reputation": {
        "status": "good",
        "is_known_good": true,
        "known_as": "Google Public DNS"
      },
      "fingerprinting": {
        "ports": [
          53,
          443
        ]
      }
    }
  ]
}
</p></details> <details><summary><i>Example 2 - ASN lookup</i></summary><p>
Command:

asn -J 5505

Output:
{
  "target": "5505",
  "target_type": "asn",
  "result": "ok",
  "reason": "success",
  "version": "0.78.0",
  "request_time": "2024-08-20T02:50:46",
  "request_duration": 17,
  "api_tokens": {
    "ipqualityscore": true,
    "ipinfo": true,
    "cloudflare": true
  },
  "result_count": 1,
  "results": [
    {
      "asn": "5505",
      "asname": "VADAVO, ES",
      "asrank": 4448,
      "org": "VDV-VLC-RED06 VDV-VLC-RED06 - CLIENTES TELECOM",
      "holder": "VADAVO SOLUCIONES SL",
      "abuse_contacts": [
        "abuse@vadavo.com"
      ],
      "registration_date": "2016-12-13T08:28:07",
      "ixp_presence": [
        "DE-CIX Madrid: DE-CIX Madrid Peering LAN",
        "ESpanix Madrid Lower LAN"
      ],
      "prefix_count_v4": 8,
      "prefix_count_v6": 1,
      "bgp_peer_count": 36,
      "bgp_hijack_incidents": {
        "total": 0,
        "as_hijacker": 0,
        "as_victim": 0
      },
      "bgp_leak_incidents": {
        "total": 0
      },
      "bgp_peers": {
        "upstream": [
          "1299",
          "6939",
          "59432",
          "174",
          "34549",
          "25091",
          "35625",
          "33891",
          "48348",
          "13030",
          "8218",
          "41327",
          "3303",
          "4455",
          "6424",
          "6057",
          "34927",
          "9498",
          "35280",
          "1239"
        ],
        "downstream": [
          "48952",
          "208248",
          "205086",
          "202054"
        ],
        "uncertain": [
          "24482",
          "51185",
          "41047",
          "29680",
          "212483",
          "198150",
          "14840",
          "49544",
          "39384",
          "37721",
          "36236",
          "25160"
        ]
      },
      "announced_prefixes": {
        "v4": [
          "185.210.225.0/24",
          "188.130.247.0/24",
          "185.210.227.0/24",
          "185.123.205.0/24",
          "185.123.207.0/24",
          "185.210.226.0/24",
          "185.123.206.0/24",
          "185.123.204.0/24"
        ],
        "v6": [
          "2a03:9320::/32"
        ]
      },
      "inetnums": {
        "v4": [
          "185.123.204.0/22",
          "185.210.225.0/24",
          "185.210.226.0/24",
          "185.210.227.0/24",
          "188.130.247.0/24"
        ],
        "v6": [
          "2a03:9320::/32"
        ]
      },
      "inetnums_announced_by_other_as": {
        "v4": [
          {
            "prefix": "188.130.254.0/24",
            "origin_asn": "",
            "origin_org": "",
            "is_announced": false
          }
        ],
        "v6": []
      }
    }
  ]
}
</p></details> <details><summary><i>Example 3 - enumerating abuse contacts for every IP to which a hostname resolves</i></summary><p>
Command:

asn -j www.google.com | jq '[.results[].abuse_contacts[]] | unique[]'

Output:
"network-abuse@google.com"
"ripe-contact@google.com"
</p></details> <details><summary><i>Example 4 - enumerating known vulnerabilities for a target</i></summary><p>
Command:

asn -j 45.67.34.100 | jq '.results[].fingerprinting.vulns[]'

Output:
"CVE-2017-15906"
"CVE-2018-15919"
</p></details> <details><summary><i>Example 5 - upstream/transit AS lookup for a given IP</i></summary><p>
Command:

asn -Ju 72.17.119.201

Output:
{
  "target": "72.17.119.201",
  "target_type": "ipv4",
  "result": "ok",
  "reason": "success",
  "version": "0.78.0",
  "request_time": "2024-08-20T02:54:03",
  "request_duration": 4,
  "api_tokens": {
    "ipqualityscore": true,
    "ipinfo": true,
    "cloudflare": true
  },
  "result_count": 1,
  "results": [
    {
      "prefix": "72.17.0.0/17",
      "origin_as": "33363",
      "origin_as_name": "BHN-33363, US",
      "origin_as_rank": 441,
      "upstreams_count": 1,
      "upstreams": [
        {
          "asn": "7843",
          "asname": "TWC-7843-BB, US",
          "probability": 100,
          "is_tier1": false
        }
      ],
      "multiple_upstreams": false
    }
  ]
}
</p></details> <details><summary><i>Example 6 - enumerating unannounced address blocks for a given AS</i></summary><p>
Command:

asn -j AS5505 | jq -r '.results[].inetnums_announced_by_other_as.v4[] | select(.is_announced==false) | .prefix'

Output:
188.130.254.0/24
</p></details> <details><summary><i>Example 7 - enumerating the amount of BGP hijacking incidents involving a given AS</i></summary><p>
Command:

asn -j AS8860 | jq '.results[].bgp_hijack_incidents'

Output:
{
  "total": 18,
  "as_hijacker": 11,
  "as_victim": 7
}
</p></details>

Remotely (API endpoint)

By running the script in server mode, it is possible to use it as a self-hosted lookup API service by running HTTP queries against it and retrieving the results in compact or pretty-printed JSON format. The server exposes the asn_lookup_json and asn_lookup_jsonp endpoints for this purpose. The syntax is the same as with normal browser-based remote queries.

Example 1: querying the server remotely using curl (compact output):

root@KRUSTY:~# curl -s "http://localhost:49200/asn_lookup_json&1.1.1.1"
{"target":"1.1.1.1","target_type":"ipv4","result":"ok","reason":"success","version":"0.72.1","request_time":"2022-03-29T00:13:11","request_duration":5,"result_count":1,"results":[{"ip":"1.1.1.1","ip_version":"4","reverse":"one.one.one.one","org_name":"APNIC and Cloudflare DNS Resolver project","abuse_contacts":["helpdesk@apnic.net"],"routing":{"is_announced":true,"as_number":"13335","as_name":"CLOUDFLARENET, US","net_range":"1.1.1.0/24","net_name":"APNIC-LABS","roa_count":"1","roa_validity":"valid"},"type":{"is_bogon":false,"is_anycast":true,"is_mobile":false,"is_proxy":false,"is_dc":true,"dc_details":{"dc_name":"Cloudflare"},"is_ixp":false},"geolocation":{"city":"Magomeni","region":"Dar es Salaam","country":"Tanzania","cc":"TZ"},"reputation":{"status":"good","is_known_good":true,"known_as":"Cloudflare Public DNS"},"fingerprinting":{"ports":[53,80,443]}}]}

Example 2: querying the server remotely using curl (pretty printed output):

root@KRUSTY:~# curl -s "http://localhost:49200/asn_lookup_jsonp&10.0.0.1"
{
  "target": "10.0.0.1",
  "target_type": "ipv4",
  "result": "ok",
  "reason": "success",
  "version": "0.72.1",
  "request_time": "2022-03-29T00:14:57",
  "request_duration": 0,
  "result_count": 1,
  "results": [
    {
      "ip": "10.0.0.1",
      "ip_version": "4",
      "org_name": "IANA",
      "routing": {
        "is_announced": false,
        "net_name": "PRIVATE-ADDRESS-ABLK-RFC1918-IANA-RESERVED"
      },
      "type": {
        "is_bogon": true,
        "bogon_type": "rfc1918 (Private Space)"
      },
      "reputation": {},
      "fingerprinting": {}
    }
  ]
}

Thanks

An initial version of this script was featured in the Security Trails blog post "ASN Lookup Tools, Strategies and Techniques". Thank you Esteban!

Thanks Massimo Candela for your support and excellent work on IPmap, BGPlay and TraceMON!

Thanks to all the awesome contributors for their code, ideas, suggestions, packages and bug reports!

Feedback and contributing

Any feedback or pull request to improve the code is welcome. Feel free to contribute!