feat: Add ClamAV container with automatic config wiring for PHP 8.4 and 8.5

Author: Chris Snyder

.github/workflows/build-clamav.yml

@@ -0,0 +1,23 @@
+name: Build ClamAV image
+
+on:
+  release:
+    types:
+      - created
+  pull_request:
+    branches:
+      - master
+    paths:
+      - clamav/**
+      - .github/workflows/build-image.yml
+      - .github/workflows/build-clamav.yml
+
+jobs:
+  build-clamav-image:
+    name: Build ClamAV image
+    uses: ./.github/workflows/build-image.yml
+    with:
+      image: clamav
+      context: ./clamav
+      push: ${{ github.event_name == 'release' }}
+    secrets: inherit

.github/workflows/scan-images.yml

@@ -16,6 +16,7 @@ jobs:
       fail-fast: true
       matrix:
         include:
+          - image: clamav
           - image: mssql2017
           - image: mssql2019
           - image: mssql2022

README.md

@@ -23,6 +23,7 @@ Although this project started as a development environment for Totara Learn it c
  * A [PHPUnit](https://phpunit.de/) and [Behat](http://behat.org/en/latest/) setup to run tests (including [Selenium](https://www.seleniumhq.org/))
  * A [MailDev](https://github.com/maildev/maildev?tab=readme-ov-file#maildev) instance to view sent emails
  * [Redis](https://redis.io/) for caching and/or session handling
+ * [ClamAV](https://www.clamav.net/) for antivirus scanning, wired up automatically on PHP 8.4 and 8.5
  * [XHProf](https://github.com/tideways/php-xhprof-extension) for profiling
  * [XDebug](https://xdebug.org/) installed, ready for debugging with your favorite IDE
  * [Excimer](https://www.mediawiki.org/wiki/Excimer) installed, for discovering performance problems

bin/tdocker

@@ -11,6 +11,7 @@ source "$project_path/tools/check_for_update.sh"
 files=(
     "docker-compose.yml"
     "compose/apache.yml"
+    "compose/clamav.yml"
     "compose/mariadb.yml"
     "compose/mssql.yml"
     "compose/mysql.yml"

clamav/Dockerfile

@@ -0,0 +1,23 @@
+FROM alpine:3.21
+
+ARG TIME_ZONE=Pacific/Auckland
+
+RUN apk add --no-cache \
+        clamav \
+        clamav-daemon \
+        clamav-libunrar \
+        freshclam \
+        tzdata \
+    && ln -fs /usr/share/zoneinfo/${TIME_ZONE} /etc/localtime \
+    && mkdir -p /run/clamav /var/lib/clamav
+
+COPY config/clamd.conf /etc/clamav/clamd.conf
+COPY config/freshclam.conf /etc/clamav/freshclam.conf
+COPY entrypoint.sh /entrypoint.sh
+
+RUN chmod +x /entrypoint.sh
+
+# clamd listens on a unix socket shared with the PHP containers. TCP is for ad-hoc debugging.
+EXPOSE 3310
+
+ENTRYPOINT ["/entrypoint.sh"]

clamav/config/clamd.conf

@@ -0,0 +1,26 @@
+# docker-dev ClamAV daemon configuration.
+
+# No LogFile - clamav refuses /dev/stdout as a log target ("Symbolic link loop"), and with
+# Foreground set it logs to stdout regardless, which is what docker wants.
+LogTime yes
+Foreground yes
+PidFile /run/clamav/clamd.pid
+DatabaseDirectory /var/lib/clamav
+
+# Unix socket, shared with the PHP containers via the clamav-socket volume.
+# The PHP containers run clamdscan with --fdpass, which passes the file descriptor over this
+# socket, so clamd never needs to see the scanned file's path or have permission to read it.
+# Mode 0666 so that www-data in the PHP containers can connect.
+LocalSocket /run/clamav/clamd.sock
+LocalSocketMode 0666
+
+# TCP is exposed for ad-hoc debugging only - the healthcheck uses the unix socket above. Totara
+# cannot use it either: antivirus_clamav's scanner::is_configured() returns false for the
+# tcpsocket running method, so a TCP-configured plugin is silently never invoked.
+TCPSocket 3310
+TCPAddr 0.0.0.0
+
+MaxThreads 4
+
+# Must stay above upload_max_filesize in php/config/php.ini.
+StreamMaxLength 100M

clamav/config/freshclam.conf

@@ -0,0 +1,9 @@
+# docker-dev freshclam configuration.
+# The entrypoint runs freshclam once when the signature database is empty. The database lives in
+# the clamav-data volume, so this only downloads on first start.
+
+DatabaseDirectory /var/lib/clamav
+# No UpdateLogFile, for the same reason as clamd.conf - the entrypoint passes --stdout instead.
+LogTime yes
+DatabaseMirror database.clamav.net
+Checks 1

clamav/entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+set -e
+
+# The clamav-socket and clamav-data volumes are owned by root when first created, but clamd and
+# freshclam both drop privileges to the clamav user, so hand them over.
+chown -R clamav:clamav /run/clamav /var/lib/clamav
+
+# Only download signatures when we don't already have them - the clamav-data volume persists them
+# between runs, so this normally happens once per machine.
+if ! ls /var/lib/clamav/*.cvd /var/lib/clamav/*.cld >/dev/null 2>&1; then
+    echo "clamav: no signature database found, running freshclam (this takes a few minutes)"
+    freshclam --stdout || echo "clamav: freshclam failed, clamd will not start until signatures are available" >&2
+fi
+
+exec clamd

compose/build.yml

@@ -1,4 +1,10 @@
 services:
+  clamav:
+    build:
+      context: ./clamav
+      args:
+        TIME_ZONE: ${TIME_ZONE}
+
   mssql2017:
     build:
       context: ./mssql

compose/clamav.yml

@@ -0,0 +1,33 @@
+x-healthcheck-template: &clamav-healthcheck
+  healthcheck:
+    # clamd answers PING with PONG once it has finished loading its signatures. clamdscan reads
+    # LocalSocket from clamd.conf, so this also proves the unix socket the PHP containers use is
+    # actually accepting connections.
+    test: ["CMD", "clamdscan", "--ping", "1"]
+    interval: 10s
+    timeout: 5s
+    retries: 5
+    # Loading the signature database takes around a minute, and the first ever start also has to
+    # download it.
+    start_period: 300s
+
+services:
+
+  clamav:
+    <<: *clamav-healthcheck
+    image: ghcr.io/totara/docker-dev-clamav
+    container_name: totara_clamav
+    restart: ${RESTART_POLICY:-no}
+    environment:
+      TZ: ${TIME_ZONE}
+    volumes:
+      # Shared with the PHP 8.4/8.5 containers so clamdscan can reach clamd.
+      - clamav-socket:/run/clamav
+      # Persists the signature database so freshclam only downloads it on first start.
+      - clamav-data:/var/lib/clamav
+    networks:
+      - totara
+
+volumes:
+  clamav-socket:
+  clamav-data: