Skip to content
BatistaFelipePublic

About

Single-file Python CLI that resolves a hostname to an IP and queries ipinfo.io for geolocation and ASN data. Can print the result for a single host or batch-process a list of hosts into a CSV file.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 

Repository files navigation

geoip

Single-file Python CLI that resolves a hostname to an IP and queries ipinfo.io for geolocation and ASN data. Can print the result for a single host or batch-process a list of hosts into a CSV file.

  • Stdlib only — no third-party dependencies.
  • SSRF-safe: refuses to look up loopback, private, link-local, multicast, reserved, or unspecified addresses.
  • HTTPS to ipinfo.io with verified TLS and a configurable timeout.
  • Batch mode continues on per-host failures and writes a properly quoted ;-delimited CSV via the stdlib csv module.

Requirements

  • Python 3.10 or newer (uses dict[str, Any] and list[str] | None).

Installation

Clone the repo and run the script directly — no dependencies to install.

git clone <repo-url> geoip
cd geoip
python geoip.py --help

A .venv/ directory is included for convenience if you want to add tooling (black, ruff, pytest). Activate it before installing anything:

# Windows
.venv/Scripts/activate

# Linux / macOS
source .venv/bin/activate

Usage

Single host

Prints each ipinfo field on its own line and exits 0 on success, 1 on failure.

python geoip.py 8.8.8.8
python geoip.py dns.google

Example output:

ip: 8.8.8.8
hostname: dns.google
city: Mountain View
region: California
country: US
loc: 38.0088,-122.1175
org: AS15169 Google LLC
postal: 94043
timezone: America/Los_Angeles

Batch mode

Reads one host per line from FILE and appends host;ip;org rows to the output CSV. Exits 0 when every host succeeds, 2 when at least one fails (the batch is not aborted — failing hosts are logged and skipped).

python geoip.py -f domains.txt
python geoip.py -f domains.txt -o out.csv --timeout 5

The output file is opened in append mode, so re-running duplicates rows. Truncate the file first for a clean rebuild:

: > data.csv && python geoip.py -f domains.txt

Options

usage: geoip.py [-h] [-f FILE] [-o OUTPUT] [--timeout TIMEOUT] [host]

positional arguments:
  host                  hostname to resolve and look up

options:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  batch mode: read hostnames one per line from FILE
  -o OUTPUT, --output OUTPUT
                        CSV output path for batch mode (default: ./data.csv)
  --timeout TIMEOUT     HTTP timeout in seconds (default: 10.0)

Exactly one of host or -f/--file must be provided.

Exit Codes

Code Meaning
0 Success
1 Single-host lookup failed (DNS, SSRF guard, network, TLS)
2 Batch finished with at least one failed host, or bad usage

Environment Variables

None. The script requires no configuration beyond its CLI flags. ipinfo.io is queried without a token, so the free unauthenticated quota applies (~50k requests/month).

Security Notes

  • The resolved IP is validated with ipaddress.ip_address and rejected if the address is private, loopback, link-local, multicast, reserved, or unspecified. This prevents DNS-rebinding or SSRF via attacker-controlled hostnames.
  • The org field written to CSV is prefixed with ' when it begins with = + - @ to neutralize spreadsheet-formula injection.
  • All HTTP calls use https:// with ssl.create_default_context().

About

Single-file Python CLI that resolves a hostname to an IP and queries ipinfo.io for geolocation and ASN data. Can print the result for a single host or batch-process a list of hosts into a CSV file.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages