author: jose_at_monkey.org

license: 3-clause BSD.

freshmeat entry

vthrottle is an implementation of m. williamson's rate throttling mechanism for mail bourne worms and viruses. basically the software keeps track of what hosts and what senders have been sending mail. if they attempt to send mail from one machine or using one address more than once in a specified interval we back them off by sending a temporary failure. well behaved hosts are expected to not trip this detection/throttle ...

vthrottle works by evaluating mail transactions at three points: the connection, the HELO (or EHLO) statement, and the stated source address of the mail. for each of these, a list is traversed and the observed time interval between observations is evaluated. if the observed interval is shorter than the policy interval, the mail is blocked. this is accomplished by sending a failure reply code to the SMTP client, causing them to queue the message.

a whitelist may be used to create exceptions to the default intervals. this whitelist can specify hostnames or mail addresses and specifies the expected interval for that entry. the tool vmeasure can be used To generate this whitelist based on observations on your network. this tool is included in the vthrottle distribution.

the threat model for this tool requires a generic solution. hosts infected with a worm which uses mail to spread will attempt to send as much mail as possible to spread rapidly. to prevent this system from becoming overwhelmed by requests, only header information is recorded and acted upon.

when a host is throttled, entries like this will appear in the system logfiles:

    Jan 25 00:20:42 gibbs vthrottle: throttling host localhost: observed interval: 10, expected: 60 

a big hearty thank you to matt williamson and the HP management team for being ok with an independent implementation being developed and released. their technique and implementations are patent pending. this is just an approximation of their methods. two relevant papers to this tool are:

Williamson, M. HP Labs Tech Report HPL-2002-172

Twycross, J., and Williamson, M. in Proc. 12th USENIX Security Symposium, pp 285-294.

requirements

vthrottle requires that the following libraries be available: POSIX threads (aka pthreads) and libmilter. for runtime, a sendmail binary built with milter support must be used, and a configuration addition must be made to the sendmail configuration.

because vthrottle uses libmilter, it will not work with other MTAs, it will work only with sendmail.

vthrottle currently depends on a few OpenBSD specific functions, including strsep(), openlog_r() and syslog_r(). porting vthrottle to other platforms is being worked on.

to do

• implement network based whitelisting (netblocks, not domain names). eg: 10.0.1.0/24 20 (netblock 10.0.1.0/24 has a 20 second interval to respect).

installation

build the milter using the Makefile. you may have to adjust your paths, it's set up for OpenBSD's default paths to the milter include files and their sys/queue.h file (for linked list macros). a copy of sys/queue.h is included here for convenience.

add lines similar to the following to enable vthrottle's use:

 INPUT_MAIL_FILTER(`filter1', `S=unix:/var/run/milter/vthrottle.sock, F=R')
 define(`confINPUT_MAIL_FILTERS', `filter1')

download

version 0.60: november 15, 2006 vthrottle-0.60.tar.gz

version 0.55: march 8, 2004 (beta release for testing) vthrottle-0.55.tar.gz

version 0.54: june 3, 2004 vthrottle-0.54.tar.gz
minor bugfix:

• correctly report the number of times a host has been throttled

related software

• relayd for QMail
• anvil for postfix