Repository navigation
Service: 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.
- 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
FreshclamCheckstimes per day. - Serve as a malware check in an upload pipeline, a content processing job or a security check.
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}| 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.
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
|
- 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;
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.