How To Automatically Scan Uploaded Files For Viruses With php-clamavlib

Version 1.0
Author: Falko Timme <ft [at] falkotimme [dot] com>
Last edited 01/03/2007

This guide describes how you can automatically scan files uploaded by users through a web form on your server using PHP and ClamAV. That way you can make sure that your upload form will not be abused to distribute malware. To glue PHP and ClamAV, we install the package php5-clamavlib/php4-clamavlib which is rather undocumented at this time. That package is available for Debian Etch and Sid and also for Ubuntu Dapper Drake and Edgy Eft, so make sure you use one of these platforms.

I want to say first that this is not the only way of setting up such a system. There are many ways of achieving this goal but this is the way I take. I do not issue any guarantee that this will work for you!

1 Preliminary Note

As I said before, your system must use Debian Etch, Sid, Ubuntu Dapper Drake or Ubuntu Edgy Eft, and you should already have Apache2 and PHP4 or PHP5 installed.

If you are on Debian Sarge, you can install the php-clamavlib package from backports.org: http://www.backports.org/debian/pool/main/p/php-clamavlib/

I assume that you use /var/www as the default document root. If you have multiple web sites on your server already, adjust the document root to your needs. Also, I use 192.168.0.100 as the IP address of my server in this example. Adjust this as well, and if you have multiple web sites with a name-based vhost configuration, you must use the respective domain/FQDN to access the web site instead of the IP address.

I do all the steps here as the root user. So make sure you're logged in as root or, if you are on Ubuntu, prepend all commands with sudo, e.g.

apt-get update

would become

sudo apt-get update

2 Modify /etc/apt/sources.list

If you use Ubuntu Dapper Drake or Ubuntu Edgy Eft, you must modify /etc/apt/sources.list so that the universe repository is enabled. If you are on Debian Etch or Sid, then don't edit /etc/apt/sources.list.

2.1 Ubuntu Dapper Drake

Edit /etc/apt/sources.list and make sure you have the line deb http://de.archive.ubuntu.com/ubuntu/ dapper universe in it (replace de.archive.ubuntu.com with your a Ubuntu mirror close to you):

vi /etc/apt/sources.list

[...]
deb http://de.archive.ubuntu.com/ubuntu/ dapper universe
[...]

Then run

apt-get update

to update the packages database.

2.2 Ubuntu Edgy Eft

Edit /etc/apt/sources.list and make sure you have the line deb http://de.archive.ubuntu.com/ubuntu/ edgy universe in it (replace de.archive.ubuntu.com with your a Ubuntu mirror close to you):

vi /etc/apt/sources.list

[...]
deb http://de.archive.ubuntu.com/ubuntu/ edgy universe
[...]

Then run

apt-get update

to update the packages database.

3 Install ClamAV And php-clamavlib

Next we install ClamAV (our virus scanner) and php-clamavlib, the package that provides the glue between PHP and ClamAV.

If you use PHP5, run:

apt-get install php5-clamavlib clamav clamav-freshclam clamav-docs arj unzoo

If you use PHP4, run:

apt-get install php4-clamavlib clamav clamav-freshclam clamav-docs arj unzoo

Then restart Apache:

/etc/init.d/apache2 restart

If you like you can take a look at your php.ini (/etc/php5/apache2/php.ini if you use PHP5, /etc/php4/apache2/php.ini if you use PHP4) to see if there are entries for php-clamavlib. These should look like this:

vi /etc/php5/apache2/php.ini

[...]
extension=clamav.so
[clamav]
clamav.dbpath=/var/lib/clamav
clamav.maxreclevel=0
clamav.maxfiles=0
clamav.archivememlim=0
clamav.maxfilesize=0
clamav.maxratio=0

vi /etc/php4/apache2/php.ini

[...]
extension=clamav.so
[clamav]
clamav.dbpath=/var/lib/clamav
clamav.maxreclevel=0
clamav.maxfiles=0
clamav.archivememlim=0
clamav.maxfilesize=0
clamav.maxratio=0

If you are on Debian Sarge, you can install the php-clamavlib package from backports.org: http://www.backports.org/debian/pool/main/p/php-clamavlib/

4 php-clamavlib Functions

There's no documentation about the PHP functions provided by php-clamavlib, but I've found a script called clamav.php in the source code of php-clamavlib that shows which functions are available. We create the same script now in our /var/www directory:

vi /var/www/clamav.php

<?php
if(!extension_loaded('clamav')) {
        dl('clamav.' . PHP_SHLIB_SUFFIX);
}
$module = 'clamav';
$functions = get_extension_funcs($module);
echo "Functions available in the test extension:<br>\n";
foreach($functions as $func) {
    echo $func."<br>\n";
}
echo "<br>\n";
$function = 'confirm_' . $module . '_compiled';
if (extension_loaded($module)) {
        $str = $function($module);
} else {
        $str = "Module $module is not compiled into PHP";
}
echo "$str\n";
?>

Now type in http://192.168.0.100/clamav.php in your browser. The output should look like this:

Functions available in the test extension:
cl_info
cl_scanfile
cl_scanbuff
cl_setlimits
cl_scanfile_ex
cl_scanbuff_ex
cl_pretcode
clam_scan_buffer
clam_scan_file
clam_get_version

Fatal error: Call to undefined function confirm_clamav_compiled() in /var/www/clamav.php on line 14

You can ignore the fatal error in the last line.

Now we know which functions are available, but we don't know which parameters they need. I found this page: http://www.clamav.net/doc/0.88.4/html/node41.html that describes similar functions in the source code of ClamAV. By testing and by reading that page I found out how to use the functions cl_info(), cl_scanfile(), cl_setlimits(), and clam_get_version(). That are all the functions we need to scan uploaded files (in fact we'd need only cl_scanfile()). In the next chapter we will create a small HTML upload form and use these functions to scan uploaded files for viruses.