A python package for server applications to retrieve client's IP address
Best attempt to get client's IP address while keeping it DRY.
There is no perfect out-of-the-box solution to counteract fake IP addresses, or IP Address Spoofing. We strongly recommend reading the Advanced Users section. Utilize the proxy_list and proxy_count features to adapt the functionality to your specific requirements, especially if you plan to incorporate python-ipware into authentication, security, or anti-fraud systems.
Keep in mind that python-ipware is an open-source project, meaning its source code is accessible to everyone. While this openness promotes community engagement and scrutiny, it also exposes the code to potential exploiters who might take advantage of unimplemented or improperly implemented features.
Use python-ipware only as an additional layer to bolster your security, not as a primary defense mechanism. Always pair it with robust firewall security protocols to ensure comprehensive protection against a variety of security threats, including IP spoofing.
1. easy_install python-ipware
2. pip install python-ipware
3. git clone http:#github.com/un33k/python-ipware
a. cd python-ipware
b. run python setup.py install
4. wget https:#github.com/un33k/python-ipware/zipball/master
a. unzip the downloaded file
b. cd into python-ipware-* directory
c. run python setup.py install
Here's a basic example of how to use ipware in a view or middleware where the request object is available. This can be applied in Django, Flask, or other similar frameworks.
from ipware import Ipware
# Instantiate Ipware with default values
ipware = Ipware()
# Get the META data from the request object
# For Django use request.META, for Flask use request.environ
meta = request.META
# Get the client IP and the trusted route flag
ip, trusted_route = ipware.get_client_ip(meta)
if ip:
# The 'ip' is an object of type IPv4Address() or IPv6Address() with properties like:
# - ip.is_global: True if the IP is globally routable
# - ip.is_private: True if the IP is a private address
# - ip.is_loopback: True if the IP is a loopback address
# - ip.is_multicast: True if the IP is a multicast address
# - ip.is_unspecified: True if the IP is an unspecified address
# - ip.is_reserved: True if the IP is a reserved address
if trusted_route:
# Indicates if the request came through our trusted proxies
# You can now use the IP address as needed, for example, attaching it to the request object.
# Consider caching the IP address for performance, as it doesn't change often.
# It's also advisable to have distinct session IDs for public and anonymous users to cache the IP address effectively.| Params ⇩ | ⇩ Description |
|---|---|
proxy_count ⇨ |
: Total number of expected proxies (pattern: client, proxy1, ..., proxy2): if proxy_count = 0 then client: if proxy_count = 1 then client, proxy1: if proxy_count = 2 then client, proxy1, proxy2 : if proxy_count = 3 then client, proxy1, proxy2 proxy3 |
proxy_list ⇨ |
: List of trusted proxies (ip header pattern: client, proxy1, ,..., proxyN): if proxy_list = ['10.1.'] then client, proxy1: if proxy_list = ['10.1', '10.2.3'] then client, proxy1 proxy2: if proxy_list = ['10.1', '10.2.', '10.3.4.4'] then client, proxy1, proxy2, proxy3 |
leftmost ⇨ |
: leftmost = True is default for de-facto standard.: leftmost = False for rare legacy networks that are configured with the rightmost pattern.: It converts client, proxy1 proxy2 to proxy2, proxy1, client |
| Output ⇩ | ⇩ Description |
|---|---|
ip ⇨ |
: Client IP address object of type IPv4Address() or IPv6Address() |
trusted_route ⇨ |
: If proxy proxy_count and/or proxy_list were provided and matched, True, else False |
The client IP address can be found in one or more request headers attributes. The lookup order is top to bottom and the default attributes are as follow.
# The default meta precedence order - you can be more specific as per your configuration
# It will start looking through the request headers from top to bottom to find the best match
# It will return the first qualified global (public) ip address it finds, else
# It will return the first qualified private ip address it finds, else
# It will return the first qualified loopback up address it finds, else it returns None
# Update as per your network topology, reduce the numbers and/or reorder the list
request_headers_precedence_order = (
"X_FORWARDED_FOR", # Load balancers or proxies such as AWS ELB (default client is `left-most` [`<client>, <proxy1>, <proxy2>`])
"HTTP_X_FORWARDED_FOR", # Similar to X_FORWARDED_TO
"HTTP_CLIENT_IP", # Standard headers used by providers such as Amazon EC2, Heroku etc.
"HTTP_X_REAL_IP", # Standard headers used by providers such as Amazon EC2, Heroku etc.
"HTTP_X_FORWARDED", # Squid and others
"HTTP_X_CLUSTER_CLIENT_IP", # Rackspace LB and Riverbed Stingray
"HTTP_FORWARDED_FOR", # RFC 7239
"HTTP_FORWARDED", # RFC 7239
"HTTP_VIA", # Squid and others
"X-CLIENT-IP", # Microsoft Azure
"X-REAL-IP", # NGINX
"X-CLUSTER-CLIENT-IP", # Rackspace Cloud Load Balancers
"X_FORWARDED", # Squid
"FORWARDED_FOR", # RFC 7239
"CF-CONNECTING-IP", # CloudFlare
"TRUE-CLIENT-IP", # CloudFlare Enterprise,
"FASTLY-CLIENT-IP", # Firebase, Fastly
"FORWARDED", # RFC 7239
"CLIENT-IP", # Akamai and Cloudflare: True-Client-IP and Fastly: Fastly-Client-IP
"REMOTE_ADDR", # Default
)You can customize the order by providing your own list during initialization when calling IpWare().
# specific meta key
ipware = IpWare(precedence=("X_FORWARDED_FOR"))
# multiple meta keys
ipware = IpWare(precedence=("X_FORWARDED_FOR", "HTTP_X_FORWARDED_FOR"))
# usage is just to pass in the http request headers
# Django (request.META)
ip, proxy_verified = ipware.get_client_ip(meta=request.META)
# Flask (request.environ)
ip, proxy_verified = ipware.get_client_ip(meta=request.environ)
# ... etc.If your node server is behind one or more known proxy server(s), you can filter out unwanted requests
by providing a trusted proxy list, or a known proxy count.
You can customize the proxy IP prefixes by providing your own list during initialization when calling IpWare(proxy_list).
You can pass your custom list on every call, when calling the proxy-aware api to fetch the ip.
# In the above scenario, use your load balancer IP address as a way to filter out unwanted requests.
ipware = IpWare(proxy_list=["198.84.193.157"])
# If you have multiple proxies, simply add them to the list
ipware = IpWare(proxy_list=["198.84.193.157", "198.84.193.158"])
# For proxy servers with fixed sub-domain and dynamic IP, use the following pattern.
ipware = IpWare(proxy_list=["177.139.", "177.140"])
# usage: non-strict mode (X-Forwarded-For: <fake>, <client>, <proxy1>, <proxy2>)
# The request went through our <proxy1> and <proxy2>, then our server
# We choose the <client> ip address to the left our <proxy1> and ignore other ips
ip, trusted_route = self.ipware.get_client_ip(meta=request.META)
# usage: strict mode (X-Forwarded-For: <client>, <proxy1>, <proxy2>)
# The request went through our <proxy1> and <proxy2>, then our server
# Total ip address are total trusted proxies + client ip
# We don't allow far-end proxies, or fake addresses (exact or None)
ip, trusted_route = self.ipware.get_client_ip(meta=request.META, strict=True)In the following example, your public load balancer (LB) can be seen as a trusted proxy.
`Real` Client <public> <-> <public> LB (Server) <private> <-----> <private> Django Server
^
|
`Fake` Client <private> <-> <private> LB (Server) <private> -+
If your python server is behind a known number of proxies, but you deploy on multiple providers and don't want to track proxy IPs, you still can filter out unwanted requests by providing proxy count.
You can customize the proxy count by providing your proxy_count during initialization when calling IpWare(proxy_count=2).
# In the above scenario, the total number of proxies can be used as a way to filter out unwanted requests.
import ipware
# enforce proxy count
ipware = IpWare(proxy_count=1)
# enforce proxy count and trusted proxies
ipware = IpWare(proxy_count=1, proxy_list=["198.84.193.157"])
# usage: non-strict mode (X-Forwarded-For: <fake>, <client>, <proxy1>, <proxy2>)
# total number of ip addresses are greater than the total count
ip, trusted_route = self.ipware.get_client_ip(meta=request.META)
# usage: strict mode (X-Forwarded-For: <client>, <proxy1>, <proxy2>)
# total number of ip addresses are exactly equal to client ip + proxy_count
ip, trusted_route = self.ipware.get_client_ip(meta=request.META, strict=True)In the following example, your public load balancer (LB) can be seen as the only proxy.
`Real` Client <public> <-> <public> LB (Server) <private> <---> <private> Node Server
^
|
`Fake` Client <private> ---+
# We make best attempt to return the first public IP address based on header precedence
# Then we fall back on private, followed by loopback
import ipware
# no proxy enforce in this example
ipware = IpWare()
ip, _ = ipware.get_client_ip(meta=request.META)
if ip.is_global:
print('Public IP')
else if ip.is_private:
print('Private IP')
else if ip.is_loopback:
print('Loopback IP')
else if ip.is_multicast:
print('Multicast IP')
else if ip.is_unspecified:
print('Unspecified IP')
else if ip.is_reserved:
print('Reserved IP')ipware is designed to handle various IP address formats efficiently:
- Ports Stripping: Automatically removes ports from IP addresses, ensuring only the IP is processed.
- IPv6 Unwrapping: Extracts and processes IPv4 addresses wrapped in IPv6 containers.
The de-facto standard for identifying the originating client IP address is to use the leftmost IP in the X-Forwarded-For header, following the pattern client, proxy1, proxy2. Here, the rightmost IP is considered the most trusted proxy.
In some rare scenarios, networks might be configured such that the rightmost IP address represents the originating client. In such cases, instantiate IpWare with the leftmost=False parameter:
To run the tests against the current environment:
./test.sh
Released under a (MIT) license.
X.Y.Z Version
`MAJOR` version -- making incompatible API changes
`MINOR` version -- adding functionality in a backwards-compatible manner
`PATCH` version -- making backwards-compatible bug fixes
Neekware Inc. (reach out at info@neekware.com)