Skip to content

Service: ClamAV

Jonas Birmé edited this page Nov 21, 2026 · 2 revisions

ClamAV

ClamAV (serviceId cisco-talos-clamav) is an open source antivirus engine maintained by Cisco Talos. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance running ClamAV 1.5.4 that exposes an HTTP API for scanning files. License: GPL-2.0.

What it can do

  • Scan files for trojans, viruses, malware and other malicious threats by uploading them over HTTP.
  • Scan several files in one multipart request.
  • Report the engine and signature database version.
  • Update its signature database automatically, up to FreshclamChecks times per day.
  • Serve as a malware check in an upload pipeline, a content processing job or a security check.

Creating an instance

Create the instance with create-service-instance using serviceId: "cisco-talos-clamav". The name must be alphanumeric and at most 20 characters. ClamAV has no dependencies on other OSC services and needs no secrets. The instance gets a 2 GB persistent volume for the signature database and 1536 MiB of memory.

{ "name": "myscanner" }

On first start the instance downloads the full signature database (about 3.6 million signatures, roughly 20-40 seconds) and then loads it (about 15 more seconds), so allow about a minute. Use wait-for-service-ready, then describe-service-instance for the URL, which has the form https://<tenant>-<name>.cisco-talos-clamav.auto.prod-se.osaas.io. The root path is public and reports scanner state; while loading it returns "clamd":"starting", when ready:

{"service":"clamav","clamd":"up","maxBytes":104857600}

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only, at most 20 characters.
StreamMaxLength No string Maximum size of a file that can be scanned, for example 100M, 2G or a plain number of bytes. Sets the clamd StreamMaxLength option (CLAMD_CONF_StreamMaxLength) and the upload limit of the HTTP scan API; larger files are rejected. Default 100M.
FreshclamChecks No string Number of times per day the signature database is checked for updates, for example 24 for hourly. Becomes the freshclam --checks value (FRESHCLAM_CHECKS). Default 1.

Changing StreamMaxLength through the instance configuration restarts the instance and applies the new limit.

Using the instance

All paths other than GET / require authentication. Exchange your OSC personal access token ($OSC_TOKEN) for a service access token (SAT):

curl -X POST https://token.svc.prod.osaas.io/servicetoken \
  -H "x-pat-jwt: Bearer $OSC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serviceId":"cisco-talos-clamav"}'

The response is JSON with token and expiry; request a new one when it expires.

export INSTANCE_URL=https://<tenant>-<name>.cisco-talos-clamav.auto.prod-se.osaas.io
export SAT=<service-access-token>
curl -H "Authorization: Bearer $SAT" $INSTANCE_URL/version
{"version":"ClamAV 1.5.4/<db version>/<date>"}

Scan a file by sending it as the raw request body:

curl -X POST -H "Authorization: Bearer $SAT" \
  --data-binary @myfile.bin $INSTANCE_URL/scan

A clean file returns {"status":"clean","bytes":1234}. To see a detection, scan the harmless standard EICAR test string:

printf '%s' 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' > eicar.txt
curl -X POST -H "Authorization: Bearer $SAT" \
  --data-binary @eicar.txt $INSTANCE_URL/scan
{"status":"infected","signature":"Eicar-Test-Signature","bytes":68}

Scan several files in one request with multipart/form-data; every file part is scanned:

curl -X POST -H "Authorization: Bearer $SAT" \
  -F "file1=@myfile.bin" -F "file2=@eicar.txt" $INSTANCE_URL/scan
{"results":[{"filename":"myfile.bin","status":"clean","bytes":1234},{"filename":"eicar.txt","status":"infected","signature":"Eicar-Test-Signature","bytes":68}]}

Error responses:

Status Meaning
413 Body larger than the size limit, {"error":"file exceeds N bytes"}
503 The scanner is not ready yet, wait and retry
405 Method other than POST used on /scan

Limitations

  • ClamAV is signature based. A "clean" result is not a guarantee that a file is safe.
  • Uploads are limited by StreamMaxLength (default 100M). Larger bodies are rejected with 413.
  • The raw clamd TCP port (3310) is not reachable from outside OSC. Use the HTTP API; clamdscan and INSTREAM over the network are not supported.
  • The signature database is stored on the instance volume, so a restart does not download it again.

Resources

Clone this wiki locally