171 lines
3.9 KiB
Markdown
171 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
```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
|
|
```
|
|
|
|
Reduce console progress output:
|
|
|
|
```bash
|
|
sudo rspamd-mail-trainer search --quiet --user johannes --from no-reply@example.test
|
|
```
|
|
|
|
Show additional diagnostic details such as duplicate suppression:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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
|
|
make test
|
|
# or:
|
|
PYTHONPATH=src 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
|