This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

iya-sts can send files to an antivirus product before it keeps them. It speaks ICAP (RFC 3507), so any product with an ICAP service works. Scanning is off by default.

What is scanned

  • profile photos a person uploads
  • logos an administrator uploads
  • profile photos copied from a federation partner
  • risk datasets uploaded on the console or through the API

A file is refused if the service flags it, and also if the service cannot answer, because a scan that was asked for must not be a way around itself. A dataset that a scheduled job downloads, or reads from risk.datasetsDirectory, is not scanned.

Turn it on

In the admin console, open Server Settings > Malware scanning, set the service address, turn on Scan files for malware, and use Test the service. The test sends the EICAR test file, which is harmless, and passes only if the service flags it. A service that is running but whose antivirus engine failed to load can report every file as clean, so answering is not enough.

The same settings are available as environment variables:

Setting Environment variable Default
malwareScan.enabled STS_MALWARE_SCAN_ENABLED false
malwareScan.url STS_MALWARE_SCAN_URL (empty)
malwareScan.timeoutMs STS_MALWARE_SCAN_TIMEOUT_MS 30000
malwareScan.caFile STS_MALWARE_SCAN_CA_FILE (empty)
malwareScan.allowCleartext STS_MALWARE_SCAN_ALLOW_CLEARTEXT false

The address is icap://host:1344/service, or icaps://host:11344/service for TLS. The service name is whatever your product calls its scanning service.

Using TLS

Product mode refuses a plain icap:// address, so files reach the scanner encrypted. To allow it on a network you trust, turn on malwareScan.allowCleartext.

The service’s certificate is checked like any other outbound connection. If it comes from a private CA, or is self-signed, name that CA or certificate in malwareScan.caFile, a PEM file that must be under security.fileRoots.

Paranoid PKI mode, on by default in product mode, applies to this connection too. Instead of malwareScan.caFile, you can trust a private CA or an accepted self-signed certificate once for the realm in its signer truststore, at /admin/pki/trust.

If Test the service fails, the message says whether the certificate or connection was refused and why, or that the service cannot be reached.

Using ClamAV

ClamAV does not speak ICAP itself, so docker-compose.yml has two services, both off by default: clamav, and icap, a small c-icap adapter in front of it. To start them, put these in .env:

STS_CLAMAV_SCALE=1
STS_ICAP_SCALE=1
STS_MALWARE_SCAN_ENABLED=true
STS_MALWARE_SCAN_URL=icaps://icap:11344/avscan
STS_MALWARE_SCAN_CA_FILE=/etc/ssl/icap/icap.crt

The adapter listens on TLS only and makes a new self-signed certificate each time it starts. It publishes the certificate on a volume mounted at /etc/ssl/icap, so the setting above always names the current one.

To run the adapter without TLS, for example on a network you trust, add these and drop STS_MALWARE_SCAN_CA_FILE. In product mode the service refuses plain ICAP unless the second line is set:

STS_ICAP_TLS=false
STS_MALWARE_SCAN_ALLOW_CLEARTEXT=true
STS_MALWARE_SCAN_URL=icap://icap:1344/avscan

ClamAV takes a minute or two to load its signatures, and files are refused until it has.

Its size limits are raised above the default risk.uploadMaxBytes (2 GiB): StreamMaxLength and MaxFileSize to 2500M and MaxScanSize to 4000M, and the adapter’s virus_scan.MaxObjectSize to 2500M. If you raise risk.uploadMaxBytes past 2500M, raise these with it, or those uploads are refused or go unscanned.