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. 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.