Skip to content

O-X-L/haproxy-geoip

Repository files navigation

HAProxy - GeoIP Lookups

This is an example on how to use GeoIP lookups in combination with HAProxy.

Data linking requests to its origin country and ASN/ISP can be very useful when dealing with application-level attacks.

This allows you also to handle requests from specific countries and ASNs (p.e. datacenters/hosting providers) differently than others.

NOTE: This functionality is covered by the HAProxy Enterprise Maxmind-Module! Only use this implementation if you are limited to the community edition.


Topology

You can implement this in two ways:


Lookup via Backend

  1. Request hits HAProxy

  2. HAProxy calls LUA script to delegate GeoIP-database lookup

  3. LUA calls a minimal web-service on localhost that queries the GeoIP-database(s)

    You can either use a Go-based or Python3-based HTTP-Server as backend

Lookup via Library

  1. Request hits HAProxy

  2. HAProxy calls LUA script for querying the GeoIP-database(s)


GeoIP

You will have to download some MMDB GeoIP databases.

  • IPInfo: Information, CC4 License (allows for commercial usage - you need to add an attribution)

    Attribution: <p>IP address data powered by <a href="https://ipinfo.io">IPinfo</a></p>

  • MaxMind: Information, EULA (allows for limited commercial usage - you need to add an attribution)

    Attribution: This product includes GeoLite2 data created by MaxMind, available from <a href="https://www.maxmind.com">https://www.maxmind.com</a>.


Setup

  • Add the LUA script to your system
  • Install and set up the GeoIP lookup-backend of your choice

Config

  • Load the LUA module by adding lua-load /etc/haproxy/lua/geoip_lookup.lua in the global section

  • Execute the LUA script on HTTP requests:

    • In HTTP mode

      # country
      http-request lua.lookup_geoip_country
      # asn
      http-request lua.lookup_geoip_asn
      
    • In TCP mode

      # country
      tcp-request content lua.lookup_geoip_country
      # asn
      tcp-request content lua.lookup_geoip_asn
      
  • Log the data:

    • In HTTP mode

      http-request capture var(txn.geoip_asn) len 10
      http-request capture var(txn.geoip_country) len 2
      
    • In TCP mode

      tcp-request content capture var(txn.geoip_asn) len 10
      tcp-request content capture var(txn.geoip_country) len 2
      

You can also check out the configuration example: haproxy_example.cfg


Cache-Map

You will have to decide if you want to use HAProxy Maps to cache Lookup results.

This can speed up the lookup for IPs that have already connected to your server.

It will also use more memory.

See also: haproxy_example.cfg - test_country_cachemap

The speed-improvements as seen by running the test-script are: first: 0.03, second: 0.00

By utilizing HAProxy's ipmask (src,ipmask(24,48)) feature we are able to reduce the needed entries inside the map to the minimal subnets that are announced on public BGP.


Lookup

via Go-Backend

Download the binary for you system from the releases.

Read the documentation on how to use it.

You need to use the lua/geoip_lookup_w_backend.lua script.

It is recommended to start Go-Backend with -plain command line argument to get the variable in plain text format.


via Python-Backend

To query the MMDB databases, you will have to install the maxminddb python-module:

python3 -m pip install maxminddb

You will have to update the paths to your database-files in the backend/geoip_lookup_backend.py file!

You need to use the lua/geoip_lookup_w_backend.lua script.


via Library

WARNING: UNTESTED

To query the MMDB databases, you will have to install the resty-maxminddb LUA library and its dependencies.

You need to use the lua/geoip_lookup_w_lib.lua script.


Run

With Go-Backend

# start the web-service
./geoip-lookup &
# initialize the haproxy map(s)
touch /tmp/haproxy_geoip_country.map
# start haproxy
haproxy -W -f haproxy_example.cfg

With Python-Backend

# start the web-service
python3 backend/geoip_lookup.py &
# initialize the haproxy map(s)
touch /tmp/haproxy_geoip_country.map
# start haproxy
haproxy -W -f haproxy_example.cfg

With LUA-Library

# initialize the haproxy map(s)
touch /tmp/haproxy_geoip_country.map
# start haproxy
haproxy -W -f haproxy_example.cfg

Testing

You will have to copy some GeoIP databases to /tmp:

  • '/tmp/maxmind_country.mmdb'
  • '/tmp/maxmind_asn.mmdb'
  • '/tmp/ipinfo_country.mmdb'
  • '/tmp/ipinfo_asn.mmdb'

At least IPInfo OR MaxMind databases need to exist!

cd test
bash test.sh
>
> CLEANUP
>
> WARN: UNABLE TO TEST MaxMind databases as they are missing!
>
> STARTING HAPROXY
>
> TESTING with PYTHON-BACKEND
> LINKING IPInfo databases
> 127.0.0.1 - - [22/Nov/2023 21:21:00] "GET /?lookup=country&ip=1.1.1.1 HTTP/1.1" 200 -
> 127.0.0.1 - - [22/Nov/2023 21:21:00] "GET /?lookup=continent&ip=1.1.1.1 HTTP/1.1" 200 -
> 127.0.0.1 - - [22/Nov/2023 21:21:00] "GET /?lookup=asn&ip=1.1.1.1 HTTP/1.1" 200 -
> 127.0.0.1 - - [22/Nov/2023 21:21:00] "GET /?lookup=asname&ip=1.1.1.1 HTTP/1.1" 200 -
> REQUEST TIMES: 0.01 => 0.00 (cached)
>
> STOPPING HAPROXY
>
> FINISHED - exiting

Feel free to contribute more test-cases!