abes-esr / clamscan-docker

Dockerization 🐳 of ClamAV and specifically clamscan command used to scan periodicaly a specific folder for detecting trojans, viruses, malware & other malicious threats. If something bad is detected, an email is sent.

clamscan-docker

Dockerization of ClamAV and specifically clamscan command used to scan periodicaly a specific folder for detecting trojans, viruses, malware & other malicious threats. If something bad is detected, an email is sent.

demo.mp4

Parameters

• SCAN_AT_STARTUP: if 1, then start with a scan when the container is created (default is 1)
• FRESHCLAM_AT_STARTUP: if 1, then update the virus database when the container startup (default is 1)
• SCAN_ONLY_NEW_FILES: if 1, then the scan will scan a first time the whole FOLDER_TO_SCAN content, and the next time (see CRON_CLAMSCAN) it will only scan the new files found. Thanks to this feature, the process will be lighter (less CPU usage) especially when there is lot and lot of files in FOLDER_TO_SCAN (default is 1)
• FOLDER_TO_SCAN: this is the folder to scan with clamscan (default is /folder-to-scan/)
• CRON_CLAMSCAN: crontab parameters to run the clamscan command which is used to scan the FOLDER_TO_SCAN (default is */5 * * * * - it means each 5 minutes)
• CRON_FRESHCLAM: crontab parameters to run the freshclam command which is used to update virus databases (default is 0 * * * * * - it means each hours)
• ALERT_MAILTO: email address to send the alerts to (empty value as default so nothing is sent as)
• ALERT_SUBJECT: email subject for sending alerts to (Alert from clamscan ! is the default value)
• SMTP_TLS: to enable TLS, set the value to on (default is off)
• SMTP_HOST: host or ip of the smtp server used to send the alerts (default is 127.0.0.1)
• SMTP_PORT: port of the smtp server used to send the alerts (default is 25)
• SMTP_USER: smtp server login (empty value as default)
• SMTP_PASSWORD: smtp server password (empty value as default)

Usage

Here is a basic usecase. You have a folder (/var/www/html/uploads/) where anonymous users can upload attachment thanks to a web form. You want to be sure there is no malicious uploaded files. So you decide to deploy clamscan-docker to scan this folder each 15 minutes and to be alerted to [e-mail] if a virus is uploaded. Here is the docker commande you will run:

docker run -d --name myclamavcontainer \
  -v /var/www/html/uploads/:/folder-to-scan/ \
  -e SCAN_AT_STARTUP="1"
  -e CRON_CLAMSCAN="*/15 * * * *" \
  -e ALERT_SUBJECT="Alert from clamscan !" \
  -e ALERT_MAILTO="[e-mail]" \
  -e SMTP_HOST="smtp.mydomain.fr" \
  -e SMTP_PORT="25" \
  abesesr/clamscan-docker:1.4.7

Developement

Debugging and testing

Firstly, download a virus and put it into ./volumes/folder-to-scan/:

cd ./clamscan-docker/
mkdir -p volumes/folder-to-scan/ && cd volumes/folder-to-scan/ 
curl -L "https://github.com/ytisf/theZoo/blob/dd88d539de6c91e39483848fa0bd2fe859009c3e/malware/Binaries/Win32.LuckyCat/Win32.LuckyCat.zip?raw=true" > ./Win32.LuckyCat.zip
unzip -P infected ./Win32.LuckyCat.zip 

Then run the docker-compose.yml to scan the volumes/folder-to-scan/ folder:

cd ./clamscan-docker/
docker-compose up

Then, open your browser at http://127.0.0.1:8025/ to look at the alert mail sent at the fake email [e-mail]

Generating a new version

To generate a new version you have to:

1. Identify the version you want to create (the version should respect semver (X.X.X) and should not already exist)
2. Go the github action in charge of creating a new release: https://github.com/abes-esr/clamscan-docker/actions/workflows/create-release.yml
3. Clic on "Run workflow" on the right, indicate the version, and validate:
4. Validate and wait for the build,

See also

• https://dev.to/brisbanewebdeveloper/scan-infected-files-with-docker-and-clam-antivirus-clamav-1939
• https://medium.com/@darkcl_dev/scanning-files-with-clamav-inside-a-dockerized-node-application-bd2e5fcc5ce8