bongo/docs/antispam.md

Spam and malware scanning

Bongo uses two independent scanners. bongoantispam sends mail to a standard SpamAssassin spamd service for content classification. bongoavirus uses ClamAV for malware detection. Neither service replaces the other.

The antispam agent is fail-open: a connection failure, malformed response or configured size limit leaves the original message available for normal delivery and records the problem in the log. It never sends a rejection or bounce to the apparent sender. A successful SpamAssassin PROCESS response replaces the queued copy with the processed message containing the normal X-Spam-* headers and marks the envelope as already checked.

The default antispam JSON configuration is:

{
  "version": 1,
  "enabled": false,
  "timeout": 15,
  "maximum_message_size": 52428800,
  "maximum_response_size": 53477376,
  "hosts": ["127.0.0.1"]
}

hosts accepts the existing host:port:weight syntax and can list several spamd servers. Port 783 is used when no port is specified. The response limit must be at least as large as the input limit because SpamAssassin adds headers. Both scanner agents are disabled in the distribution defaults. bongo-setup probes each matching local service with a protocol PING. It can explicitly enable an unreachable endpoint without touching the scanner package, or—with a second opt-in—safely edit a detected local scanner configuration, enable and restart its service, and require the expected PONG. The local editor uses loopback-only listeners, preserves unrelated options, writes an adjacent .bongo-setup.bak, and rolls files and service state back on failure. On systemd installations where clamd receives sockets from clamav-daemon.socket, setup adds a drop-in for the loopback TCP socket while preserving the distribution's Unix socket. If SpamAssassin is installed without an initial rule set, setup shows this in the preview, downloads the official Apache update key over HTTPS, verifies its complete fingerprint 5E541DC959CB8BAC7C78DFDC4056A61A5244EC45, imports it into the sa-update keyring, and runs the distribution's sa-update before touching scanner configuration. The downloaded channel is signature-checked by SpamAssassin and must pass spamassassin --lint; otherwise setup stops before editing files or services. Rule data installed successfully by sa-update is retained like an antivirus signature update even if a later, unrelated setup step is rolled back.

The scanner wizard also offers two independent third-party channels:

• the signed KAM channel kam.sa-channels.mcgrail.com; setup downloads its public key over HTTPS and checks the complete fingerprint 21D97142272C9066FCAA792B4A156DA524C063D8 before importing it;
• spamassassin.heinlein-support.de, which is unsigned and therefore remains an explicit, warned opt-in using sa-update --nogpg.

Third-party channels are disabled by default. Setup never enables sa-update --allowplugins for downloaded rules. Every selected update must pass spamassassin --lint before spamd is restarted. Selection is persisted in /etc/bongo/spamassassin.d/channels, and setup enables the bongo-spamassassin-update.timer. The timer runs hourly with a small random delay. It invokes KAM with its pinned signing key and Heinlein in a separate, explicit --nogpg process, so the unsigned-channel exception can never disable verification for KAM. If rules changed and passed lint, the active spamassassin.service or spamd.service is reloaded or restarted. If an official or KAM signing key changes, setup reports both fingerprints and stops before editing or restarting the scanner. Existing rules and the running service remain active until an administrator verifies the upstream rotation and installs a Bongo update containing the new trust anchor. The difference is also recorded below the Bongo state directory and displayed on every bongo-admin config TUI start until a matching trusted key is imported. bongo-admin config can configure remote endpoints explicitly; setup never attempts to edit a remote scanner.

Run bongo-setup scanners to repeat only the local scanner editor after a package update or service change. This maintenance mode does not rerun initial Bongo setup. After each selected endpoint returns the expected PONG, it sets the loopback endpoint in Bongo's antispam or antivirus document, enables bongoantispam or bongoavirus in the manager document, synchronizes the files with the Store, and reloads the manager. Scanner files, service state, and Bongo documents are rolled back together if activation fails. An edited but unverified endpoint remains disabled in Bongo.

Spam folder rules should match SpamAssassin's X-Spam-Status header. A high score quarantine is deliberately not implemented through the historical global quarantine queue: quarantine state belongs to the recipient and must be visible and releasable through that user's task list. Until that per-user path is active, mail is tagged and can be filed by Sieve without being destroyed.

The Bongo systemd unit only orders Bongo after common ClamAV and SpamAssassin unit names when those services are present. It does not pull either scanner in, so remote scanners and installations without one of the optional services remain supported. The opt-in setup editor understands systemd and OpenRC; it does not make scanner packages unconditional Bongo dependencies.

The enabled scanner-health worker runs every six hours. It checks the age and availability of ClamAV daily signatures and the availability of compiled SpamAssassin rule files. It also runs Bongo's extra-channel helper in --checkonly mode, where sa-update compares the DNS serial numbers without installing data. SpamAssassin rules deliberately have no age limit because a valid channel may remain unchanged for months. Missing data, ClamAV data older than the default 48 hours, an available extra-channel update, or a failed channel check creates a deduplicated administrator task. Healthy data and current serial numbers complete the matching task. The Worker never installs rules or invokes a service manager. The hourly root-owned systemd oneshot is the only Bongo component that updates the opted-in KAM and Heinlein channels. The distribution remains responsible for its official Apache SpamAssassin channel and FreshClam.