⚠️ Status: untested. This extension is provided as-is and has not been tested in production. Please feel free to fork, modify, improve, and open pull requests.

Licensed under GNU GPLv3 (see LICENSE).

IP Block — Flask Extension

A Flask extension that registers a before_request hook checking each request against the ip-block.com service.

Targets: Flask 2.0+ (incl. 3.x), Python 3.8+.

Install

pip install flask-ip-block

Register

Direct:

from flask import Flask
from flask_ip_block import IpBlock

app = Flask(__name__)
app.config.update(
    IP_BLOCK_SITE_ID="your-site-id",
    IP_BLOCK_API_KEY="your-api-key",
)
IpBlock(app)

App-factory pattern:

from flask_ip_block import IpBlock

ip_block = IpBlock()

def create_app():
    app = Flask(__name__)
    app.config.from_object("config")
    ip_block.init_app(app)
    return app

Configure

All keys live in app.config (defaults shown):

IP_BLOCK_ENABLED = True
IP_BLOCK_SITE_ID = "your-site-id"
IP_BLOCK_API_KEY = "your-api-key"
IP_BLOCK_API_URL = "https://api.ip-block.com/v1/check"
IP_BLOCK_FAIL_OPEN = True          # allow on error/timeout
IP_BLOCK_CACHE_TTL = 300           # seconds (in-memory cache)
IP_BLOCK_TIMEOUT = 1.0             # seconds
IP_BLOCK_BEHIND_PROXY = False      # trust X-Forwarded-For / CF-Connecting-IP
IP_BLOCK_BLOCK_ACTION = "403"      # "403" or "redirect"
IP_BLOCK_REDIRECT_URL = "https://www.ip-block.com/blocked.php"
IP_BLOCK_BLOCK_MESSAGE = "Access denied."
IP_BLOCK_WHITELIST = ["127.0.0.1", "10.0.0.0/8"]

How it works

• Builds {api_key, site_id, ip, user_agent, referrer} and POSTs it with a 1 second timeout.
• Blocks only when the response is {"action":"block"}.
• Fails open on any error/timeout/non-2xx/missing action (IP_BLOCK_FAIL_OPEN=False to fail closed).
• Caches each decision for IP_BLOCK_CACHE_TTL seconds in-process, keyed by md5(ip|user_agent|referrer).
• Honours IP_BLOCK_WHITELIST (individual IPs and CIDR ranges).
• Reads the real client IP; with IP_BLOCK_BEHIND_PROXY=True it trusts CF-Connecting-IP then the first X-Forwarded-For hop.