org.apache.james.transport.mailets
Class ClamAVScan

java.lang.Object
  org.apache.mailet.GenericMailet
      org.apache.james.transport.mailets.ClamAVScan

All Implemented Interfaces:

Mailet, MailetConfig

public class ClamAVScan
extends GenericMailet

Does an antivirus scan check using a ClamAV daemon (CLAMD)

Interacts directly with the daemon using the "stream" method, which should have the lowest possible overhead.

The CLAMD daemon will typically reside on localhost, but could reside on a different host. It may also consist on a set of multiple daemons, each residing on a different server and on different IP number. In such case a DNS host name with multiple IP addresses (round-robin load sharing) is supported by the mailet (but on the same port number).

Handles the following init parameters:

• <debug>.
• <host>: the host name of the server where CLAMD runs. It can either be a machine name, such as "java.sun.com", or a textual representation of its IP address. If a literal IP address is supplied, only the validity of the address format is checked. If the machine name resolves to multiple IP addresses, round-robin load sharing will be used. The default is localhost.
• <port>: the port on which CLAMD listens. The default is 3310.
• <maxPings>: the maximum number of connection retries during startup. If the value is 0 no startup test will be done. The default is 6.
• <pingIntervalMilli>: the interval (in milliseconds) between each connection retry during startup. The default is 30000 (30 seconds).
• <streamBufferSize>: the BufferedOutputStream buffer size to use writing to the stream connection. The default is 8192.

The actions performed are as follows:

• During initialization:
1. Gets all config.xml parameters, handling the defaults;
2. resolves the <host> parameter, creating the round-robin IP list;
3. connects to CLAMD at the first IP in the round-robin list, on the specified <port>;
4. if unsuccessful, retries every <pingIntervalMilli> milliseconds up to <maxPings> times;
5. sends a PING request;
6. waits for a PONG answer;
7. repeats steps 3-6 for every other IP resolved.
• For every mail
1. connects to CLAMD at the "next" IP in the round-robin list, on the specified <port>, and increments the "next" index; if the connection request is not accepted tries with the next one in the list unless all of them have failed;
2. sends a "STREAM" request;
3. parses the "PORT streamPort" answer obtaining the port number;
4. makes a second connection (the stream connection) to CLAMD at the same host (or IP) on the streamPort just obtained;
5. sends the mime message to CLAMD (using MimeMessage.writeTo(OutputStream)) through the stream connection;
6. closes the stream connection;
7. gets the "OK" or "... FOUND" answer from the main connection;
8. closes the main connection;
9. sets the "org.apache.james.infected" mail attribute to either "true" or "false";
10. adds the "X-MessageIsInfected" header to either "true" or "false";

Some notes regarding clamav.conf:

• LocalSocket must be commented out
• TCPSocket must be set to a port# (typically 3310)
• StreamMaxLength must be >= the James config.xml parameter <maxmessagesize> in SMTP <handler>
• MaxThreads should? be >= the James config.xml parameter <threads> in <spoolmanager>
• ScanMail must be uncommented

Here follows an example of config.xml definitions deploying CLAMD on localhost, and handling the infected messages:

 ...

    <!-- Do an antivirus scan -->
    <mailet match="All" class="ClamAVScan" onMailetException="ignore"/>

    <!-- If infected go to virus processor -->
    <mailet match="HasMailAttributeWithValue=org.apache.james.infected, true" class="ToProcessor">
       <processor> virus </processor>
    </mailet>

    <!-- Check attachment extensions for possible viruses -->
    <mailet match="AttachmentFileNameIs=-d -z *.exe *.com *.bat *.cmd *.pif *.scr *.vbs *.avi *.mp3 *.mpeg *.shs" class="ToProcessor">
       <processor> bad-extensions </processor>
    </mailet>

 ...

 <!-- Messages containing viruses -->
 <processor name="virus">

    <!-- To avoid a loop while bouncing -->
    <mailet match="All" class="SetMailAttribute">
       <org.apache.james.infected>true, bouncing</org.apache.james.infected>
    </mailet>

    <mailet match="SMTPAuthSuccessful" class="Bounce">
       <sender>bounce-admin@xxx.com</sender>
       <inline>heads</inline>
       <attachment>none</attachment>
       <notice> Warning: We were unable to deliver the message below because it was found infected by virus(es). </notice>
    </mailet>

    <!--
    <mailet match="All" class="ToRepository">
       <repositoryPath>file://var/mail/infected/</repositoryPath>
    </mailet>
    -->

    <mailet match="All" class="Null" />
 </processor>
 

Since:

2.2.1

Version:

2.2.1

See Also:

ClamAV Home Page, ClamAV For Windows

Constructor Summary

ClamAVScan()

Method Summary

protected void	checkInitParameters(java.lang.String[] allowedArray) Checks if there are unallowed init parameters specified in the configuration file against the String[] allowedInitParameters.
protected java.net.InetAddress[]	getAddresses() Getter for property addresses.
protected java.net.InetAddress	getAddresses(int index) Indexed getter for property addresses.
int	getAddressesCount() Getter for property addressesCount.
protected java.lang.String[]	getAllowedInitParameters() Gets the expected init parameters.
protected java.net.Socket	getClamdSocket() Gets a Socket connected to CLAMD.
java.lang.String	getHost() Getter for property host.
java.lang.String	getMailetInfo() Return a string describing this mailet.
int	getMaxPings() Getter for property maxPings.
protected java.net.InetAddress	getNextAddress() Getter for property nextAddress.
int	getPingIntervalMilli() Getter for property pingIntervalMilli.
int	getPort() Getter for property port.
int	getStreamBufferSize() Getter for property streamBufferSize.
protected int	getStreamPortFromAnswer(java.lang.String answer) Parses the answer from a STREAM request and gets the port number.
void	init() Mailet initialization routine.
protected void	initDebug() Initializer for property debug.
protected void	initHost() Initializer for property host.
protected void	initMaxPings() Initializer for property maxPings.
protected void	initPingIntervalMilli() Initializer for property pingIntervalMilli.
protected void	initPort() Initializer for property port.
protected void	initStreamBufferSize() Initializer for property streamBufferSize.
boolean	isDebug() Getter for property debug.
protected void	ping() Tries to "ping" all the CLAMD daemons to check if they are up and accepting requests.
protected void	ping(java.net.InetAddress address) Tries (and retries as specified up to 'getMaxPings()') to "ping" the specified CLAMD daemon to check if it is up and accepting requests.
protected void	saveChanges(javax.mail.internet.MimeMessage message) Saves changes resetting the original message id.
void	service(Mail mail) Scans the mail.
protected void	setAddresses(java.net.InetAddress[] addresses) Setter for property addresses.
void	setDebug(boolean debug) Setter for property debug.
void	setHost(java.lang.String host) Setter for property host.
void	setMaxPings(int maxPings) Setter for property maxPings.
void	setPingIntervalMilli(int pingIntervalMilli) Setter for property pingIntervalMilli.
void	setPort(int port) Setter for property port.
void	setStreamBufferSize(int streamBufferSize) Setter for property streamBufferSize.

Methods inherited from class org.apache.mailet.GenericMailet

destroy, getInitParameter, getInitParameter, getInitParameterNames, getMailetConfig, getMailetContext, getMailetName, init, log, log

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ClamAVScan

public ClamAVScan()

Method Detail

getMailetInfo

public java.lang.String getMailetInfo()

Return a string describing this mailet.

Specified by:

getMailetInfo in interface Mailet

Overrides:

getMailetInfo in class GenericMailet

Returns:

a string describing this mailet

getAllowedInitParameters

protected java.lang.String[] getAllowedInitParameters()

Gets the expected init parameters.

initDebug

protected void initDebug()

Initializer for property debug.

isDebug

public boolean isDebug()

Getter for property debug.

Returns:

Value of property debug.

setDebug

public void setDebug(boolean debug)

Setter for property debug.

Parameters:

debug - New value of property debug.

initHost

protected void initHost()
                 throws java.net.UnknownHostException

Initializer for property host.

Throws:

java.net.UnknownHostException - if unable to resolve the host name, or if invalid

getHost

public java.lang.String getHost()

Getter for property host.

Returns:

Value of property host.

setHost

public void setHost(java.lang.String host)
             throws java.net.UnknownHostException

Setter for property host. Resolves also the host name into the corresponding IP addresses, issues a setAddresses(java.net.InetAddress[]) and resets the nextAddressIndex variable to 0 for dealing with round-robin.

Parameters:

host - New value of property host.

Throws:

java.net.UnknownHostException - if unable to resolve the host name, or if invalid

initPort

protected void initPort()

Initializer for property port.

getPort

public int getPort()

Getter for property port.

Returns:

Value of property port.

setPort

public void setPort(int port)

Setter for property port.

Parameters:

port - New value of property port.

initMaxPings

protected void initMaxPings()

Initializer for property maxPings.

getMaxPings

public int getMaxPings()

Getter for property maxPings.

Returns:

Value of property maxPings.

setMaxPings

public void setMaxPings(int maxPings)

Setter for property maxPings.

Parameters:

maxPings - New value of property maxPings.

initPingIntervalMilli

protected void initPingIntervalMilli()

Initializer for property pingIntervalMilli.

getPingIntervalMilli

public int getPingIntervalMilli()

Getter for property pingIntervalMilli.

Returns:

Value of property pingIntervalMilli.

setPingIntervalMilli

public void setPingIntervalMilli(int pingIntervalMilli)

Setter for property pingIntervalMilli.

Parameters:

pingIntervalMilli - New value of property pingIntervalMilli.

initStreamBufferSize

protected void initStreamBufferSize()

Initializer for property streamBufferSize.

getStreamBufferSize

public int getStreamBufferSize()

Getter for property streamBufferSize.

Returns:

Value of property streamBufferSize.

setStreamBufferSize

public void setStreamBufferSize(int streamBufferSize)

Setter for property streamBufferSize.

Parameters:

streamBufferSize - New value of property streamBufferSize.

getAddresses

protected java.net.InetAddress getAddresses(int index)

Indexed getter for property addresses.

Parameters:

index - Index of the property.

Returns:

Value of the property at index.

getAddresses

protected java.net.InetAddress[] getAddresses()

Getter for property addresses.

Returns:

Value of property addresses.

setAddresses

protected void setAddresses(java.net.InetAddress[] addresses)

Setter for property addresses.

Parameters:

addresses - New value of property addresses.

getNextAddress

protected java.net.InetAddress getNextAddress()

Getter for property nextAddress. Gets the address of the next CLAMD server to connect to in this round, using round-robin. Increments the nextAddressIndex for the next round.

Returns:

Value of property address.

getAddressesCount

public int getAddressesCount()

Getter for property addressesCount.

Returns:

Value of property addressesCount.

getClamdSocket

protected java.net.Socket getClamdSocket()
                                  throws javax.mail.MessagingException

Gets a Socket connected to CLAMD. Will loop though the round-robin address list until the first one accepts the connection.

Returns:

a socket connected to CLAMD

Throws:

javax.mail.MessagingException - if no CLAMD in the round-robin address list has accepted the connection

init

public void init()
          throws javax.mail.MessagingException

Mailet initialization routine.

Overrides:

init in class GenericMailet

Throws:

javax.mail.MessagingException - if an exception occurs that interrupts the mailet's normal operation

service

public void service(Mail mail)
             throws javax.mail.MessagingException

Scans the mail.

Specified by:

service in interface Mailet

Specified by:

service in class GenericMailet

Parameters:

mail - the mail to scan

Throws:

javax.mail.MessagingException - if a problem arises

checkInitParameters

protected final void checkInitParameters(java.lang.String[] allowedArray)
                                  throws javax.mail.MessagingException

Checks if there are unallowed init parameters specified in the configuration file against the String[] allowedInitParameters.

Parameters:

allowedArray - array of strings containing the allowed parameter names

Throws:

javax.mail.MessagingException - if an unknown parameter name is found

ping

protected void ping()
             throws java.lang.Exception

Tries to "ping" all the CLAMD daemons to check if they are up and accepting requests.

Throws:

java.lang.Exception

ping

protected void ping(java.net.InetAddress address)
             throws java.lang.Exception

Tries (and retries as specified up to 'getMaxPings()') to "ping" the specified CLAMD daemon to check if it is up and accepting requests.

Parameters:

address - the address to "ping"

Throws:

java.lang.Exception

getStreamPortFromAnswer

protected final int getStreamPortFromAnswer(java.lang.String answer)
                                     throws java.net.ConnectException

Parses the answer from a STREAM request and gets the port number.

Parameters:

answer - the answer from CLAMD containing the port number

Returns:

the port number for streaming out the data to scan

Throws:

java.net.ConnectException

saveChanges

protected final void saveChanges(javax.mail.internet.MimeMessage message)
                          throws javax.mail.MessagingException

Saves changes resetting the original message id.

Parameters:

message - the message to save

Throws:

javax.mail.MessagingException