The Antivirus Check Service provides the ability to scan files with a locally installed clamav daemon. In addition, the service offers a URL scan using virustotal. The Antivirus Check Service processes incoming scan requests and sends the scan result to a specified web hook.
Antivirus Check Service provides two interfaces.
The WebAPI is the most common interface to use Antivirus Check Service.
All requests besides of the root resource /
have to be authenticated using basic access authentication.
A GET request to https://<antivirus-check-service>/
gives a detailed usage api doc:
"scan file request": {
"description": "Download file and scan against virus (using local clamd), report back to given webhook uri",
"path": "/scan/file",
"method": "POST",
"params": {
"download_uri": {
"type": "string",
"description": "Complete uri to the downloadable file"
},
"callback_uri": {
"type": "string",
"description": "Complete uri to the callback uri"
},
}
},
"scan url request": {
"description": "Scan Url (using virustotal), report back to given webhook Uri",
"path": "/scan/url",
"method": "POST",
"params": {
"url": {
"type": "string",
"description": "Url to scan using virustotal"
},
"callback_uri": {
"type": "string",
"description": "Complete Uri to the callback uri"
},
}
},
"clamav daemon version": {
"description": "Get clamav daemon version and last database update",
"path": "/antivirus-version",
"method": "GET"
},
To get the clamav daemon version and last database update, you can send a request to the WebAPI /antivirus-version
.
The response is similar to:
{"clamd-version": "0.99.2/24389/Tue", "clamd-database-version": "2018/03/13 - 08:12:22"}
The Antivirus Check Service provides an AMQP API, which is uses by the WebAPI as well. Authenticate and publish a message to the regarding queue using the routing_key:
amqp://<user>:<password>@<antivirus-check-service>/antivirus
scan_file
{
"download_uri": "https://<uri-to-file>",
"callback_uri": "https://<uri-to-report-endpoint>"
}
scan_url
{
"url": "https://<url-to-be-scanned>",
"callback_uri": "https://<uri-to-report-endpoint>"
}
The reports are PUT requests to the given webhook Uri. The payload differs reagrding the scan type.
{"virus_detected": "<true|false>", "virus_signature": "<null|signature name>"}
{"blacklisted": "<true|false>", "full_report": "<virustotal's full report>"}
If an error occures the Antivirus Check Service will try to send an error page (500) with the error message as json:
{"error": "<error message>"}
As prerequisite you have to have installed: git
and make
.
In general, follow the instruction in the vagrant provision script.
To get the services running, you need access to rabbitmq-server and clamav-daemon.
Copy ./resources/rabbitmq-definitions.template.json
to /etc/rabbitmq/rabbitmq-definitions.json
and
Copy ./resources/rabbitmq.config
to /etc/rabbitmq/rabbitmq.config
.
Adjust the amqp <user>
and the <sha256-hash-of-users-password>
.
To get the <sha256-hash-of-users-password>
you can follow the (missleading) documentation from rabbitmq:
https://www.rabbitmq.com/passwords.html#computing-password-hash .
Or you can use my tool. Change to ./resources
and run python encrypt_rabbitmq_password.py --password="<your-rabbit-password>"
(only python2).
/etc/clamav/clamd.conf
:
TCPSocket 3310
TCPAddr 0.0.0.0
An API-Key is needed to use virustotal. To get this, an account on virustotal has to be created. The API-Key can be found in the account's settings.
git clone
this repository to a modern debian (currently stretch). Change to the new
directory and run as root
: make install
. This will install all necessary
packages.
/resources/config.template.yml
to /antivirus_service/config.yml
and adjust the config file.auth_keys
to the webserver section, format: <username>:<password>
/usr/local/bin/antivirus
systemctl start antivirus-<webserver|scanfile|scanurl>.service
systemctl status antivirus-<webserver|scanfile|scanurl>.service
journalctl -f -u antivirus-<webserver|scanfile|scanurl>.service
antivirus_check_service/tests
and start the development webserver with:
python3 develop_webserver.py
. The minimal webserver simulates the fileserver and listens for the webhook.curl -v -d@scan_virus_file_payload.json -u <username>:<password> http://<antivirus-check-service>:8080/scan/file
,
whereby scan_virus_file_payload.json
has the payload:
{
"download_uri": "http://localhost:7000/scanfile?name=virus.txt",
"callback_uri": "http://localhost:7000/report"
}
======== Running on http://0.0.0.0:7000 ========
(Press CTRL+C to quit)
--- Scan Request Result ---
{"virus_detected": true, "virus_signature": "Eicar-Test-Signature"}
Change to install directory and run make update
This project can be developed and tested in a vagrant box. debian/stretch64
is used as predefined image.
It is strongly recommended to use the vagrant-vbguest plugin: by vagrant plugin install vagrant-vbguest
.
(The virtualbox guest additions provides synchronizing the sources)
The vagrant command vagrant up
starts a virtual machine and provision Antivirus Check Service
within. At the end of the provision the Antivirus Check Service service will
be started.