Bahriya Tersane

Documentation / clamav

ClamAV Helm Chart

Deploys ClamAV as a shared in-cluster malware scanner, with ClamAV’s own Debian-based image (clamav/clamav-debian), for amd64 and arm64. clamd serves scans, and freshclam keeps the signatures current and tells clamd to reload them.

Applications send files to clamd for scanning over its TCP protocol (INSTREAM, port 3310) before storing them.

Design

A single replica with a persistent volume at /var/lib/clamav caching the signature database across restarts. The Pod has three parts, sharing that volume and /run/clamav:

  • an init container downloads the database when the volume holds none, because clamd does not start without one;
  • a clamd container serves scans on port 3310;
  • a freshclam container checks for new signatures freshclam.checksPerDay times a day (12 by default) and tells clamd to reload through the shared socket. If it stops, the kubelet restarts that container alone.

The signature database is held in memory, and twice for a moment while a new one is loaded, so budget about 1.5 to 2.5 GiB for clamd. Scale out only if scan throughput ever demands it.

The image is pinned by digest. Upstream rebuilds under the same tag, so a tag alone would run whatever was copied last. If you set image.repository or image.tag to an image of your own, also set image.digest to its digest, or to "" to pull by tag.

Requirements and outbound traffic

The chart needs Kubernetes 1.20 or later: its container uses a startup probe, generally available from that version, and otherwise only stable APIs.

freshclam downloads the signature database from ClamAV’s servers (database.clamav.net), so the Pod needs outbound HTTPS to them: on first start, when the volume holds no signatures, and afterwards for each update.

Where the Pod has no direct route to ClamAV’s servers, set freshclam’s own directives in freshclam.extraConfig. They apply to the first download and to the updates. Through a proxy:

freshclam:
  extraConfig: |
    HTTPProxyServer proxy.example.com
    HTTPProxyPort 3128

Or from a mirror of your own:

freshclam:
  extraConfig: |
    PrivateMirror clamav-mirror.example.com

clamd.extraConfig adds clamd.conf directives in the same way. The image’s CLAMD_CONF_* and FRESHCLAM_CONF_* environment variables do not apply: they are read by the image’s own entrypoint, which this chart does not use.

ClamAV 1.4

ClamAV 1.4 is ClamAV’s long-term support line. It receives security fixes until 15 August 2027, and may download signatures until 15 August 2028.

Scan size and disk

clamd.streamMaxLength (100M, ClamAV’s own default) is the largest file clamd accepts over INSTREAM. A larger stream is refused. An application’s own size limit must not exceed it.

clamd holds each streamed file in /tmp while it scans it, with up to 10 scans at once, plus the files it unpacks from archives. /tmp is on disk, not in memory, so these files do not count against the memory limit, and is limited to clamd.tmpSize (2Gi). Keep clamd.tmpSize at least ten times clamd.streamMaxLength, with room to unpack, and keep the container’s ephemeral-storage limit (3Gi) above it.

Connecting an application

Applications reach clamd through the chart’s Service:

<release>-clamav.<namespace>.svc.cluster.local:3310

The Pods carry the label app.kubernetes.io/name: clamav, for a NetworkPolicy that admits an application to them.

Pod Security and quotas

The chart meets the Kubernetes restricted Pod Security Standard. Every container runs as the image’s clamav user (uid and gid 1000) with runAsNonRoot, drops every capability and adds none, disallows privilege escalation, uses the RuntimeDefault seccomp profile and a read-only root filesystem. fsGroup: 1000 makes the signature volume writable.

Every container, the init container included, declares CPU, memory and ephemeral-storage requests and limits, so the Pod is admitted in a namespace whose ResourceQuota requires them.

Upgrading from 1.0

Version 1.1 changes the image from clamav/clamav (Alpine) to clamav/clamav-debian, in which the clamav user is uid 1000 rather than 100, and runs it as that user rather than as root.

  • If you override securityContext, podSecurityContext, runAsUser or fsGroup, update them for uid and gid 1000, or remove your overrides.
  • The existing signature volume is taken over through fsGroup. With persistence.existingClaim, or storage that ignores fsGroup, make its files writable by uid or gid 1000 before upgrading.
  • Settings made through CLAMD_CONF_* or FRESHCLAM_CONF_* in extraEnv move to clamd.extraConfig and freshclam.extraConfig.

Key values

Key Default Description
replicaCount 1 Number of clamd pods
image.repository / .tag / .digest 1x.ax/tersane/core/clamav/clamav-debian / the ClamAV release named in the chart’s appVersion / pinned ClamAV’s own Debian-based image, amd64 and arm64
imagePullSecrets [{name: 1x-ax}] Pull secret for 1x.ax, which must exist in the release’s namespace
service.port 3310 clamd TCP listener
persistence.enabled true Cache the signature DB on a PVC
persistence.size 2Gi Signature DB volume size
clamd.streamMaxLength 100M Largest file accepted over INSTREAM
clamd.tmpSize 2Gi clamd’s /tmp, on disk
clamd.extraConfig "" Further clamd.conf lines
freshclam.checksPerDay 12 Signature checks a day
freshclam.extraConfig "" Further freshclam.conf lines, such as a proxy or a private mirror
resources 250m, 1536Mi, 512Mi requested; 2 CPUs, 2560Mi, 3Gi limits clamd’s CPU, memory and ephemeral storage
freshclam.resources 50m, 256Mi, 64Mi requested; 1 CPU, 1536Mi, 1Gi limits freshclam’s, and the first download’s

Render / lint

helm lint charts/clamav
./charts/clamav/tests/render-defaults.sh