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->build or die "Failed to build engine: $Mail::ClamAV::Error"; # check to see if we need to reload if ($c->statchkdir) { $c = new Mail::ClamAV(retdbdir()); $c->build or die "Failed to build engine: $Mail::ClamAV::Error"; } # Set some limits (only applies to scan()) # Only relevant for archives $c->maxreclevel(4); $c->maxmailrec(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 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"; } DESCRIPTION Clam AntiVirus is an anti-virus toolkit for UNIX . This module provide a simple interface to its C API. EXPORT None by default. Exportable constants Options for scanning. CL_SCAN_STDOPT This is an alias for a recommended set of scan options. You should use it to make your software ready for new features in the future versions of libclamav. CL_SCAN_RAW Use it alone if you want to disable support for special files. CL_SCAN_ARCHIVE This flag enables transparent scanning of various archive formats. CL_SCAN_BLOCKENCRYPTED With this flag the library will mark encrypted archives as viruses (Encrypted.Zip, Encrypted.RAR). CL_SCAN_BLOCKMAX Mark archives as viruses if maxfiles, maxfilesize, or maxreclevel limit is reached. CL_SCAN_MAIL Enable support for mail files. CL_SCAN_MAILURL 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. CL_SCAN_OLE2 Enables support for OLE2 containers (used by MS Office and .msi files). CL_SCAN_PE This flag enables deep scanning of Portable Executable files and allows libclamav to unpack executables compressed with run-time unpackers. CL_SCAN_ELF Enable support for ELF files. CL_SCAN_BLOCKBROKEN libclamav will try to detect broken executables and mark them as Broken.Executable. CL_SCAN_HTML This flag enables HTML normalisation (including ScrEnc decryption). CL_SCAN_ALGORITHMIC Enable algorithmic detection of viruses. CL_SCAN_PHISHING_DOMAINLIST Phishing module: restrict URL scanning to domains from .pdf (RECOMMENDED). CL_SCAN_PHISHING_BLOCKSSL Phishing module: always block SSL mismatches in URLs. CL_SCAN_PHISHING_BLOCKCLOAK Phishing module: always block cloaked URLs. 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 limit exceeded CL_EMAXSIZE size limit exceeded CL_EMAXFILES files limit exceeded CL_ERAR rar handler error CL_EZIP zip handler error CL_EGZIP gzip handler error CL_EBZIP bzip2 handler error CL_EOLE2 OLE2 handler error CL_EMSCOMP MS Expand handler error CL_EMSCAB MS CAB module error CL_EACCES access denied CL_ENULLARG null argument CL_ETMPFILE tmpfile() failed CL_EFSYNC fsync() failed CL_EMEM memory allocation error CL_EOPEN file open error CL_EMALFDB malformed database CL_EPATSHORT pattern too short CL_ETMPDIR mkdir() failed CL_ECVD not a CVD file (or broken) CL_ECVDEXTR CVD extraction failure CL_EMD5 MD5 verification error CL_EDSIG digital signature verification error CL_EIO general I/O error CL_EFORMAT bad format or broken file CL_ESUPPORT not supported data format CL_ELOCKDB can't lock DB directory CL_ENCINIT NodalCore initialization failed CL_ENCLOAD error loading NodalCore database CL_ENCIO general NodalCore I/O 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_SCAN_ARCHIVE). maxreclevel Sets the maximum recursion level into archives [default 5]. maxmailrec Sets the maximum recursion level into emails [default 10]. maxfiles Maximum number of files that will be scanned [default 1000]. A value of zero disables the check. maxfilesize Maximum file size that will be scanned in bytes [default 10M]. A value of zero disables the check. maxratio 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. archivememlim Turns on/off memory usage limits for bzip2. [default 1] 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_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($buff) This function was taken out of ClamAV in 0.90 and was thus taken out of Mail::ClamAV. 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 AUTHOR Scott Beck COPYRIGHT AND LICENSE Copyright (C) 2003 by Gossamer Threads Inc. 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.