Clam Antivirus 0.90: User Manual
Clam Antivirus 0.90: User Manual
90
User Manual
Contents 1
Contents
1 Introduction 3
1.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Mailing lists and IRC channel . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Virus submitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Base package 5
2.1 Supported platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Binary packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 Installation 6
3.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.2 Installing on shell account . . . . . . . . . . . . . . . . . . . . . . . . 6
3.3 Adding new system user and group . . . . . . . . . . . . . . . . . . . . 7
3.4 Compilation of base package . . . . . . . . . . . . . . . . . . . . . . . 7
3.5 Compilation with clamav-milter enabled . . . . . . . . . . . . . . . . . 7
4 Configuration 8
4.1 clamd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1.1 On-access scanning . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2 clamav-milter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.3 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.4 Setting up auto-updating . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.4.1 Closest mirrors . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5 Usage 11
5.1 Clam daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.2 Clamdscan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.3 Clamuko . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4 Output format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4.1 clamscan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4.2 clamd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6 LibClamAV 15
6.1 Licence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.2 Supported formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.2.1 Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.2.2 Mail files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.2.3 Archives and compressed files . . . . . . . . . . . . . . . . . . 16
Contents 2
6.2.4 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.2.5 Others . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.3 Hardware acceleration . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.4 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.4.1 Header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.4.2 Database loading . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.4.3 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6.4.4 Engine structure . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.5 Database reloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.5.1 Data scan functions . . . . . . . . . . . . . . . . . . . . . . . . 20
6.5.2 Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.5.3 clamav-config . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.5.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.6 CVD format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.7 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.8 Donors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.9 Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.10 OpenAntiVirus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
7 Core Team 40
Clam AntiVirus is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License along with this
program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
Floor, Boston, MA 02110-1301, USA.
1 Introduction
Clam AntiVirus is an anti-virus toolkit for UNIX, designed especially for e-mail scan-
ning on mail gateways. It provides a number of utilities including a flexible and scal-
able multi-threaded daemon, a command line scanner and advanced tool for automatic
database updates. The core of the package is an anti-virus engine available in a form of
shared library.
1.1 Features
• Licensed under the GNU General Public License, Version 2
• Fast scanning
• Detects over 90.000 viruses, worms and trojans, including Microsoft Office macro
viruses, mobile malware, and other threats
• Scans within archives and compressed files (also protects against archive bombs),
built-in support includes:
– UPX
– FSG
1 Introduction 4
– Petite
– NsPack
– wwpack32
– MEW
– Upack
– SUE
– Y0da Cryptor
– HTML
– RTF
– PDF
– Files encrypted with CryptFF and ScrEnc
– uuencode
– TNEF (winmail.dat)
• Advanced database updater with support for scripted updates, digital signatures
and DNS based database version queries
/server irc.freenode.net
/join #clamav
http://www.clamav.net/sendvirus
2 Base package
2.1 Supported platforms
Most popular UNIX operating systems are supported. Clam AntiVirus 0.90 was tested
on:
• GNU/Linux
• Solaris
• FreeBSD
• OpenBSD 2
• Mac OS X
Some features may not be available on your operating system. If you are successfully
running Clam AntiVirus on a system not listed above please let us know.
3 Installation
3.1 Requirements
The following elements are required to compile ClamAV:
• gcc compiler suite (tested with 2.9x, 3.x and 4.x series)
• GNU MP 3
It’s very important to install the GMP package because it allows freshclam to
verify the digital signatures of the virus databases and scripted updates. If fresh-
clam was compiled without GMP support it will display ”SECURITY WARN-
ING: NO SUPPORT FOR DIGITAL SIGNATURES” on every update. You can
download GNU MP at http://www.swox.com/gmp/
A note for Solaris/SPARC users: you must set the ABI system variable to 32 (e.g.
setenv ABI 32) before running the configuration script of GMP.
$ ˜/clamav/bin/freshclam
$ ˜/clamav/bin/clamscan ˜
The --disable-clamav switch disables the check for existence of the clamav user and
group but clamscan would still require an unprivileged account to work in a superuser
mode.
3 Installation 7
# groupadd clamav
# useradd -g clamav -s /bin/false -c "Clam AntiVirus" clamav
Consult a system manual if your OS has not groupadd and useradd utilities. Don’t
forget to lock access to the account!
Assuming you want to install the configuration files in /etc, configure and build the
software as follows:
$ ./configure --sysconfdir=/etc
$ make
$ su -c "make install"
In the last step the software is installed into the /usr/local directory and the config files
into /etc. WARNING: Never enable the SUID or SGID bits for Clam AntiVirus
binaries.
$ ./configure --enable-milter
3
Cygwin note: If you have not /etc/passwd you can skip this point
4 Configuration 8
4 Configuration
4.1 clamd
Before you start using the daemon you have to edit the configuration file (in other case
clamd won’t run):
$ clamd
ERROR: Please edit the example config file /etc/clamd.conf.
This shows the location of the default configuration file. The format and options of this
file are fully described in the clamd.conf(5) manual. The config file is well commented
and configuration should be straightforward.
Depending on your Linux distribution you may need to add a ”dazuko” entry to /etc/modules
or run the module during system’s startup by adding
/sbin/modprobe dazuko
4.2 clamav-milter
Nigel Horne’s clamav-milter is a very efficient email scanner designed for Send-
mail. It’s written entirely in C and only depends on libclamav or clamd. You can find
detailed installation instructions in the INSTALL file that comes with the clamav-milter
sources. Basically, to connect it with Sendmail add the following lines to /etc/mail/sendmail.mc:
INPUT_MAIL_FILTER(‘clmilter’,‘S=local:/var/run/clamav/clmilter.sock,
F=, T=S:4m;R:4m’)dnl
define(‘confINPUT_MAIL_FILTERS’, ‘clmilter’)
Start clamav-milter
/usr/local/sbin/clamav-milter -lo /var/run/clamav/clmilter.sock
4.3 Testing
Try to scan recursively the source directory:
$ clamscan -r -l scan.txt clamav-x.yz
It should find some test files in the clamav-x.yz/test directory. The scan result will be
saved in the scan.txt log file 4 . To test clamd, start it and use clamdscan (or instead
connect directly to its socket and run the SCAN command):
$ clamdscan -l scan.txt clamav-x.yz
Please note that the scanned files must be accessible by the user running clamd or you
will get an error.
4 To get more info on clamscan options run ’man clamscan’
4 Configuration 10
# touch /var/log/freshclam.log
# chmod 600 /var/log/freshclam.log
# chown clamav /var/log/freshclam.log
Now you should edit the configuration file freshclam.conf and point the UpdateLog-
File directive to the log file. Finally, to run freshclam in the daemon mode, execute:
# freshclam -d
The other way is to use the cron daemon. You have to add the following line to the
crontab of root or clamav user:
N * * * * /usr/local/bin/freshclam --quiet
to check for a new database every hour. N should be a number between 3 and 57
of your choice. Please don’t choose any multiple of 10, because there are already
too many clients using those time slots. Proxy settings are only configurable via the
configuration file and freshclam will require strict permission settings for the config
file when HTTPProxyPassword is turned on.
HTTPProxyServer myproxyserver.com
HTTPProxyPort 1234
HTTPProxyUsername myusername
HTTPProxyPassword mypass
5 Usage 11
DNSDatabaseInfo current.cvd.clamav.net
DatabaseMirror db.ac.clamav.net
DatabaseMirror database.clamav.net
The second entry acts as a fallback in case the connection to the first mirror fails for
some reason. The full list of two-letters country codes is available at http://www.
iana.org/cctld/cctld-whois.htm
5 Usage
5.1 Clam daemon
clamd is a multi-threaded daemon that uses libclamav to scan files for viruses. It may
work in one or both modes listening on:
• TCP socket
The daemon is fully configurable via the clamd.conf file 5 . clamd recognizes the
following commands:
• PING
Check the daemon’s state (should reply with ”PONG”).
• VERSION
Print program and database versions.
• RELOAD
Reload the databases.
5 man 5 clamd.conf
5 Usage 12
• SHUTDOWN
Perform a clean exit.
• SCAN file/directory
Scan file or directory (recursively) with archive support enabled (a full path is
required).
• RAWSCAN file/directory
Scan file or directory (recursively) with archive and special file support disabled
(a full path is required).
• CONTSCAN file/directory
Scan file or directory (recursively) with archive support enabled and don’t stop
the scanning when a virus is found.
• MULTISCAN file/directory
Scan file in a standard way or scan directory (recursively) using multiple threads
(to make the scanning faster on SMP machines).
• STREAM
Scan stream: clamd will return a new port number you should connect to and
send data to scan.
• SESSION, END
Start/end a clamd session - you can do multiple commands per TCP session
(WARNING: due to the clamd implementation the RELOAD command will
break the session).
and reacts on the special signals:
• SIGTERM - perform a clean exit
5.2 Clamdscan
clamdscan is a simple clamd client. In many cases you can use it as a clamscan
replacement however you must remember that:
• it only depends on clamd
• although it accepts the same command line options as clamscan most of them are
ignored because they must be enabled directly in clamd, i.e. clamd.conf
5 Usage 13
5.3 Clamuko
Clamuko is a special thread in clamd that performs on-access scanning under Linux and
FreeBSD and shares internal virus database with the daemon. You must follow some
important rules when using it:
• Always stop the daemon cleanly - using the SHUTDOWN command or the
SIGTERM signal. In other case you can lose access to protected files until the
system is restarted.
• Never protect the directory your mail-scanner software uses for attachment un-
packing. Access to all infected files will be automatically blocked and the scanner
(including clamd!) will not be able to detect any viruses. In the result all infected
mails may be delivered.
For example, to protect the whole system add the following lines to clamd.conf:
ClamukoScanOnAccess
ClamukoIncludePath /
ClamukoExcludePath /proc
ClamukoExcludePath /temporary/dir/of/your/mail/scanning/software
You can also use clamuko to protect files on Samba/Netatalk but a far more better and
safe idea is to use the samba-vscan module. NFS is not supported because Dazuko
doesn’t intercept NFS access calls.
/tmp/test/message.c: OK
/tmp/test/error.hta: VBS.Inor.D FOUND
When a virus is found its name is printed between the filename: and FOUND strings. In
case of archives the scanner depends on libclamav and only prints the first virus found
within an archive:
TIP: You can force clamscan to list all infected files in an archive using –no-archive
(this option disables transparent decompressors built into libclamav) and enabling ex-
ternal decompressors: –unzip –unrar....
5.4.2 clamd
The output format of clamd is very similar to clamscan.
In the SCAN mode it closes the connection when the first virus is found.
6 LibClamAV 15
SCAN /home/zolw/test/clam.zip
/home/zolw/test/clam.zip: ClamAV-Test-File FOUND
SCAN /no/such/file
/no/such/file: Can’t stat() the file. ERROR
6 LibClamAV
Libclamav provides an easy and effective way to add a virus protection into your soft-
ware. The library is thread-safe and transparently recognizes and scans within archives,
mail files, MS Office document files, executables and other special formats.
6.1 Licence
Libclamav is licensed under the GNU GPL v2 licence. This means you are not allowed
to link commercial, close-source applications against it6 . All software using libclamav
must be GPL compliant.
• Petite (2.x)
• NsPack
• wwpack32 (1.20)
6 You can still use clamd or clamscan instead
6 LibClamAV 16
• MEW
• Upack
• SUE
• Y0da Cryptor (1.3)
6.2.4 Documents
The most popular file formats are supported:
• MS Office and MacOffice files
• RTF
• PDF
• HTML
6 LibClamAV 17
6.2.5 Others
Libclamav can handle various obfuscators, encoders, files vulnerable to security risks
such as:
• uuencode
• ScrEnc obfuscation
• CryptFF
6.4 API
6.4.1 Header file
Every program using libclamav must include the header file clamav.h:
#include <clamav.h>
cl_retdbdir returns the default (hardcoded) path to the directory with ClamAV databases.
cl_load loads a single database file or all databases from a directory (if path points
to a directory). The second argument is used for passing in the engine structure which
should be previously initialized with NULL. A number of loaded signatures will be
added to signo 7 . The last argument can pass the following flags:
• CL DB STDOPT
This is an alias for a recommended set of scan options.
• CL DB NCORE
Initialize NodalCore and load the hardware database (if applicable).
• CL DB PHISHING
Load phishing signatures.
• CL DB PHISHING URLS
Initialize the phishing detection module and load .wdb and .pdb files.
...
struct cl_engine *engine = NULL;
unsigned int sigs = 0;
int ret;
if(ret) {
printf("cl_load() error: %s\n", cl_strerror(ret));
exit(1);
}
In our example:
if((ret = cl_build(engine))) {
printf("cl_build() error: %s\n", cl_strerror(ret));
cl_free(engine);
exit(1);
}
Initialization:
...
struct cl_stat dbstat;
To check for a change you just need to call cl_statchkdir and check its return value:
if(cl_statchkdir(&dbstat) == 1) {
reload_database...;
cl_statfree(&dbstat);
cl_statinidir(cl_retdbdir(), &dbstat);
}
Both functions will save a virus name under the pointer virname, the virus name is
part of the engine structure and must not be released directly. If the third argument
(scanned) is not NULL, the functions will increase its value with the size of scanned
data (in CL_COUNT_PRECISION units). Both functions have support for archive limits in
order to protect against Denial of Service attacks.
struct cl_limits {
unsigned int maxreclevel; /* maximum recursion level for archives */
unsigned int maxfiles; /* maximum number of files to be scanned
* within a single archive
*/
unsigned int maxmailrec; /* maximum recursion level for mail files */
unsigned int maxratio; /* maximum compression ratio */
unsigned long int maxfilesize;/* compressed files larger than this limit
* will not be scanned
*/
unsigned short archivememlim; /* limit memory usage for some unpackers */
};
The last argument (options) configures the scan engine and supports the following
flags (that can be combined using bit operators):
• 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.
6 LibClamAV 21
• 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.
All functions return 0 (CL_CLEAN) when the file seems clean, CL_VIRUS when a virus is
detected and another value on failure.
...
struct cl_limits limits;
const char *virname;
6.5.2 Memory
Because the engine structure consumes a few megabytes of system memory, you should
release it with cl_free if you no longer need to scan files.
6.5.3 clamav-config
Use clamav-config to check compilation information for libclamav.
-I/usr/local/include -g -O2
6.5.4 Example
You will find an example scanner application in the clamav sources (/example). Don’t
forget that all programs based on libclamav must be linked against it:
6.7 Contributors
The following people contributed to our project in some way (providing patches, bug
reports, technical support, documentation, good ideas...):
• David <djgardner*users.sourceforge.net>
• Jay <sysop-clamav*coronastreet.net>
• Kazuhiko <kazuhiko*fdiary.net>
• Jo Mills <Jonathan.Mills*frequentis.com>
• Flinn Mueller<flinn*activeintra.net>
• Ed Phillips <ed*UDel.Edu>
• Ed Ravin <eravin*panix.com>
• Martin Schitter
• Scsi <scsi*softland.ru>
• Al Smith <ajs+clamav*aeschi.ch.eu.org>
• Steve <steveb*webtribe.net>
• Trashware <trashware*gmx.net>
• ST Wong <st-wong*cuhk.edu.hk>
6 LibClamAV 34
• David Wu <dyw*iohk.com>
• ZMan Z. <x86zman*go-a-way.dyndns.org>
6.8 Donors
We’ve received financial support from: (in alphabetical order)
• Steve Anderson
• Arudius (http://arudius.sourceforge.net/)
• Peter Ashman
• Dave Baker
6 LibClamAV 35
• Aaron Begley
• Craig H. Block
• Josh Burstyn
• By Design (http://www.by-design.net/)
• cedarcreeksoftware.com (http://www.cedarcreeksoftware.com/)
• Ricardo Cerqueira
• Thanos Chatziathanassiou
• Alan Cook
• Joe Cooper
• Ron DeFulio
• Digirati (http://oss.digirati.com.br/)
• eCoupons.com (http://www.ecoupons.com/)
• John T. Ellis
• Epublica
• Bernhard Erdmann
6 LibClamAV 36
• Philip Ershler
• David Farrick
• Jim Feldman
• Paul Freeman
• Jack Fung
• Stephen Gageby
• Paolo Galeazzi
• GANDI (http://www.gandi.net/)
• GHRS (http://www.ghrshotels.com/)
• Lyle Giese
• Todd Goodman
• Grain-of-Salt Consulting
• Terje Gravvold
• Pen Helm
• Interact2Day (http://www.interact2day.com/)
• Craig Jackson
• Stuart Jones
• Jason Judge
• Keith (http://www.textpad.com/)
• Brad Koehn
• Olivier Marechal
• Matthew McKenzie
• Mimecast (http://www.mimecast.com/)
• Kazuhiro Miyaji
• Bozidar Mladenovic
• Paul Morgan
• Tomas Morkus
6 LibClamAV 38
• Jorgen Norgaard
• Oneworkspace.com (http://www.oneworkspace.com/)
• Alexander Panzhin
• Thodoris Pitikaris
• Paul Rantin
• RHX (http://www.rhx.it/)
• Stefano Rizzetto
• Luke Rosenthal
• Tim Scoff
6 LibClamAV 39
• Stephane Rault
• SearchMain (http://www.searchmain.com/)
• Olivier Silber
• StarBand (http://www.starband.com/)
• Sahil Tandon
• Brad Tarver
• William Tisdale
• Ulfi
• Nicklaus Wicker
• David Williams (http://kayakero.net/)
• Glenn R Williams
• Kelly Williams
6.9 Graphics
The ClamAV logo was created by Mia Kalenius and Sergei Pronin from Finndesign
(http://www.finndesign.fi/).
6.10 OpenAntiVirus
Our database includes the virus database (about 7000 signatures) from OpenAntiVirus
(http://OpenAntiVirus.org).
7 Core Team
• aCaB <acab*clamav.net>, Italy
Role: virus database maintainer, coder