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:

```json
{
  "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.