liberatti/ipxa-resty repository overview

⁠🛡️ IPXA

IPXA is a high-performance, private-by-design platform for threat intelligence aggregation. It provides instant IP reputation queries, GeoIP data, and integration with 15+ Real-time Blackhole Lists (RBLs), all running entirely on your own infrastructure.

Instantly visualize the origin and risk score of any IP address with our premium web dashboard.

Multi-workspace environment for isolated security configurations.

⁠⚡ Performance & Privacy

• 🚀 Ultra-low Latency: Sub-5ms response times.
• 🔒 100% Private: Runs entirely on your infrastructure.
• 💰 Zero Cost: No per-request fees or subscription limits.
• 🔌 Air-gap Ready: Optimized for restricted and high-security environments.

⁠🔗 Server Integrations (Hooks)

IPXA provides native, high-performance middleware hooks for popular web servers, allowing you to block malicious traffic at the edge. These hooks support standardized JSON error responses with unique request_id tracking for enhanced observability.

⁠OpenResty / Nginx

Leverage the power of Lua in Nginx via OpenResty for ultra-low latency IP checking, complete with local caching.

Quick Setup:

1. Install the lua-resty-http package (via luarocks).
2. Copy the contents of hooks/openresty/lua/ to your OpenResty lualib path (e.g., /usr/local/openresty/lualib/ipxa/).
3. Update config.lua with your IPXA API URL and blocklist settings.
4. Configure your nginx.conf:

   http {
       # ...
       lua_package_path "/usr/local/openresty/lualib/ipxa/?.lua;;";
       lua_shared_dict ip_cache 10m; # Required for caching
   
       server {
           # ...
           error_page 403 /lua-error;
   
           location / {
               access_by_lua_file /usr/local/openresty/lualib/ipxa/ip_info_check.lua;
           }
   
           location = /lua-error {
               internal;
               content_by_lua_file /usr/local/openresty/lualib/ipxa/errors.lua;
           }
       }
   }
   

   Copy

(Check hooks/openresty/nginx.conf and hooks/openresty/Dockerfile for working examples).

⁠🛡️ Response Format

When a request is blocked, the hooks return a machine-readable JSON response instead of default HTML error pages. This ensures consistent error handling for both browsers and API clients.

Example Blocked Response:

{
  "error": "Forbidden",
  "status": 403,
  "request_id": "b10ed3a6f76ad62a75a956ce3e922336",
  "message": "ipxa [block/risk-score]: 172.20.0.1 risk_score=14"
}