ClamAV Antivirus API Server — API Endpoints (Google Cloud)

All API routes are served under the /api/v1 prefix. After starting the instance, you can access the API Server using its IP address and port 8080. For instance, if the IP address is 172.31.39.37, the base URL is http://172.31.39.37:8080/api/v1.

Breaking change: In earlier versions the routes were unversioned (/api/clamav/scan/gcs/object and /api/clamav/scan/file). They now live under /api/v1, the GCS scan route is /api/v1/gcp/scan, and the response body now includes a provider field and echoes the request identifiers. See the Release Notes.

Scan Google Cloud Storage objects

Scan an object stored in a GCS bucket by making a request to http://172.31.39.37:8080/api/v1/gcp/scan.

curl -d '{"bucket": "elm-bucket-virus-scan", "object": "test/virus_test.txt", "stream": true}' -H 'Content-Type: application/json' http://172.31.39.37:8080/api/v1/gcp/scan

Parameter Meanings

The following parameters are used in the request:

bucket

This parameter specifies the name of the GCS bucket from which the file should be retrieved.

object

This parameter represents the object within the GCS bucket. It identifies the specific file that should be downloaded and scanned.

stream

This parameter controls how the server handles the file download process. When set to false, the server downloads the entire file into memory before saving it to disk. Conversely, when set to true, the server streams the file directly to disk in smaller chunks. Streaming is particularly beneficial when dealing with large files, as it reduces the memory required for the download process. This approach enables more efficient resource utilization and allows the server to handle files that might otherwise exceed available memory capacity.

Response

A json format string is returned. The response now includes the provider and echoes the bucket and object that were scanned. The possible return codes are 0, 1, 2, and 99.

Clean

{"provider":"gcp","code":0,"message":"OK","bucket":"elm-bucket-virus-scan","object":"test/virus_test.txt"}

Infected

For example, when the Eicar signature is identified, the response would be

{"provider":"gcp","code":1,"message":"Eicar-Signature FOUND","bucket":"elm-bucket-virus-scan","object":"test/virus_test.txt"}

Scan Errors

For example, when having a file access error, the response would be

{"provider":"gcp","code":2,"message":"Can't access file /tmp/test/file","bucket":"elm-bucket-virus-scan","object":"test/virus_test.txt"}

Other Errors

For example, when the service account is not properly configured, the response would be

{"provider":"gcp","code":99,"message":"no credentials in the property bag","bucket":"elm-bucket-virus-scan","object":"test/virus_test.txt"}

A scan that finds malware still returns HTTP 200; the result is carried in the body. A file larger than the API request limit (MAX_SCAN_SIZE_MB, 500MB by default) returns HTTP 413 and is never scanned. A smaller file that still exceeds ClamAV's own engine limits is instead flagged at HTTP 200 with code: 1 and a Heuristics.Limits.Exceeded message — see Scan Size Limits. When the GCP provider is not initialized the server returns HTTP 503.

Scan an uploaded file

Scan file bytes directly by streaming the raw file as the request body to http://172.31.39.37:8080/api/v1/scan/upload. This does not require staging the file in a GCS bucket.

curl --data-binary @/tmp/test.pdf -H 'Content-Type: application/octet-stream' http://172.31.39.37:8080/api/v1/scan/upload

The response includes the number of bytes scanned:

{"code":0,"message":"OK","size_bytes":12345}

The body is streamed to disk as it arrives and the size limit is enforced incrementally, so an oversize upload is rejected with HTTP 413 without being buffered in full.

Scan local files

Scanning a server-local file path is available only when the server is started with the LOCAL_SCAN_DIR environment variable set to an allowlisted directory. Requests for paths outside that directory are rejected with HTTP 403.

curl -d '{"file": "/data/scan/test.txt"}' -H 'Content-Type: application/json' http://172.31.39.37:8080/api/v1/scan

Health and liveness

Two probes are provided for load balancers and orchestrators:

• GET http://172.31.39.37:8080/api/v1/health — readiness. Scans a probe file with clamd and returns 200 only when the scanner is working and reports the probe clean; otherwise 503.
• GET http://172.31.39.37:8080/api/v1/livez — liveness. Returns 200 immediately without touching clamd.