Rqwatch Laravel Package

Product Decisions This Supports

• Build vs. buy for mail hygiene / quarantine UX. Rqwatch is a self-hosted quarantine and mail-log console for Rspamd-based mail stacks. This release makes the "self-host" case more defensible (fuzzy learning with weighted learns and fuzzy search, per-month reporting, IPv6 maps, notification skip map, per-release audit logging) while also raising the operating bar (five schema migrations, Apache hardening, Rspamd force_actions.conf, MAILER_* config correctness). Treat it as a candidate to replace commercial quarantine/reporting tooling only if you already run Rspamd and have ops capacity.
• Security posture and ship/no-ship decisions. v2.1.2 is effectively a security release: it closes IDOR on map entries (edit/delete/toggle by id alone), cross-user visibility of shared-address map entries, leakage of other users' envelope recipients (BCC), session persistence after alias/credential/admin-flag changes, unauthenticated read of /maps files under the shipped Apache config, login timing-based username enumeration, log-line injection, and CSRF-less logout. It also stops non-admins from seeing the absolute quarantine path, stores IP map entries in canonical form, throttles IPv6 logins per /64, and removes the login delay on unmatched routes/blocked IPs/empty credentials. If a security review is on the roadmap, this release is the forcing function to schedule it.
• Roadmap sequencing for end-user self-service. New release/notification behaviours (one-time links by default, 10-minute idle expiry, JS required to open a link, current-password required to change password) change the support burden and the help-desk script. The release form is now shared between the mail list page and the detail page, which removes a UX inconsistency but also means a release action is reachable from more places — confirm that matches your support policy. Decide whether to adopt the new defaults or set $notification_links_one_time = false before announcing self-service to users.
• Feature prioritisation with real demand signals. Fuzzy learning (admin-only, learn/unlearn spam/not-spam with per-learn weights, add weight without unlearning, duplicate-learn warnings, fuzzy view searchable by QID / learned-by / server / hash prefix, local-fuzzy-hit markers, cron:fuzzy_cleanup retention default 90 days), clickable per-month quarantine chart, virus notification skip map (case-insensitive globs), cron:notifications -B to notify on blacklisted mail at any score, and IPv6 IP maps are the headline capabilities to slot into a roadmap or explicitly defer.
• Capacity and change-window planning as a product constraint. The ever_stored index migration scales with mail_logs (~2s on ~860k rows) and blocks writes cluster-wide under Galera. With $import_spool (default) imports are spooled and replayed by cron:import_spool, which bounds the user-visible impact — but the release requires a quiet window, which is a scheduling decision, not just an ops one.
• Supportability decisions — including a new config-drift failure mode. Password-less release is now refused with a message while MAILER_FROM is empty, and MAILER_DSN/MAILER_FROM are validated on the node that actually sends the release. That turns a .env drift into a user-facing "I can't release my mail" ticket — decide whether that gets a monitoring check. Alongside it: DB_WEB_MAX_STATEMENT_TIME (default 30s) caps runaway searches, DNS failures are cached 60s instead of a negative 3600s TTL, searches land on a plain GET results page (Back/refresh/paging work), and malformed Rspamd symbols are repaired and logged instead of failing the import. Together these reduce "the app is slow/broken" tickets — a direct support-cost lever.
• Auditability / compliance. Every release is now logged to file and syslog on the web node with user and client context. If you have an audit or forensics requirement, this is a reason to adopt; if you don't, it is a log-retention and log-shipping decision to make explicitly rather than inherit.
• Adoption gate for legacy installs. Upgrades are supported only from 1.8.4 and 2.x. Older deployments require a two-hop upgrade (1.8.x code + 1.8.x DB migrations first, then 2.x). This is a scoping input for any migration plan.

When to Consider This Package

Consider it when:

• You run Rspamd with Postfix/Exim and want quarantine, mail-log search, map management, and user self-service release in one self-hosted console.
• You have a PHP-capable ops team comfortable running db:migrate, editing .env, Apache Location blocks, and Rspamd local.d configs.
• You need per-user/per-alias quarantine views with admin override, and you want fuzzy learning (with weighted learns and hash/QID search), virus-notification suppression, and release audit logging without buying a separate product.
• You can guarantee MAILER_DSN/MAILER_FROM are set on every node that can send a release — otherwise self-service release breaks for users on that node.
• You are already on 1.8.4 or 2.x, or can fund the staged 1.8.x → 2.x upgrade.
• You can absorb the behaviour changes: users must enter their current password to change it; pre-2.1.2 notification links stop working; opening links requires JavaScript; personal map entries are capped at 1000 per user per map unless $USER_MAP_MAX_ENTRIES = 0; a whitelisted mail is only shown green when the whitelist actually won (not on a forced reject/discard).
• You can tolerate no vendor SLA — this is a community/self-supported project; you are the support tier.

Look elsewhere when:

• You want a managed/SaaS email security or quarantine product with an SLA — the upgrade, migration, and Apache hardening work here all lands on you.
• Your MTA is not Rspamd (the feature set — fuzzy learning, symbols, force_actions.conf — is Rspamd-shaped).
• You run Galera and cannot get a quiet write window for the ever_stored index build, or you have a very large mail_logs table and no spool/replay tolerance.
• You need magic-link, no-login release flows with long-lived links — this release deliberately tightens that (one-time by default, session-bound handle, JS required, 10-minute idle expiry).
• Your security review forbids shipping an app that needs an Apache <Location /maps> block restricted to specific Rspamd source IPs — i.e. you cannot guarantee the network control the fix depends on.
• You cannot guarantee mailer configuration on sending nodes, or your release path relies on password-less notification links surviving beyond a session.
• You need API-stable integrations: the importer now accepts only alphanumeric QIDs, API clients refuse redirects, and CHANGE_ME_ placeholder passwords hard-fail mail import and remote get/release.
• You have a custom map named rqwatch_virus_no_notify already — the migration will fail until you repoint $notification_skip_virus_map; messy for you, and a signal the schema is opinionated.

Diligence items before committing: confirm whether this is consumable as a Composer/Laravel-integrated package or is a standalone PHP application (./bin/cli.php suggests the latter) — that changes the integration cost materially; confirm upgrade support matrix and maintenance cadence; confirm Galera/topology assumptions; confirm where release audit logs land and how long they are kept.

How to Pitch It (Stakeholders)

To executives: This is a self-hosted quarantine and mail-visibility console for our Rspamd-based mail stack — an alternative to licensing commercial quarantine tooling. The new 2.1.2 release is, above all, a security release: it fixes a set of access-control and data-exposure bugs (users could act on other users' map entries, BCC recipients were visible to non-admins, whitelist/personal map files were world-readable under the shipped web config, sessions survived permission and credential changes), and it hides internal quarantine paths from non-admins. It also adds per-release audit logging and admin-side fuzzy learning. We should treat it as a prioritised security upgrade, not a routine version bump. Cost is an engineering change window plus a short coordinated config change across the web tier, Apache and Rspamd — not a new licence line.

To engineering: v2.1.2 is a breaking security release with a narrow upgrade path.

• Path: supported only from 1.8.4 or 2.x. Older installs need 1.8.4 code + 1.8.x DB migrations first, then 2.x.
• Schema: db:migrate applies five migrations (Mail Log Fuzzy, fuzzy hit/updated_at, ever_stored column + index, Users session_version, Virus notification skip map). All fast except the ever_stored index, which scales with mail_logs (~2s at ~860k rows) and blocks writes cluster-wide under Galera — schedule a quiet window. $import_spool (default) spools failed imports for cron:import_spool replay.
• Config gates: grep -nE '^(RSPAMD|MAIL)_API_PASS=CHANGE_ME_' .env — the importer and mail APIs now refuse placeholders; change RSPAMD_API_PASS in .env and metadata_exporter.conf together. Also verify MAILER_DSN and MAILER_FROM on each web node: password-less release is refused with a message while MAILER_FROM is empty, and the check runs on the node that sends the release.
• Infra: add the <Location /maps> block from contrib/apache-rqwatch.conf and restrict it to the Rspamd servers that fetch maps; add contrib/rspamd/local.d/force_actions.conf and adjust the antivirus symbol expression (it now discards viruses even from whitelisted senders).
• Collision risk: if a custom map rqwatch_virus_no_notify already exists, the skip-map migration fails — set $notification_skip_virus_map and re-run.
• Behaviour changes to communicate: prior notification links are dead (users log in instead); links need JS, are one-time by default, and expire after 10 idle minutes ($notification_links_one_time, $notification_links_idle_minutes); current password required to change password and it ends other sessions; personal map entries capped at 1000/user/map; every release is logged to file and syslog; whitelisted mail is only green when the whitelist actually won.
• Also new: admin-only Rspamd fuzzy learning with per-learn weights and add-weight-without-unlearn, fuzzy view searchable by QID / learned-by / server / hash prefix, local-fuzzy-hit markers, cron:fuzzy_cleanup (90-day default), cron:notifications -B for blacklisted mail at any score, IPv6 in IP maps (stored canonically), clickable per-month quarantine chart, release form on the mail list page shared with the detail page, DB statement cap (30s), saner DNS failure caching, importer self-repair of malformed Rspamd symbols, IPv6 /64-aware login throttling, and search pages that survive Back/refresh.

Recommendation: schedule the upgrade as a security change with a named quiet window, land the .env/MAILER_*/Apache/Rspamd changes in the same change set (the map-file exposure fix is incomplete without the Apache block), add a check that MAILER_FROM is set on every sending node, and brief the help desk on the notification-link and password-change changes before rollout. If we cannot get the write window or the Apache restriction, that is a reason to defer the upgrade and document the residual risk — not to run it half-applied.