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
FreshclamChecksper 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;
clamdscanand 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
StreamMaxLengththrough 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
FreshclamChecksvalue on the update schedule.