Mail::ClamAV - Perl extension for the clamav virus scanner
use Mail::ClamAV qw/:all/;
# $Mail::ClamAV::Error in numeric context return clamav's
# error status code which corresponds to the constants which
# can be exported
my $c = new Mail::ClamAV("/path/to/directory/or/file")
or die "Failed to load db: $Mail::ClamAV::Error (", 0+$Mail::;
# You can get retdbdir() to get the database dir in
# clamav's conf
my $c = new Mail::ClamAV(retdbdir())
or die "Failed to load db: $Mail::ClamAV::Error";
# When database is loaded, you must create the proper trie with:
$c->buildtrie;
# check to see if we need to reload
if ($c->statchkdir) {
$c = new Mail::ClamAV(retdbdir());
$c->buildtrie;
}
# Set some limits (only applies to scan())
# Only relevant for archives
$c->maxreclevel(4);
$c->maxfiles(20);
$c->maxfilesize(1024 * 1024 * 20); # 20 megs
$c->archivememlim(0); # limit memory usage for bzip2 (0/1)
$c->maxratio(0);
# Scan a buffer
my $status = $c->scanbuff($buff);
# Scan a filehandle (scandesc in clamav)
# scan(FileHandle or path, Bitfield of options)
my $status = $c->scan(FH, CL_SCAN_ARCHIVE|CL_SCAN_MAIL);
# Scan a file (scanfile in clamav)
my $status = $c->scan("/path/to/file.eml", CL_SCAN_MAIL);
# $status is an overloaded object
die "Failed to scan: $status" unless $status;
if ($status->virus) {
print "Message is a virus: $status\n";
}
else {
print "No virus found!\n";
}
Clam AntiVirus is an anti-virus toolkit for UNIX http://clamav.elektrapro.com/. This module provide a simple interface to its C API.
None by default.
Options for scanning.
This is an alias for a recommended set of scan options. You should use it to make your software ready for new features in future versions of libclamav.
It does nothing. Please use it (alone) if you don't want to scan any special files.
This flag enables transparent scanning of various archive formats.
With this flag the library marks encrypted archives as viruses (Encrypted.Zip, Encrypted.RAR).
Mark archives as viruses if maxfiles, maxfilesize, or maxreclevel limit is reached.
It enables support for mail files.
The mail scanner will download and scan URLs listed in a mail body. This flag should not be used on loaded servers. Due to potential problems please do not enable it by default but make it optional.
Enables support for Microsoft Office document files.
This flag enables scanning withing Portable Executable files and allows libclamav to unpack UPX, Petite, and FSG compressed executables.
libclamav will try to detect broken executables and mark them as Broken.Executable.
This flag enables HTML normalisation (including JScript decryption).
Status returns. You can get the status code by putting the status object returned into into numeric context.
my $status = $c->scan("foo.txt");
print "Status: ", ($status + 0), "\n";
The following are returned statuses if no error occured.
Error statuses
recursion level limit exceeded
size limit exceeded
files limit exceeded
rar handler error
zip handler error
malformed zip
gzip handler error
bzip2 handler error
OLE2 handler error
access denied
null argument error
These function can be exported either individually or using the :all export flags
This function returns the path to the database directory specified when clamav was compiled.
NOTE These settings only apply to scan() and archives (CL_SCAN_ARCHIVE).
Sets the maximum recursion level [default 5].
Maximum number of files that will be scanned [default 1000]. A value of zero disables the check.
Maximum file size that will be scanned in bytes [default 10M]. A value of zero disables the check.
Maximum compression ratio. So if this is set to 200, libclamav will give up decompressing a file if it reaches 200x its compressed size [default 200]. A value of zero disables the check.
Turns on/off memory usage limits for bzip2. [default 1]
All of these methods return a status object. This object is overloaded to make things cleaner. In boolean context this will return false if there was an error. For example: my $status = $c->scan("foo.txt"); die "Error scanning: $status" unless $status;
As you probably just noticed, $status in scalar context returns the error message. In addition to the overloading you just saw, $status has the following methods:
The numeric value (if any) clamav returned.
This will be true if the message was not a virus and an error did not occur.
Returns true if the message is a virus.
Return the error message (if any). This is the same thing as quoting $status.
Returns the number of messages scanned. Only works with archives.
scan() takes a FileHanle or path and passed the file descriptor for that off to clamav. The second argument is a bitfield of options, CL_SCAN_MAIL, CL_SCAN_ARCHIVE or CL_SCAN_RAW "Exportable constants".
This function returns the status object discussed earlier.
Note that if you are running in taint mode (-T) and a tainted path is passed to scan(), it will croak().
scanbuff takes a raw buffer and scans it. No options are available for this function (it is assumed you already unarchived or de-MIMEed the buffer and that it is raw).
If the path passed into new() is a directory Mail::ClamAV will set things up to check for updated database files. Calling the statchkdir() will check the database directory to the stats we have in memory. If anything has changed true is returned, otherwise false.
NOTE: trying to use statchkdir() when you passed in a database file instead of directory will produce a fatal error.
statchkdir() is useful for long running daemons that need to check to see if it is time to reload the database. Reloading is simply getting a new Mail::ClamAV object and initializing it.
The ClamAV API documentation http://www.clamav.net/doc/html-0.65/node44.html
Scott Beck <sbeck@gossamer-threads.com>
Copyright (C) 2003 by Gossamer Threads Inc. http://www.gossamer-threads.com
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.
