Getting Started

ClamAV is an open source antivirus engine, licensed under GPL-2.0 and maintained by Cisco Talos. The service on Eyevinn Open Source Cloud runs ClamAV 1.5.4 and exposes an HTTP API on the instance URL, so you can scan files for malware by uploading them with any HTTP client.

Prerequisites

  • An Eyevinn Open Source Cloud account
  • A personal access token for your OSC account, available as $OSC_TOKEN
  • curl (see Usage Example)

Step 1: Create the ClamAV instance

Navigate to the ClamAV service, go to the "My clamav" tab and click "Create clamav". Fill in:

Option Description Example
Name Instance name myscanner

The other options are optional, see Configuration. No service secrets are needed. The instance gets a 2 GB persistent volume for the virus signature database and 1536 MiB of memory.

Step 2: Wait for the instance to become ready

On first start the instance downloads the full signature database (about 3.6 million signatures, roughly 20-40 seconds) and then loads it, which takes about 15 more seconds. The instance URL is:

https://<tenant>-<name>.cisco-talos-clamav.auto.prod-se.osaas.io

The root path is public and reports the scanner state:

curl https://<tenant>-<name>.cisco-talos-clamav.auto.prod-se.osaas.io/

While loading it returns "clamd":"starting". When ready it returns:

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

Step 3: Get a service access token

All paths other than GET / require authentication. Exchange your personal access 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. Use the token value as $SAT below, and request a new one when it expires.

Usage Example

Set your placeholders:

export INSTANCE_URL=https://<tenant>-<name>.cisco-talos-clamav.auto.prod-se.osaas.io
export SAT=<service-access-token>

Check the engine and signature database version:

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 standard EICAR antivirus test string. It is harmless and every antivirus engine reports it as a test virus:

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}

To scan several files in one request, use 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

Configuration

Option Required Description
Name Yes Instance name
StreamMaxLength No Maximum size of a scanned file. Accepts values like 100M, 2G or plain bytes. Default 100M. Also sets the HTTP upload limit
FreshclamChecks No Number of signature update checks per day. Default 1

Limitations

  • ClamAV is signature based. A "clean" result is not a guarantee that a file is safe, and a scan is only as good as the current signature database. Signatures update automatically, as often as FreshclamChecks per day.
  • Uploads are limited by StreamMaxLength (default 100M). Files are streamed to the scanner, and larger bodies are rejected with 413.
  • The first start downloads the full signature set, so a new instance needs about a minute before it reports "clamd":"up".
  • 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. Changing StreamMaxLength through the instance configuration restarts the instance and applies the new limit.
  • Not tested: large files close to the size limit, concurrency or throughput, and the effect of a changed FreshclamChecks value on the update schedule.

Resources