Malware Scanning

PentestPad can scan every uploaded file for malware before it is stored or served — project attachments, finding and editor images, report template and PDF replacements, and whitelabel logos. Scanning is handled by a ClamAV clamd sidecar container that the application streams uploads to.

On PentestPad Cloud this is always on. On self-hosted instances it is opt-in: you add the ClamAV container and set a single environment variable.

Fail-open by design

Scanning never blocks legitimate work because of an outage. If the scanner is unreachable or a file is too large to scan in the request, the upload is accepted and flagged rather than rejected, and large files are settled by a background scan. Only files clamd actively reports as infected are blocked.

1. Add the ClamAV container

Add the clamav service to your docker-compose.yml, alongside the existing PentestPad services:

services:
  # ... existing app, postgres, redis services ...

  clamav:
    image: clamav/clamav:1.4-debian
    container_name: clamav
    restart: unless-stopped
    volumes:
      # Persist downloaded signatures so the slow first pull only happens once.
      - clamav_db:/var/lib/clamav
      - ./clamd.conf:/etc/clamav/clamd.conf:ro
    healthcheck:
      # Image-provided helper: PINGs clamd, exits non-zero until ready.
      test: ["CMD", "clamdcheck.sh"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s
    networks:
      - app_network

volumes:
  clamav_db:

Then declare the dependency on the app service so it starts after ClamAV, and point it at the sidecar:

services:
  app:
    depends_on:
      clamav:
        condition: service_started
    environment:
      CLAMAV_HOST: clamav

clamd listens on TCP port 3310 and is reached only over the internal app_network — there is no need to publish a host port.

First boot takes a couple of minutes

On its first start the container downloads the full virus-signature database before clamd accepts connections. The healthcheck keeps it in a starting state until it is ready (about two minutes). The clamav_db volume persists the signatures so this only happens once.

Tip

An official pentestpad-docker setup bundling this container is coming shortly. Until then, add the service manually as shown above.

2. Provide clamd.conf

The mounted clamd.conf raises clamd’s size limits so large attachments (up to ~700 MB) can be scanned. The stock image defaults to only 25 MB per stream and 400 MB per file, which would silently leave large uploads unscanned — so this file is required.

Create clamd.conf next to your docker-compose.yml:

LogFile /var/log/clamav/clamd.log
LogTime yes

# Bind all interfaces (dual-stack) so the image's clamdcheck.sh healthcheck,
# which PINGs IPv6 localhost, keeps working. Do not pin TCPAddr.
LocalSocket /tmp/clamd.sock
TCPSocket 3310
User clamav

# Raise the limits well above the ~700 MB attachment cap. The application
# enforces a matching ceiling via CLAMAV_MAX_STREAM_BYTES.
StreamMaxLength 768M
MaxScanSize 768M
MaxFileSize 768M

3. Enable scanning

Set the master switch in your .env and restart the app:

SCANNING_ENABLED=true

When scanning is disabled (the self-hosted default), the application behaves exactly as before — no scan records are created and no jobs are queued.

The remaining variables have sensible defaults that match the container above; override them only for a non-standard setup (for example an external clamd):

Environment variable	Default	Purpose
SCANNING_ENABLED	false (self-hosted)	Master on/off switch.
CLAMAV_HOST	clamav	Hostname of the clamd sidecar.
CLAMAV_PORT	3310	clamd TCP port.
CLAMAV_TIMEOUT	120	Socket timeout, in seconds, for a single scan.
CLAMAV_MAX_STREAM_BYTES	805306368 (768 MB)	Largest file streamed to clamd; bigger files are recorded as unscannable. Must stay ≤ clamd’s StreamMaxLength.
CLAMAV_SYNC_MAX_BYTES	134217728 (128 MB)	Largest file scanned in-request at upload time. Bigger files are accepted and scanned in the background.
CLAMAV_STALE_AFTER_MINUTES	60	How long a scan may sit pending before the recovery sweep re-runs or escalates it.

Keep the two ceilings aligned

CLAMAV_MAX_STREAM_BYTES must stay less than or equal to the StreamMaxLength in clamd.conf (768 MB above). If the application ceiling is higher, clamd will abort streams that exceed its own limit.

4. Make sure the queue worker is running

Files larger than CLAMAV_SYNC_MAX_BYTES (128 MB by default), plus any uploads accepted while the scanner was briefly unreachable, are scanned in the background on a dedicated scans queue. The standard PentestPad image runs Laravel Horizon, which already drains this queue — just make sure Horizon is running.

Self-healing

An hourly maintenance task re-runs or settles any scan that was left pending — for example because the queue worker or the ClamAV container was down when a large file was uploaded. Nothing is ever silently treated as scanned-and-clean.

5. Verify

1. Start the stack: docker compose up.
2. Confirm the sidecar is healthy: docker compose ps should show clamav as healthy (allow ~2 minutes on first boot).
3. Upload a normal file in a project — it should attach without any warning badge.
4. To safely confirm detection works, upload an EICAR test file — a harmless standard antivirus test string. The upload should be blocked by malware scanning.

Once verified, see Attachment Scanning for what your team sees day to day — the scan badges, the blocked-upload flow, and downloading flagged files safely.