MailRecon SMTP Content control system

	version 1.1

Starting and stopping mailrecon
-------------------------------
Usage: mailrecon [ -d | -k ]

-d : run as daemon
-k : kill running mailrecon daemon

When started, mailrecon reads config file mailrecon.conf in current directory.
For capturing messages, mailrecon forks into two processes. One of them ("slow")is used for most operations, other ("fast") used only for packet capturing.
So, "pidof mailrecon" should always show 2 pid's.


Reading captured messages
-------------------------
All captured messages are stored in /usr/local/mailrecon/Maildir. 
1. You can use unix mailreader with maildir support to read it. e.g. mutt -f /usr/local/mailrecon/Maildir
2. You can use POP3/IMAP server (e.g. Dovecot) with maildir support to make this maildir available over network and download all messages into your mail reader.
3. You can use use webmail system (e.g. SquirrelMail). Webmails ofter works via POP3/IMAP server, so you may need to install it too.

Configuration
-------------
mailrecon.conf is main configuration of mailrecon sniffer.
example file:

[SNIFFER]
device=eth0                         <-- listen eth0 device
promiscous=0                        <-- do not set device in promiscous mode
filter=tcp and port smtp            <-- filter string in pcap format (tcpdump)
maildir=Maildir                     <-- maildir directory name from current dir
lock=/usr/local/mailrecon/mailrecon.lock  <-- filename of lockfile
user=mailrecon                      <-- user and group name. Mailrecon will drop
group=mailrecon                     <-- .. it's root privileges after start. 
bufsize=5120                        <-- size of buffer in 4k pages. (20 Mb)
snaplen=1514                        <-- max packet length to read
[LICENSE]
level=0                             <-- should be 0 for evaluation.
[CHECK]
plugin=./external.so                <-- filename of CHECK plugin.
params=script=./mailfilter.pl       <-- params for plugin external.so
[SAVE] 
plugin=./maildir.so                 <-- filename of SAVE plugin
params=Maildir                      <-- params for plugin maildir.so

Mailrecon goes with program mailfilter.pl which is used as external CHECK plugin. mailfilter.pl reads mailfilter.conf file for instructions which messages to consider as suspicios and save. Run "./mailfilter.pl --help" for help. 

Feel free to contact us if you have any questions.


Testing
-------
There is simple file "secretfile.txt" which comes with distribution. After you will install system, you can try to send this file over SMTP and check if mailrecon will capture this message.

MailRecon Sensor
----------------
Sensor does listen traffic addressed to this machine (or all traffic if
in 'promiscous' mode). Packets with SMTP traffic are captured. When sensor
captures enough packets to reassemble message, it invokes "Check" plugin to
decide if message is 'interesting' or not. If message is 'interesting',
MailRecon passes message to 'Save' plugin which can save message or just collect
statistics from this message.


Plugins
-------
Currently, there is two types of plug-ins: "Check" and "Save".
MailRecon has open architecture, so it's easy to write new plugins in
any programming language (even shell script can be used as plugin).

Check plugin gets full message text (together with additional info as "X-
MailRecon" headers). It can modify message, e.g. put additional headers, and 
then report verdict to sensor.

Check plugin called when each new message is intercepted. It can perform any analysis of message - it can check matching of message to regexps, check content of attachment files, etc. If check plugin returns "1", current message will be discarded. If "0" - it will be considered as "suspicious" and saved via save plugin. In this case, check plugin should print message (which is received from stdin) to stdout. So, plugin can modify message. You can use /bin/cat as sample plugin which do not modify message and instruct mailrecon to save all messages (because exit code of /bin/cat is always 0).


Save plugin gets invoked only for messages which was marked as suspicious by Check plugin. Save plugin received modified message text and usually save it in
some format (e.g. in Maildir) so message could be downloaded into desktop
mailreader via POP3 or viewed in webmail interface. But Save plugin can discard 
message and just record fact of message. 

Mailrecon supports two plugin types:
1. shared library (.so) Example of such plugins is maildir.c and external.c.
2. external program. external plugins are connected via first type of plugin external.c. this plugin invokes external program acording to configuration, writes text of message to stdin of plugin, reports exit code of plugin and output of plugin back to mailrecon core system. Example of such plugin is mailfilter.pl.