Install

pip install flask-nobot

Quick start

from flask import Flask
from flask_nobot import NoBot

app = Flask(__name__)
nobot = NoBot(app, secret="change-me")

App factory

nobot = NoBot()

def create_app():
    app = Flask(__name__)
    app.config["SECRET_KEY"] = "change-me"
    nobot.init_app(app)
    return app

Secret resolution: constructor arg → NOBOT_SECRET → SECRET_KEY.

Config (app.config)

Change prefix via NoBot(prefix="SEC_").

Route decorators

from flask_nobot import skip, protect, challenge, block

@app.route("/health")
@skip
def health(): ...          # never challenged

@app.route("/login")
@protect
def login(): ...           # always evaluated

@app.route("/admin")
@challenge
def admin(): ...           # always challenged

@app.route("/api")
@block
def api(): ...             # failed challenge → 403, no retry

Rules

from flask_nobot import Rule

rules = [
    Rule("trusted-office", action="allow",
         remote_addresses=["10.0.0.0/8", "192.168.1.0/24"]),
    Rule("known-bad", action="deny",
         user_agent=r"(curl|wget|python-requests)"),
    Rule("suspicious-ua", action="weigh", weight=6,
         user_agent=r"(bot|crawler|spider|scrap)"),
    Rule("no-accept-lang", action="weigh", weight=4,
         headers={"Accept-Language": r"^$"}),
    Rule("admin-paths", action="challenge",
         path=r"^/admin", method="GET|POST"),
]

nobot = NoBot(app, secret="...", rules=rules, threshold=8)

Built-in preset

DEFAULT_RULES is applied when no rules argument is given. Pass rules=[] to disable, or extend it:

from flask_nobot import NoBot, DEFAULT_RULES, Rule

nobot = NoBot(app, secret="...")  # uses DEFAULT_RULES
nobot = NoBot(app, secret="...", rules=DEFAULT_RULES + [Rule(...)])

DEFAULT_RULES covers: Cloudflare-Worker deny, known-bad/vuln/WP scanners, dotfile/shell/traversal probes (deny); well-known, favicon, robots, sitemap, health, search engines, feed readers, monitoring, link previews, archive.org (allow); AI bots, headless browsers, aggressive scrapers, empty UA (challenge); curl/wget, missing Accept/Accept-Language, Connection:close (weigh).

Rule fields

Evaluation: first matching allow/deny/challenge wins → short-circuit. All matching weigh rules accumulate → if score ≥ threshold → challenge.

Challenge

Invisible, no user input. Serves a dark HTML page that runs JS signal collection:

• navigator.webdriver, plugin/language counts, hardware concurrency
• Headless/automation markers: _phantom, __nightmare, $cdc_*, webdriver attr
• Native Function.toString integrity
• WebGL vendor/renderer (blocks SwiftShader/llvmpipe)
• Notification-permission inconsistency trick
• Chrome object presence vs UA
• Timing floor/ceiling

Posts signals → server-side scoring → HMAC token cookie → redirect to original URL.

Verification token

base64(payload).base64(hmac_sha256(secret, payload)) where payload binds {timestamp, ip-hash, ua-hash, random}. IP/UA rebinding prevents cookie theft; TTL limits replay.

Security

• HttpOnly, Secure (when HTTPS), SameSite=Strict cookies
• Required Origin + X-Requested-With check on verify → CSRF defense
• CSP on challenge page (default-src 'none', no third-party), X-Frame-Options: DENY, Referrer-Policy: strict-origin-when-cross-origin, X-Content-Type-Options: nosniff
• Constant-time HMAC compare
• One-time nonce: each challenge nonce's random r is consumed server-side on first verify → replay blocked for nonce_ttl
• Crawler heuristic (is_crawler): regex over UA for bot signals, known tools, URLs-in-UA, absence of real browser tokens → adds crawler_weight to score
• Bogon detection (is_bogon): blocks RFC1918/loopback/link-local/reserved ranges when deny_bogons=True (enable behind trusted proxy)

Formatting

pip install black isort
isort . && black .
npx prtfm

License

Apache-2.0