flask_gatekeeper code documentation

Gatekeeper()

A simple banning & rate limiting extension for Flask.

class GateKeeper(app: Optional[flask.app.Flask] = None, ban_rule: Optional[dict] = None, rate_limit_rules: Optional[list] = None, ip_header: Optional[str] = None, excluded_methods: Optional[list] = None)

GateKeeper instance around a flask app.

Provides rate-limiting & ban functions.

Rate limiting is done automatically, but you have to specify when an IP should be reported, using .report() (usually in your login route when the creds are not valid)

ban_rule should be a dict {“count”:int,”window”:int,”duration”:int} where - count is the number of reports before actually banning the IP - window is the rolling time window to look for ban reports - duration is the duration of the ban in seconds.

rate_limit_rules should be a list [{“count”:int,”window”:int},..] where - count is the maximum number of requests - window is the rolling time window for the rate count.

As an example, ban_rule={“count”:3,”window”:60,”duration”:600}, rate_limit_rules=[{“count”:20,”window”:1},{“count”:100,”window”:10}] would: - ban any IP for 600s if it has been reported 3 times in the last 60s, - rate limit any IP if it has made more than 20 requests in the last 1s or more than 100 requests in a 10s window.

If you do not set ban_rule, no banning will be done. Same goes for the rate limiting.

Requests made during the rate limiting period or ban period are not counted.

You can delay the init by omitting app here and calling .init_app() later.

If you set ip_header but the header is not present in the request, it falls back to the client seen by flask (which might be the proxy’s IP if using one) string, and any request made by potentially different clients will be added to this.

Parameters

• app (flask.Flask, optional) – Flask app to wrap around. Defaults to None.

• ban_rule (dict, optional) – Global ban rule for the whole app. Defaults to None.

• rate_limit_rules (list, optional) – Global rate limit rules for the whole app. Defaults to None.

• ip_header (str, optional) – Header to check for the IP. useful with a proxy that will add a header with the ip of the actual client. Defaults to request.remote_addr.

• excluded_methods (str, optional) – Types of requests to ignore when counting requests. Can be GET, POST, HEAD, OPTIONS.. Defaults to None.

bypass(route)

do not apply rate-limiting to this route

init_app(app)

add our before request to flask now

report(ip: Optional[str] = None)

Report the client who made the request, increasing its tally towards being banned.

If no ip arg is provided, uses the ip_header arg provided to the GateKeeper instance

Parameters

ip (str, optional) – IP to ban. Defaults to None.

specific(rate_limit_rules: list = [], standalone: bool = False)

Route specific gatekeeper. Only for rate limiting purposes.

By defaults the specific rate_limit rule is set on top of the global instance rule. A use-case could be a global per-minute rule, and a per-second bursting rule here If you want to set a unique rate limite rule, set standalone to True.

You can supply a different ip_header, otherwise it will default to the instance configuration.

class IP(ban_count, rate_count)

IP record that keeps track of reports and requests made by that IP.

Parameters

• ban_count (int) – number of reports to keep

• rate_count (int) – number of requests to keep