NAME
Mail::ClamAV - Perl extension for the clamav virus scanner
SYNOPSIS
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
# 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_ARCHIVE|CL_MAIL);
# Scan a file (scanfile in clamav)
my $status = $c->scan("/path/to/file.eml", CL_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";
}DESCRIPTION
Clam AntiVirus is an anti-virus toolkit for UNIX http://clamav.elektrapro.com/. This module provide a simple interface to its C API.
EXPORT
None by default.
Exportable constants
Options for scanning.
- CL_RAW
-
It does nothing. Please use it (alone) if you don't want to scan any special files.
- CL_ARCHIVE
-
This flag enables the transparent archive scanning.
- CL_DISABLERAR
-
Disables the built-in RAR unpacker which is known to cause memory leaks.
- CL_ENCRYPTED
-
Marks encrypted archives as viruses (Enccrypted.Zip, Encrypted.RAR).
- CL_MAIL
-
Required to scan various types of mail files.
WARNING WARNING WARNING The MIME parsing in clamav is still beta quality code as of the time of this writing [Fri Apr 2 09:16:25 PST 2004]. It will segfault with certain emails. This tested with current CVS of clamav.
- CL_OLE2
-
Enables support for Microsoft Office document files.
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.
- CL_CLEAN
-
no viruses found
- CL_VIRUS
-
virus found, put the status in scalar context to see the type
Error statuses
- CL_EMAXREC
-
recursion level limit exceeded
- CL_EMAXSIZE
-
size limit exceeded
- CL_EMAXFILES
-
files limit exceeded
- CL_ERAR
-
rar handler error
- CL_EZIP
-
zip handler error
- CL_EMALFZIP
-
malformed zip
- CL_EGZIP
-
gzip handler error
- CL_EBZIP
-
bzip2 handler error
- CL_EOLE2
-
OLE2 handler error
- CL_EACCES
-
access denied
- CL_ENULLARG
-
null argument error
Exportable functions
These function can be exported either individually or using the :all export flags
- retdbdir
-
This function returns the path to the database directory specified when clamav was compiled.
METHODS
Settings
NOTE These settings only apply to scan() and archives (CL_ARCHIVE).
- maxreclevel
-
Sets the maximum recursion level [default 5].
- maxfiles
-
Maximum number of files that will be scanned [default 1000].
- maxfilesize
-
Maximum file size that will be scanned in bytes [default 10M].
Scanning
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:
- errno
-
The numeric value (if any) clamav returned.
- clean
-
This will be true if the message was not a virus and an error did not occur.
- virus
-
Returns true if the message is a virus.
- error
-
Return the error message (if any). This is the same thing as quoting $status.
- count
-
Returns the number of messages scanned. Only works with archives.
- scan(FileHandle or Path, Bitfield of options)
-
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_MAIL, CL_ARCHIVE or CL_RAW "Exportable constants".This function returns the status object discussed earlier
- scanbuff($buff)
-
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).
Data Directory stats
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.
SEE ALSO
The ClamAV API documentation http://www.clamav.net/doc/html-0.65/node44.html
AUTHOR
Scott Beck <sbeck@gossamer-threads.com>
COPYRIGHT AND LICENSE
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.