Stalwart + ClamAV

This guide adds virus scanning to a Stalwart mail server with the ClamAV image. Infected messages are rejected while the sender is still connected, so they never reach a mailbox.

How it fits together

The ClamAV image runs three services:

Stalwart hands each incoming message to clamav-milter at the SMTP DATA stage. The milter scans it through clamd and answers:

• Clean: the message is accepted, with X-Virus-Scanned and X-Virus-Status: Clean headers added.
• Infected: Stalwart rejects the message with 503 5.5.3 Message rejected., and ClamAV logs Message from <...> to <...> infected by <signature>. Attachments are scanned too, not just the message body.
• Scanner unavailable: Stalwart defers the message with 451 4.3.5 Unable to accept message at this time., so the sending server retries later instead of the mail arriving unscanned.

Requirements

• Memory: clamd keeps every signature in RAM, about 1.4 GB, and briefly holds a second copy while it reloads after an update. Plan for a few GB.
• Container DNS: Stalwart reaches ClamAV by its container name. On FreeBSD that needs container name resolution; see Networking. Without it, use the ClamAV container's IP address instead of clamav below.

1. Run both containers

Save as compose.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

name: mail

services:
  clamav:
    image: @REGISTRY@/clamav:latest
    container_name: clamav
    restart: always
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
    volumes:
      - @CONTAINER_CONFIG_ROOT@/clamav:/config
    # No published ports: only Stalwart talks to ClamAV, over the compose
    # network. clamd and the milter have no authentication.

  stalwart:
    image: @REGISTRY@/stalwart:latest
    container_name: stalwart
    restart: always
    environment:
      - TZ=UTC
      - ADMIN_SECRET=changeme
      - ENABLE_V4PROXY=true
    volumes:
      - @CONTAINER_CONFIG_ROOT@/stalwart:/config
    ports:
      - "25:25"
      - "465:465"
      - "587:587"
      - "993:993"
      - "443:443"
      - "8080:8080"
    depends_on:
      - clamav

1
2

mkdir -p /path/to/containers/clamav /path/to/containers/stalwart
podman-compose up -d

2. Wait for the first signature download

On its first start, freshclam downloads the full signature database (a few hundred MB) into /path/to/containers/clamav/db. clamd and the milter wait for it:

1

podman logs -f clamav

It's ready once you see [clamav-milter] starting on port 7357. Later restarts reuse the downloaded database and come up in seconds.

3. Make Stalwart listen on IPv4

In the web admin, edit each listener and add the IPv4 address next to the IPv6 one (for SMTP: 0.0.0.0:25 alongside [::]:25). Or do it with stalwart-cli, for example for SMTP:

1
2

echo '{"@type":"upsert","object":"NetworkListener","matchOn":["name"],"value":{"smtp":{"name":"smtp","bind":{"[::]:25":true,"0.0.0.0:25":true},"protocol":"smtp","tlsImplicit":false}}}' |
  stalwart-cli --url http://your-host:8080 --user admin@your-domain apply --stdin

Restart the Stalwart container afterwards so the new binds take effect.

4. Add the milter in Stalwart

If Stalwart is new, finish its setup wizard first (see the Stalwart image page). Then in the web admin, open Settings › MTA › Filters › Milters and add a milter:

Leave the timeouts and protocol version at their defaults, and save.

Only the data stage matters for virus scanning: that's the stage where Stalwart passes the message body to the milter.

The same milter with stalwart-cli:

1
2

echo '{"@type":"create","object":"MtaMilter","value":{"clamav":{"hostname":"clamav","port":7357,"stages":{"data":true},"tempFailOnError":true,"useTls":false}}}' |
  stalwart-cli --url http://your-host:8080 --user admin@your-domain apply --stdin

5. Test it

Send a message containing the EICAR test string from another host. It's a harmless file every antivirus flags. With swaks:

1
2

swaks --to you@your-domain --server mail.your-domain \
  --body 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*'

The server should answer 503 5.5.3 Message rejected., and ClamAV should log the hit:

1

podman logs clamav | grep infected

A normal message goes through and arrives with an X-Virus-Status: Clean header.

Tuning

The milter's settings are in /path/to/containers/clamav/clamav-milter.conf, written on first start. Edit it and restart the container.

The full list of options is in /usr/local/etc/clamav-milter.conf.sample inside the container.