rspamd-mail-trainer-gitea/README.md

rspamd-mail-trainer

Small defensive admin tool for Linux mail servers. It finds messages in Maildir or mbox mailboxes by sender, recipient, subject, date or selected text and then passes the matching messages to rspamc learn_spam or rspamc learn_ham.

Designed for setups such as Rocky Linux + Postfix/Dovecot + Rspamd.

Features

• Searches Maildir and mbox mailboxes.
• Tries to discover common mailbox roots automatically, including doveconf -n.
• Filters by From, To, Subject, header/body text and date range.
• Trains spam and ham via rspamc.
• Asks for confirmation before training.
• Refuses broad runs without any filter.
• Deduplicates matches by SHA-256.
• Logs scan progress and summaries to stderr while keeping search results on stdout.
• Extracts single mbox messages to temporary .eml files before training.
• Provides search, check, train spam and train ham subcommands.

Install

From the repository root:

sudo python3 -m pip install .

Then:

rspamd-mail-trainer --help

For a local editable install during development:

python3 -m pip install -e .

Quick start

Discover mailbox roots for the Unix user johannes:

sudo rspamd-mail-trainer roots --user johannes

Search suspicious messages from a sender:

sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test

Train matches as spam:

sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test

Train matches as ham:

sudo rspamd-mail-trainer train ham --user johannes --subject "Invoice"

Run Rspamd analysis without training:

sudo rspamd-mail-trainer check --user johannes --from no-reply@example.test

Useful options

Treat filter arguments as literal text instead of regex:

sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test --literal

Search subject:

sudo rspamd-mail-trainer search --user johannes --subject "Monthly report"

Search selected headers and text body:

sudo rspamd-mail-trainer search --user johannes --any "unsubscribe"

Restrict by date:

sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test --after 2026-06-01 --before 2026-06-13

Dry-run training:

sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test --dry-run

Skip confirmation for a known-safe batch:

sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test --yes

Reduce console progress output:

sudo rspamd-mail-trainer search --quiet --user johannes --from no-reply@example.test

Show additional diagnostic details such as duplicate suppression:

sudo rspamd-mail-trainer search --verbose --user johannes --from no-reply@example.test

Progress and warnings are written to stderr. Matching messages and rspamc results are written to stdout, so you can still redirect or pipe search output without mixing it with progress messages.

Push to Gitea

Create a new empty repository in Gitea, then run from this directory:

git init
git add .
git commit -m "Initial import of rspamd mail trainer"
git branch -M main
git remote add origin ssh://git@gitea.example.local/johannes/rspamd-mail-trainer.git
git push -u origin main

Replace the remote URL with your Gitea repository URL.

A Gitea Actions workflow is included at .gitea/workflows/ci.yml.

Development

Run tests without external dependencies:

make test
# or:
PYTHONPATH=src python3 -m unittest discover -s tests

Build a Python package:

python3 -m pip install build
python3 -m build

Safety notes

This tool reads local mailboxes and can train your Rspamd classifier. Start with search, check or --dry-run. Avoid broad patterns unless you inspected the matches. Train good messages as ham from time to time, not only spam.

License

MIT