{"id":50479491,"url":"https://github.com/liberatti/ipxa","last_synced_at":"2026-06-01T16:30:52.231Z","repository":{"id":353233033,"uuid":"1216206264","full_name":"liberatti/ipxa","owner":"liberatti","description":"IP Reputation and Network Intelligence Monitoring","archived":false,"fork":false,"pushed_at":"2026-05-25T14:38:08.000Z","size":2798,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T15:28:26.390Z","etag":null,"topics":["api-rest","ip-information","network-security","security","security-feeds"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/liberatti/ipxa","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liberatti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T17:14:33.000Z","updated_at":"2026-05-25T14:20:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/liberatti/ipxa","commit_stats":null,"previous_names":["liberatti/ipxa"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/liberatti/ipxa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liberatti%2Fipxa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liberatti%2Fipxa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liberatti%2Fipxa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liberatti%2Fipxa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liberatti","download_url":"https://codeload.github.com/liberatti/ipxa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liberatti%2Fipxa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33784625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-rest","ip-information","network-security","security","security-feeds"],"created_at":"2026-06-01T16:30:51.360Z","updated_at":"2026-06-01T16:30:52.226Z","avatar_url":"https://github.com/liberatti.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ IPXA\n\u003e **IP Reputation and Network Intelligence Monitoring**\n\n**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.\n\n[![Docker Image](https://img.shields.io/badge/docker-ready-blue?logo=docker\u0026logoColor=white)](https://hub.docker.com/r/liberatti/ipxa)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)\n\n![Dashboard](docs/screenshot-01.png)\n*Instantly visualize the origin and risk score of any IP address with our premium web dashboard.*\n\n![IpInfo](docs/screenshot-02.png)\n*Multi-workspace environment for isolated security configurations.*\n\n---\n\n## ⚡ Performance \u0026 Privacy\n\n- 🚀 **Ultra-low Latency**: Sub-5ms response times.\n- 🔒 **100% Private**: Runs entirely on your infrastructure.\n- 💰 **Zero Cost**: No per-request fees or subscription limits.\n- 🔌 **Air-gap Ready**: Optimized for restricted and high-security environments.\n\n---\n\n\n## 🎨 Admin Interface\nThe administrative interface is accessible at the `/admin` context. It features a secure login system and a **one-click logout** to ensure session security in shared environments.\n\nYou can configure the access credentials using the following environment variables:\n\n- **ADMIN_EMAIL**: Administrator email (Default: `admin@local`)\n- **ADMIN_PASSWORD**: Administrator password (Default: `admin`)\n\n![Admin Dashboard](docs/screenshot-03.png)\n*Manage your feeds, workspaces, and monitoring data through a premium, dark-mode administrative interface with secure session management.*\n\n---\n\n\n## 🚀 Key Features\n\n*   🌍 **Intelligent GeoIP**: Local integration with MaxMind and ip2asn for lightning-fast lookups.\n*   🚫 **RBL Orchestration**: Dynamic management of 15+ threat feed sources (Reputation \u0026 Bypass).\n*   ⚡ **Multiple API Flavors**: Specialized endpoints for exhaustive data, security checks, or high-speed header-based responses.\n*   🏢 **Multi-Workspace**: Isolate configurations and API keys across different environments or clients.\n*   🎨 **Admin Dashboard**: High-contrast, dark-mode interface for real-time monitoring and data management.\n\n---\n\n## 🛠️ Quick Deploy\n\nIPXA is distributed as a lightweight Docker image.\n\n### Docker Compose\n\n```yaml\nservices:\n  ipxa:\n    image: liberatti/ipxa:latest\n    container_name: ipxa\n#    environment:\n#      - IBLOCKLIST_USERNAME=\n#      - IBLOCKLIST_PASSWORD=\n#      - MAXMIND_ACCOUNT_ID=\n#      - MAXMIND_LICENSE_KEY=\n    volumes:\n      - ipxa_data:/data\n    ports:\n      - \"5000:5000\"\n    restart: always\n    deploy:\n      resources:\n        limits:\n          memory: 256M\n\nvolumes:\n  ipxa_data:\n```\n---\n\n## 🔗 Server Integrations (Hooks)\n\nIPXA 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.\n\n### Apache (`mod_lua`)\n\nIntegrate IPXA directly into your Apache configuration using `mod_lua` to evaluate IPs on the fly.\n\n**Quick Setup:**\n1. Install `mod_lua` and `lua-socket` (e.g., `yum install httpd mod_lua lua-socket`).\n2. Copy `hooks/httpd/lua/*.lua` to your Apache lua directory (e.g., `/etc/httpd/lua/`).\n3. Update `/etc/httpd/lua/config.lua` with your IPXA API URL and settings.\n4. Hook into your `VirtualHost`:\n   ```apacheconf\n   \u003cVirtualHost *:80\u003e\n       ServerName example.com\n       DocumentRoot /var/www/html\n       \n       # IPXA Access Control\n       LuaHookAccessChecker /etc/httpd/lua/ipxa.lua ip_info_check\n       \n       # IPXA JSON Error Handler\n       Alias /errors /etc/httpd/lua/errors.lua\n       \u003cLocation /errors\u003e\n           SetHandler lua-script\n       \u003c/Location\u003e\n       ErrorDocument 403 /errors\n   \u003c/VirtualHost\u003e\n   ```\n\n*(See `hooks/httpd/README.md` for full details).*\n\n### OpenResty / Nginx\n\nLeverage the power of Lua in Nginx via OpenResty for ultra-low latency IP checking, complete with local caching.\n\n**Quick Setup:**\n1. Install the `lua-resty-http` package (via `luarocks`).\n2. Copy the contents of `hooks/openresty/lua/` to your OpenResty `lualib` path (e.g., `/usr/local/openresty/lualib/ipxa/`).\n3. Update `config.lua` with your IPXA API URL and blocklist settings.\n4. Configure your `nginx.conf`:\n   ```nginx\n   http {\n       # ...\n       lua_package_path \"/usr/local/openresty/lualib/ipxa/?.lua;;\";\n       lua_shared_dict ip_cache 10m; # Required for caching\n\n       server {\n           # ...\n           error_page 403 /lua-error;\n\n           location / {\n               access_by_lua_file /usr/local/openresty/lualib/ipxa/ip_info_check.lua;\n           }\n\n           location = /lua-error {\n               internal;\n               content_by_lua_file /usr/local/openresty/lualib/ipxa/errors.lua;\n           }\n       }\n   }\n   ```\n\n*(Check `hooks/openresty/nginx.conf` and `hooks/openresty/Dockerfile` for working examples).*\n\n### 🛡️ Response Format\n\nWhen 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.\n\n**Example Blocked Response:**\n```json\n{\n  \"error\": \"Forbidden\",\n  \"status\": 403,\n  \"request_id\": \"b10ed3a6f76ad62a75a956ce3e922336\",\n  \"message\": \"ipxa [block/risk-score]: 172.20.0.1 risk_score=14\"\n}\n```\n\n---\n\n## 📡 API Reference\n\n### 1. Full IP Info\n`GET /api/ip/info/{address}`\nReturns comprehensive GeoIP, ASN, and reputation data.\n\n**Example Response:**\n```json\n{\n  \"ip\": {\n    \"address\": \"14.152.94.1\",\n    \"broadcast\": \"14.152.95.255\",\n    \"network\": \"14.152.80.0\",\n    \"prefix\": 20,\n    \"version\": 4\n  },\n  \"location\": {\n    \"continent\": \"Asia\",\n    \"country_code\": \"CN\",\n    \"country_name\": \"China\"\n  },\n  \"organization\": {\n    \"asn_description\": \"\",\n    \"asn_name\": \"CT-DONGGUAN-IDC CHINANET Guangdong province network\",\n    \"asn_number\": 134763\n  },\n  \"security\": {\n    \"reasons\": [\n      \"rbl:firehol_level1\"\n    ],\n    \"risk_score\": 0\n  }\n}\n```\n\n### 2. Security Check\n`GET /api/ip/check/{address}`\nSimplified response focused on reputation and risk assessment.\n\n**Example Response:**\n```json\n{\n  \"ip\": \"14.152.94.1\",\n  \"risk_score\": 0,\n  \"reasons\": [\"rbl:firehol_level1\"]\n}\n```\n\n### 3. Quick Decision (Headless)\n`GET /api/ip/quick/{address}`\nOptimized for firewalls and middleware. Returns risk score in body and `x-risk-score` header.\n\n**Example Response:**\n```json\n{\n  \"risk_score\": 9\n}\n```\n\n---\n\n## 🛠️ Testing \u0026 Development\n\nIPXA includes an `api.rest` file for rapid API testing.\n\n1.  **VS Code**: Install the [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) extension.\n2.  **Run**: Open `api.rest` and click `Send Request` above any endpoint.\n3.  **Explore**: Use these examples as a baseline for your own integrations.\n\n---\n\n## 🔌 RBL Feed Management\n\nWhile advanced users can still add JSON files in `config/`, IPXA now features a complete **Admin Panel** to manage feeds dynamically through the UI.\n\n| Field | Description |\n| :--- | :--- |\n| `name` | Human-friendly identifier for the feed |\n| `slug` | Unique internal identifier |\n| `type` | `reputation` (for blocking) or `bypass` (for allowlisting) |\n| `source` | Public URL for download (CIDR or IP list) |\n| `format` | `cdir_text` (plain text) or `cdir_gz` (compressed) |\n| `risk_score` | Weight of this feed in the final decision (0-10) |\n\n---\n\n## 📦 Integrated Feeds\n\nIncludes a pre-configured library of industry-standard feeds:\n\n- **FireHOL Level 1-4**: Highly curated aggregation.\n- **Cisco Talos \u0026 DShield**: Global threat intelligence.\n- **Abuse.ch Feodo**: Botnet C2 tracking.\n- **Spamhaus DROP**: SBL Advisory blocks.\n- **Emerging Threats**: Known compromised hosts.\n- **Blocklist.de \u0026 GreenSnow**: SSH/Mail brute force.\n\n---\n\n## ⚖️ Limitation of Liability\n\n**Disclaimer of Warranty**: This software is provided \"AS IS\", without warranty of any kind, express or implied. The author(s) and contributor(s) shall not be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.\n\n**Use at Your Own Risk**: You are solely responsible for any decisions made or actions taken based on the data provided by IPXA. The software involves security-related functions; its misconfiguration or misuse could lead to service disruption or security gaps.\n\n---\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliberatti%2Fipxa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliberatti%2Fipxa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliberatti%2Fipxa/lists"}