Initial commit for the rspamd spam/ham trainer

README.md

@@ -0,0 +1,151 @@
+# 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.
+- Extracts single mbox messages to temporary `.eml` files before training.
+- Provides `search`, `check`, `train spam` and `train ham` subcommands.
+
+## Install
+
+From the repository root:
+
+```bash
+sudo python3 -m pip install .
+```
+
+Then:
+
+```bash
+rspamd-mail-trainer --help
+```
+
+For a local editable install during development:
+
+```bash
+python3 -m pip install -e .
+```
+
+## Quick start
+
+Discover mailbox roots for the Unix user `johannes`:
+
+```bash
+sudo rspamd-mail-trainer roots --user johannes
+```
+
+Search suspicious messages from a sender:
+
+```bash
+sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test
+```
+
+Train matches as spam:
+
+```bash
+sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test
+```
+
+Train matches as ham:
+
+```bash
+sudo rspamd-mail-trainer train ham --user johannes --subject "Invoice"
+```
+
+Run Rspamd analysis without training:
+
+```bash
+sudo rspamd-mail-trainer check --user johannes --from no-reply@example.test
+```
+
+## Useful options
+
+Treat filter arguments as literal text instead of regex:
+
+```bash
+sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test --literal
+```
+
+Search subject:
+
+```bash
+sudo rspamd-mail-trainer search --user johannes --subject "Monthly report"
+```
+
+Search selected headers and text body:
+
+```bash
+sudo rspamd-mail-trainer search --user johannes --any "unsubscribe"
+```
+
+Restrict by date:
+
+```bash
+sudo rspamd-mail-trainer search --user johannes --from no-reply@example.test --after 2026-06-01 --before 2026-06-13
+```
+
+Dry-run training:
+
+```bash
+sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test --dry-run
+```
+
+Skip confirmation for a known-safe batch:
+
+```bash
+sudo rspamd-mail-trainer train spam --user johannes --from no-reply@example.test --yes
+```
+
+## Push to Gitea
+
+Create a new empty repository in Gitea, then run from this directory:
+
+```bash
+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:
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+Build a Python package:
+
+```bash
+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