asname

README

asname

asname is a fast, offline command-line utility written in Go for resolving IP addresses, hostnames and URLs to their Autonomous System Number (ASN), the AS owner's name, and the geographical country.

Lookups are answered from local LC-trie databases, so there is no per-query network call and no API key or rate limit to worry about.

Features

• Blazing Fast: Uses offline LC-trie databases for instantaneous IP lookups.
• Takes Whatever You Have: An IP address, a hostname, a URL you pasted from a browser, or a file listing any mix of them.
• Auto-Updating: Automatically fetches the latest RouteViews RIB dumps, RIPE ASN names, and RIR Delegation Statistics to build and maintain its own fresh databases when they get older than 30 days.
• Fully Standalone: A single static binary — no Cgo, and no geoiplookup or other system tool to install alongside it.

Installation

go install github.com/flyingllama87/asname@latest

Or build and install from a clone using the provided Makefile, which stamps the version into the binary and links it statically:

make build
sudo make install

This compiles the tool and places the asname binary into /usr/local/bin/. Run make test to run the test suite.

Usage

Simply pass an IP address to resolve its information:

$ asname 8.8.8.8
IP: 8.8.8.8 → ASN: AS15169 → Name: GOOGLE - Google LLC, US → Country: US, United States

The argument can equally be a hostname. Every address the name resolves to is looked up, one line each:

$ asname dns.google
Host: dns.google → IP: 8.8.8.8 → ASN: AS15169 → Name: GOOGLE - Google LLC, US → Country: US, United States
Host: dns.google → IP: 8.8.4.4 → ASN: AS15169 → Name: GOOGLE - Google LLC, US → Country: US, United States

Or a URL, so you can paste one straight from a browser. The scheme, credentials, port, path, query and fragment are stripped and whatever host remains is looked up:

$ asname 'https://dns.google:443/resolve?name=example.com'
Host: dns.google → IP: 8.8.8.8 → ASN: AS15169 → Name: GOOGLE - Google LLC, US → Country: US, United States

Or a file listing any mix of the above, one entry per line. Blank lines and # comments are ignored, and only the first field of a line is read, so columnar files work as they are:

$ cat hosts.txt
# resolvers to check
8.8.8.8
1.1.1.1          # cloudflare
https://github.com/anthropics

$ asname hosts.txt
IP: 8.8.8.8 → ASN: AS15169 → Name: GOOGLE - Google LLC, US → Country: US, United States
IP: 1.1.1.1 → ASN: AS13335 → Name: CLOUDFLARENET - Cloudflare, Inc., US → Country: AU, Australia
Host: github.com → IP: 4.237.22.38 → ASN: AS8075 → Name: MICROSOFT-CORP-MSN-AS-BLOCK - Microsoft Corporation, US → Country: US, United States

Entries that cannot be resolved are reported on stderr and the rest of the file is still printed; asname then exits non-zero. Names are resolved concurrently, so a long file is not paced by DNS latency.

An argument that parses as an IP address is always treated as one; otherwise an existing file is read as a list, and anything else is treated as a hostname or URL.

Add --reverse-dns (or -r) to also send a reverse DNS query and include PTR names in the output:

$ asname --reverse-dns 8.8.8.8
IP: 8.8.8.8 → ASN: AS15169 → Name: GOOGLE - Google LLC, US → Country: US, United States → Reverse DNS: dns.google

City lookups

City-level geolocation is optional and off by default, because the database is large. Enable it once with --city (or -c), which downloads it:

$ asname --city 8.8.8.8
IP: 8.8.8.8 → ASN: AS15169 → Name: GOOGLE - Google LLC, US → Country: US, United States → City: Mountain View, California

After that the flag is not needed — the city is included whenever the database is present, and refreshed along with everything else:

$ asname 1.1.1.1
IP: 1.1.1.1 → ASN: AS13335 → Name: CLOUDFLARENET - Cloudflare, Inc., US → Country: AU, Australia → City: Sydney, New South Wales

Use --no-city to suppress it for one run, or delete ~/.asname/city.mmdb to opt back out for good. asname update refreshes the city database only once you already have it, so it is never fetched unasked.

Treat the city as a hint, not a fact. DB-IP rate the free Lite database at an accuracy index of 77, against 96 for their commercial one. VPNs, mobile carriers, CGNAT and anycast routinely place an address hundreds of kilometres from where it really is — dns.google's IPv6 anycast address reports as Montreal, for instance. The ASN and AS name come from BGP and are solid; the city is a best guess.

Add --uniform (or -u) to print aligned fields:

$ asname -u -r 8.8.8.8
IP: 8.8.8.8                                → ASN: AS15169      → Name: GOOGLE - Google LLC, US                                      → Country: US, United States         → Reverse DNS: dns.google

Manual Updates

You can manually trigger an update of the local databases using:

asname update

You can also update specific databases using the --db-only, --names-only, or --country-only flags.

Database Locations

By default, asname stores its auto-updating databases in your home directory under ~/.asname/. The following files will be created:

• ~/.asname/asname.db: The binary LC-trie database for IP to ASN resolution.
• ~/.asname/asn_db.txt: The text file mapping ASNs to their respective names.
• ~/.asname/country.db: The binary LC-trie database for IP to Country mapping.
• ~/.asname/city.mmdb: The DB-IP Lite city database, in MaxMind DB format. Only present if you have enabled city lookups; ~125 MB.

You can override this directory by setting the ASNAME_DIR environment variable or using the --dir flag. You can also override the path to individual databases using the ASNAME_DB, ASNAME_NAMES, ASNAME_COUNTRY, and ASNAME_CITY environment variables or their respective flags.

Credits

The LC-trie implementation and the binary database format under pkg/binarytrie and pkg/database are derived from asnlookup by @banviktor, used under the Apache License 2.0. Those files have been modified for use here — the database type was reworked into an interface, trie optimization was parallelised, and the marshalling header was changed. Each file carries a notice to that effect.

Data comes from RouteViews (BGP RIB dumps), RIPE NCC (ASN names), and the RIR delegation statistics files (IP to country).

City data is the DB-IP Lite database — IP Geolocation by DB-IP, licensed under CC BY 4.0. It is downloaded on request and is not redistributed with this tool.

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

Documentation

Overview

Command asname resolves an IP address, hostname or URL to its Autonomous System number, the AS owner's name and the geographic country. The argument can also be a file holding a list of entries to look up.

Lookups are answered offline, from three data files: an LC-trie database for the IP->ASN mapping, a RIPE asn.txt derived file for the ASN->name mapping and a second LC-trie built from the RIRs' delegation statistics for the IP->country mapping. All of them can be refreshed with `asname update`, and lookups auto-refresh stale data unless disabled.

City lookups are optional and add a fourth, much larger file, so they are only enabled once the user asks with --city. See city.go.