Metadata-Version: 2.5
Name: flaskbb-plugin-stopforumspam
Version: 1.0.0
Summary: StopForumSpam integration for FlaskBB - block known spammers at registration and report new ones
Project-URL: Homepage, https://github.com/flaskbb/flaskbb-plugin-stopforumspam
Project-URL: Repository, https://github.com/flaskbb/flaskbb-plugin-stopforumspam
Project-URL: Issues, https://github.com/flaskbb/flaskbb-plugin-stopforumspam/issues
Project-URL: Changelog, https://github.com/flaskbb/flaskbb-plugin-stopforumspam/blob/master/CHANGELOG.md
Author-email: Peter Justin <peter@peterjustin.com>
Maintainer-email: Peter Justin <peter@peterjustin.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: flaskbb,plugin,registration,spam,stopforumspam
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: flaskbb>=3.0.0
Requires-Dist: requests>=2.34.2
Description-Content-Type: text/markdown

StopForumSpam
=============

[StopForumSpam](https://www.stopforumspam.com) integration for FlaskBB.
Checks new registrations against StopForumSpam's database of known
spammer usernames, email addresses and IP addresses, and lets moderators
report new spammers back to it.

See [flaskbb/flaskbb#391](https://github.com/flaskbb/flaskbb/issues/391).


Installation
------------

Install *flaskbb-plugin-stopforumspam* with
``pip install flaskbb-plugin-stopforumspam``

For local development against a FlaskBB checkout, from FlaskBB's root
folder:

```
uv pip install -e ../flaskbb-plugin-stopforumspam
```

Then install the plugin from the admin panel and run the migrations
(``flaskbb db upgrade``).


Usage
-----

Every registration is looked up on StopForumSpam. If the username, email
address or IP address is listed with at least the configured confidence
score, the registration is rejected with a generic message and the
attempt is logged. Admins can review and clear that log from the admin
panel's "StopForumSpam" page.

Users who can ban a member also get a "Report spammer" button on that
member's profile. It submits the username, email address and the IP the
member registered from to StopForumSpam, optionally with evidence, and
can ban the member at the same time. Reporting needs an
[API key](https://www.stopforumspam.com/keys). FlaskBB doesn't store
registration IPs itself, so only members who registered while this
plugin was installed can be reported.

If FlaskBB runs behind a reverse proxy, configure it to pass on the
client's address (for example with Werkzeug's ``ProxyFix``), otherwise
every registration is checked against the proxy's IP. Private and
loopback addresses are never sent.


Settings
--------

*StopForumSpam Settings*, under the admin panel's Plugin Settings:

* **Check registrations** - master toggle for the lookup (default: on).
* **Check username / email address / IP address** - which fields are
  looked up (default: all).
* **Minimum confidence (%)** - reject a registration if any checked field
  is listed with at least this confidence (default: 50, 0 rejects any
  listing).
* **Send email addresses hashed** - send an MD5 hash instead of the plain
  address. StopForumSpam skips its domain blacklists and address
  normalisation for hashed lookups (default: off).
* **Reject registrations when StopForumSpam is unreachable** - fail
  closed instead of open (default: off).
* **Request timeout (seconds)** - default: 5.
* **API key** - only needed for reporting spammers.

The blueprint is mounted at ``/stopforumspam``; override it with
``PLUGIN_STOPFORUMSPAM_URL_PREFIX`` in your FlaskBB config.


License
-------
This project is licensed under the terms of the [BSD License](/LICENSE).
