Package: ipref
iprefipref-pyis a simple utility to look up IP addresses in MaxMind's GeoIP
downloadable databases by command-line and web.I often look up geolocation data of a number of IP addresses in my research,
but existing tools do not satisfy this need.
So, I wroteipref-py.Note that the web interface must be used for internal use only such as your own
environment and your lab. If you make it public, it can be abused for attackers
and may also violate terms of use by MaxMind.Main features:Look up IP addresses by MaxMind's GeoIP databases.Look up hostnames of IP addresses by DNS reverse lookups.A command line and a simple web interface.Configuration by YAML files.Flexible outputs (JSON, JSON-Lines, CSV, TSV).RequirementsPython 3.7-Linux or macOS (It may work in Windows but I have not checked yet.)Installation(Optional, but recommended) Create a virtualenv environment for Python.# /path/to/dir/ depends on your environment. e.g. /opt/ipref/$cd/path/to/dir/# Create a virtualenv$python3-mvenvenv# Activate the virtualenv$sourceenv/bin/activateYou can installipref-pyvia pypi (plus, the wheel file is available fromGitHub releasepage).# if you want CLI only(env)$pipinstallipref# if you want CLI and web interface(env)$pipinstallipref[web]ConfigurationMake a configuration file.
The template files for configurations are available.GeoIP2:https://github.com/md-irohas/ipref-py/blob/main/ipref/config.yaml.origGeoLite:https://github.com/md-irohas/ipref-py/blob/main/ipref/config-geolite.yaml.origConfiguration files are loaded from the following paths:~/.config/ipref.yaml~/.config/ipref.yml~/.ipref.yaml~/.ipref.yml(environment variableIPREF_CONF)(command line argument [CLI only])The latter file overwrites the former one.# Copy the configuration template above and edit it.$vim~/.config/ipref.yaml
...(edit)...CLI ExamplesUsage$ipref--help

usage:ipref[-h][-v][-d][-cCONFIG][-I{ip,file}][-O{tsv,json,jsonl,csv}][--csv-columnsCSV_COLUMNS][--csv-exclude-header][--csv-escape-comma][items...]positionalarguments:itemsIPaddressesorfilenames.ifinput_typeisfileandtheitemsareempty,stdinisused.(default:None)options:-h,--helpshowthishelpmessageandexit-v,--versionshowversionandexit.-d,--debugenabledebugloggingtostderr.(default:False)-cCONFIG,--configCONFIGpathtoconfigfile.(default:None)-I{ip,file},--input-type{ip,file}inputtype.(default:ip)-O{tsv,json,jsonl,csv},--output-format{tsv,json,jsonl,csv}outputformat.(default:json)--csv-columnsCSV_COLUMNS[csv|tsv]outputcolumnsseparatedbycomma(,).(default:None)--csv-exclude-header[csv|tsv]excludeacsvheader.(default:False)--csv-escape-comma[csv|tsv]replacecommas(,)to<comma>(usefulwhenusingcommandssuchas'cut').(default:False)Example-1: First stepThe following example looks up "1.1.1.1" and "8.8.8.8" from command line and dumps the results as CSV format.$ipref-Ocsv"1.1.1.1""8.8.8.8"meta.raw_input,meta.ip_address_types,geoip.city.continent.names.en,geoip.city.country.iso_code,geoip.city.country.names.en,geoip.city.city.names.en,geoip.city.postal.code,geoip.city.location.latitude,geoip.city.location.longitude,geoip.asn.autonomous_system_number,geoip.asn.autonomous_system_organization1.1.1.1,public,,,,,,,,13335,CLOUDFLARENET8.8.8.8,public,NorthAmerica,US,UnitedStates,,,37.751,-97.822,15169,GOOGLEExample-2: Flexible outputYou can specify columns to be printed in CSV/TSV formats.
Seeoutput.columnssection inconfig.yaml.origfor the list of column names.$ipref-Ocsv--csv-columnsmeta.raw_input,geoip.city.country.name"1.1.1.1""8.8.8.8"meta.raw_input,geoip.city.country.name1.1.1.1,8.8.8.8,UnitedStatesYou can also set columns in the configuration file.Example-3: Bulk searchTo look up a number of IP addresses, you can pass them through files.# from stdin$catip-list.txt|ipref-Ocsv# from files$ipref-Ifile-Ocsvfile1.txtfile2.txt...Web ExamplesA simple web app is also avaialble.Example-4: Launch a web appLaunch ipref-web from command line and accesshttp://localhost:5000/.
A simple web interface like the above figure is shown.$IPREF_CONF="path/to/config.yaml"ipref-webrunInput IP addresses, select checkboxes, and click "Search" button!
The "Look-up Items" are also configurable by config.yaml.Example-5: Run as a production WSGI appUse gunicorn to run ipref-web as a production WSGI app.$gunicorn--envIPREF_CONF="path/to/config.yaml""ipref.web:create_app()"Template files for systemd (as a unit) and nginx (as a reverse proxy) are also available:Systemd's unit file: ipref-web.serviceNginx configuration file: nginx.confAlternativesmmdbinspect:https://github.com/maxmind/mmdbinspect(Official command-line lookup tool)geoiplookupLicenseMIT License (link).Contactmkt (E-mail: md.irohas at gmail.com)