ipwhois 0.14.0

Retrieve and parse whois data for IPv4 and IPv6 addresses.

ipwhois is a Python package focused on retrieving and parsing whois data for IPv4 and IPv6 addresses.

Attention!

NIR (National Internet Registry) lookups are now enabled by default. This is currently only performed for JPNIC and KRNIC addresses. To disable, set inc_nir=False in your IPWhois.lookup_*() query.

Attention!

The ‘nets’ -> ‘emails’ key in IPWhois.lookup_whois() has been changed from a ‘\n’ separated string to a list.

Important

RDAP (IPWhois.lookup_rdap()) is the recommended query method as of v0.11.0. If you are upgrading from earlier than 0.11.0, please see the upgrade info.

Note

If you are experiencing latency issues, it is likely related to rate limiting. Profiling the tests, I see most time spent attributed to network latency. Rate limiting is based on your source IP, which may be a problem with multiple users behind the same proxy. Additionally, LACNIC implements aggressive rate limiting. Bulk query optimization is on the roadmap (https://github.com/secynic/ipwhois/issues/134)

Features

• Parses a majority of whois fields in to a standard dictionary

• IPv4 and IPv6 support

• Supports RDAP queries (recommended method, see: https://tools.ietf.org/html/rfc7483)

• Proxy support for RDAP queries

• Supports legacy whois protocol queries

• Referral whois support for legacy whois protocol

• Recursive network parsing for IPs with parent/children networks listed

• National Internet Registry support for JPNIC and KRNIC

• Python 2.6+ and 3.3+ supported

• Useful set of utilities

• BSD license

• 100% core code coverage (See ‘# pragma: no cover’ for exclusions)

• Human readable field translations

• Full CLI for IPWhois with optional ANSI colored console output.

Links

Documentation

Release v0.14.0

https://ipwhois.readthedocs.io/en/v0.14.0

GitHub master

https://ipwhois.readthedocs.io/en/latest

GitHub dev

https://ipwhois.readthedocs.io/en/dev

Examples

https://github.com/secynic/ipwhois/tree/master/ipwhois/examples

Github

https://github.com/secynic/ipwhois

Pypi

https://pypi.python.org/pypi/ipwhois

Changes

https://ipwhois.readthedocs.io/en/latest/CHANGES.html

Dependencies

Python 2.6, 2.7:

dnspython
ipaddr

Python 3.3+:

dnspython3

Installing

Latest release from PyPi:

pip install --upgrade ipwhois

GitHub - Stable:

pip install -e git+https://github.com/secynic/ipwhois@master#egg=ipwhois

GitHub - Dev:

pip install -e git+https://github.com/secynic/ipwhois@dev#egg=ipwhois

Firewall Ports

ipwhois needs some outbound firewall ports opened from your host/server.

ASN (DNS):

53/tcp

ASN (Whois):

43/tcp

ASN (HTTP):

80/tcp

443/tcp (Pending)

RDAP (HTTP):

80/tcp

443/tcp (Pending)

Legacy Whois:

43/tcp

Get Host:

43/tcp

API

IPWhois (main class)

ipwhois.IPWhois is the base class for wrapping RDAP and Legacy Whois lookups. Instantiate this object, then call one of the lookup functions:

RDAP (HTTP) - IPWhois.lookup_rdap() OR Legacy Whois - IPWhois.lookup_whois()

Input

Key	Type	Description
address	String	An IPv4 or IPv6 address as a string, integer, IPv4Address, or IPv6Address.
timeout	Int	The default timeout for socket connections in seconds.
proxy_opener	Object	The urllib.request.OpenerDirector request for proxy support or None.
allow_permutations	Bool	Allow net.Net() to use additional methods if DNS lookups to Cymru fail.

RDAP (HTTP)

IPWhois.lookup_rdap() is the recommended lookup method. RDAP provides a far better data structure than legacy whois and REST lookups (previous implementation). RDAP queries allow for parsing of contact information and details for users, organizations, and groups. RDAP also provides more detailed network information.

RDAP documentation:

https://ipwhois.readthedocs.io/en/latest/RDAP.html

Legacy Whois

IPWhois.lookup() is deprecated as of v0.12.0 and will be removed. Legacy whois lookups were moved to IPWhois.lookup_whois().

Legacy Whois documentation:

https://ipwhois.readthedocs.io/en/latest/WHOIS.html

National Internet Registries

This library now supports NIR lookups for JPNIC and KRNIC. Previously, Whois and RDAP data for Japan and South Korea was restricted. NIR lookups scrape these national registries directly for the data restricted from regional internet registries. NIR queries are enabled by default via the inc_nir argument in the IPWhois.lookup_*() functions.

https://ipwhois.readthedocs.io/en/latest/NIR.html

Utilities

Utilities documentation:

https://ipwhois.readthedocs.io/en/latest/UTILS.html

Scripts

CLI documentation:

https://ipwhois.readthedocs.io/en/latest/CLI.html

Contributing

https://ipwhois.readthedocs.io/en/latest/CONTRIBUTING.html

IP Reputation Support

This feature is under consideration. Take a look at TekDefense’s Automater:

TekDefense-Automater

Domain Support

There are no plans for domain whois support in this project.

Look at Sven Slootweg’s python-whois for a library with domain support.

Special Thanks

Thank you JetBrains for the PyCharm open source support!

Changelog

0.14.0 (2016-08-29)

• Changed legacy whois emails output type to list (#133)

• Fixed retry count non-decrementing infinite loop in ipwhois.net.Net.get_whois() (issue #125 - krader1961)

• Added new function ipwhois.net.Net.get_http_raw() and tests (#67)

• Added National Internet Registry (JPNIC, KRNIC) support (#67). Enabled by default in IPWhois.lookup_*(). Disable by passing inc_nir=False. Optionally, lower level code can call nir.NIRWhois(). This enhancement results in extra network queries, but more detailed information for NIRs.

• Added utils CLI (ipwhois_utils_cli.py) - #121. Installed to your environments Scripts dir. This is a wrapper for utils.py.

• Documentation improvements (#123)

• kw arg readability (#115)

• Replaced usage of args with script_args in ipwhois_cli.py

• Minor optimization in whois.py and online/test_whois.py

• Added coveralls integration and re-enabled online tests with Travis CI

• Added Read the Docs support (#132)

• Added documentation (Sphinx) requirements.txt (#132)

• Fixed test imports

• Added –json argument (output in JSON format) to ipwhois_cli.py (#135)

0.13.0 (2016-04-18)

• Added events_actor parsing for RDAP results.

• Added example for caching data via Redis (#81)

• Added normalization (human-readable field information) in hr.py (#47)

• README word wrap fix (#102)

• Fixed bug in exception handling for ASN HTTP lookups.

• Fixed bug in IPWhois.lookup_rdap() that caused ASN HTTP lookup responses to be used in place of RDAP responses.

• Added new function Net.get_asn_http() and migrated code from Net.lookup_asn() + new tests.

• Fixed bug in ASN HTTP fallback lookups for DNIC (#108).

• Added new parameter extra_org_map in Net.get_asn_http(), Net.lookup_asn(), and IPWhois.lookup*() (#108).

• Fixed _RDAPCommon.summarize_notices() None check - changed len() to all().

• Added CLI (ipwhois_cli.py) - #46. Installed to your environments Scripts dir. This is a wrapper for ipwhois.py (IPWhois). Utils CLI will be in a future release (#121).

• Documentation split up and added more detail (#81).

0.12.0 (2016-03-28)

• Added headers parameter to ipwhois.Net.get_http_json() (issue #98).

• Fixed ASN HTTP lookup (fallback) Accept headers (issue #98).

• Fixed HTTP decoding, set to utf-8 (italomaia - issue #97)

• IPWhois.lookup() deprecated (issue #96), and will be removed in a future release (TBD). Use IPWhois.lookup_whois() instead.

• Added rate_limit_timeout parameter (issue #99) to Net.get_http_json(), IPWhois.lookup_rdap(), and RDAP.lookup(). New exception HTTPRateLimitError.

• Added new parameter asn_alts to Net.lookup_asn(), IPWhois.lookup_rdap() and IPWhois.lookup(). Takes an array of lookup types to attempt if the ASN dns lookup fails. Allow permutations must be enabled. Defaults to all [‘whois’, ‘http’] (issue #93).

• Fixed socket exception handling in Net.get_http_json() for Python 2.6.

• Fixed assertIsInstance for Python 2.6 tests (issue #100). Implemented unittest._formatMessage and unittest.util.safe_repr for Python 2.6.

• Moved TestCommon to tests\__init__.py to avoid duplicate code.

• Replaced remaining % with str.format (issue #95).

0.11.2 (2016-02-25)

• Added allow_permutations parameter (bool) to net.Net() and ipwhois.IPWhois() to allow alternate ASN lookups if DNS lookups fail. (FirefighterBlu3)

• Fixed ASN DNS resolver timeout/retry_count support. Retry count is used as a multiplier of timeout, to determine a limetime interval. (FirefighterBlu3)

• Fixed bug where remarks would return None if missing a title.

• Added CONTRIBUTING.rst

• Added tests

0.11.1 (2015-12-17)

• Re-added CIDR calculation for RDAP lookups.

• Improved tests - core code coverage now 100%. See ‘# pragma: no cover’ for exclusions. A few bugs were identified in the process, detailed below.

• Moved IP zero stripping from rdap._RDAPNetwork.parse() to new helper function utils.ipv4_lstrip_zeros().

• Moved CIDR calculation from rdap._RDAPNetwork.parse() to new helper function utils.calculate_cidr().

• Fixed utils.ipv4_is_defined() if statement ordering for RFC 1918 conflict.

• Fixed utils.ipv6_is_defined() if statement ordering for Unspecified and Loopback (conflict with Reserved).

• Added is_offline parameter to whois.Whois.lookup() primarily for testing.

• Fixed bug in whois.Whois._parse_fields() that attempted to parse ‘val2’ of regex, which is no longer used. Also fixed the expected Exception to be IndexError.

• Fixed bug in ipwhois.IPWhois.lookup() where the argument order was mixed up, causing referral lookups to be skipped when get_referral=True.

• Fixed bug in rdap._RDAPCommon.summarize_notices() output for links.

• Fixed bug in root entity iteration exception handling in rdap.RDAP.lookup().

0.11.0 (2015-11-02)

• Support for REST lookups replaced with RDAP.

• Split code for a more structured system (net, whois, rdap, exceptions).

• Tests match the data new structure.

• Split tests for online and offline testing.

• Performance enhancements for parsing.

• Added an optional bootstrap parameter for RDAP lookups, in order to replace ASN lookups or use both. Will default to False. Afrinic is currently not supported, so I would not use this for now. ARIN acknowledged my issue for this, and will be adding support back in for Afrinic bootstrap.

• Added field_list parameter (inclusion list) for WHOIS lookups.

• Added logging.

• Added examples directory.

0.10.3 (2015-08-14)

• Fixed LACNIC lookup_rws() queries, since they switched to RDAP. This is temporary to get it working until the major library transition to RDAP and new parsed formatting is complete.

0.10.2 (2015-05-19)

• Fixed APNIC parsing for updated field.

• Fixed datetime parsing and validation when Zulu (Z) is appended.

• Added RIPE parsing for created and updated fields (whois and RWS).

• Removed unnecessary parentheses in IPWhois class declaration.

• Some documentation and comment tweaking to work with Sphinx.

• Minor PEP 8 tweaks.

0.10.1 (2015-02-09)

• Fixed setup.py bug.

0.10.0 (2015-02-09)

• Added .csv support for country code source. You can no longer download country code information from iso.org.

• Added support for IPv4Address or IPv6Address as the address arg in IPWhois.

• Fixed file open encoding bug. Moved from open to io.open.

• Fixed parameter in IPWhois ip defined checks.

• Fixed TestIPWhois.test_ip_invalid() assertions.