Threatless

Scanning

How Threatless scans files and URLs with ClamAV.

Threatless scans bytes through ClamAV using the INSTREAM protocol. Nothing is written to disk for the scan itself: the stream is forwarded to clamd, the verdict is parsed, and the bytes are dropped.

What you can scan

Files

Remote URLs

You must send either a file or a URL on the public API — not both empty. The dashboard scanner only accepts a file.

Limits

LimitValue
Maximum size10 MB
URL protocolshttp, https
URL connect timeout10 seconds
URL read timeout30 seconds
EngineClamAV (clamd)

The result

Every successful scan returns:

filename
string
Original file name, or the last path segment of the URL.
extension
string
File extension without the dot. Empty when the name has none.
sizeInBytes
number
Uploaded size, or bytes actually streamed from a URL.
scanDurationMillis
number
Time spent talking to ClamAV.
infected
boolean
true when ClamAV reports FOUND.
virusName
string | null
Signature name when infected, otherwise null.
Some clients also read isInfected. The API serializes the flag as infected. Accept both if you generate types from Lombok beans.

What is stored

File contents are not stored. Threatless keeps scan metadata on your account so the dashboard can show history and charts:

  • filename
  • duration
  • infected flag and virus name
  • HTTP status recorded as 200 for completed scans
  • environment label (PRODUCTION today)

That history powers Dashboard analytics. It is not a copy of the file.

Engine updates

The API container runs freshclam daily at midnight to refresh virus signatures. Self-hosted instances inherit that schedule from the bundled ClamAV image.

Testing detection

Do not commit malware. Use the official EICAR test file as described in Test with EICAR. A positive result is still HTTP 200 with infected: true (typically virusName Win.Test.EICAR_HDB-1).

Next

Previous

API Keys

Create, use, and revoke API keys for the Scan API.

Next