Mailbot - IRC messaging system

Frequently, IRC channels are used as a collaboration tool. Due to the real-time nature of IRC, it is hard to keep up with events when you are offline. The Mailbot script solves that problem. It provides a unified messaging service in form of an interactive IRC bot. Users are able to post to messages to channels, for other users to come and read them later. As well, the script allows the users to send private messages to each other. This is useful in cases where the recipient is not online, yet a message be sent to him/her (just like offline messages in ICQ).
The service is implemented as a TCL script for eggdrop. It uses sqlite for the backend database storage, and AES for encryption. It has extensive search capabilities.

Example Scenario

This scenario presents a typical usage pattern of the bot: users posting messages, and other users reading them at a later time. Suppose we have a channel #cooltalk, with 3 regulars: Bob, Alice and Jeff.
Users Bob joins channel #cooltalk, and posts an announcement using the bot:

(in #cooltalk)
<Bob> !mail add Hey guys! I will be away next week so please forward all your concerns about the project to Jeff.
<MAILBOT> Message number 1 posted to channel #cooltalk.
* Bob has left the channel

At this point, the mail bot stores the message in the pool for channel #cooltalk, so other users can read it.

Now, a bit later, Alice joins #cooltalk. She receives a private message from the mail bot telling her that she has unread mail:

(in private query with MAILBOT)
<MAILBOT> You have unread mail.
<Alice> !mail read
<MAILBOT> MESSAGES TO #cooltalk
<MAILBOT> 1. 26.10.2007 15:42:27 Bob: Hey guys! I will be away next week so please forward all your concerns about the project to Jeff.

Then, Jeff joins the channel and reads the same message. He has a personal question to Bob about the project. However, Bob is offline. So, Jeff sends a private message to Bob using the mail bot (in private query):

(in private query with MAILBOT)
<Jeff> !mail send Bob Listen Bob, there was a problem with the project. The database is corrupted.
<MAILBOT> Private message number 7 sent to user Bob.

Bob, an incurable IRC addict, joins IRC but wants to stay away from #cooltalk so no one bothers him. However, he can still interact with the mail bot:

(in private query with MAILBOT)
<Bob> !mail read
<MAILBOT> PRIVATE MESSAGES
<MAILBOT> 7. 28.10.2007 11:12:55 Jeff: Listen Bob, there was a problem with the project. The database is corrupted.

Installation

The installation of the script involves the installation of the prerequisites (tcllib, sqlite), the actual TCL script, as well as tweaking the configuration files.

Installation of the Prerequisites

Mailbot requires the following prerequisites: Tcllib and the SQLite TCL bindings.
Tcllib comes standard on recent Tcl installations. Specifically, mailbot uses the aes, base64, and crc packages from tcllib. So, if you do not want to bother install all of tcllib, you can just copy the directories of those packages and include them in the eggdrop configuration file for your bot (described in detail later).
The SQLite TCL bindings are required so the mailbot script can use sqlite databases. The script has been coded against version 3 of sqlite. Typically, the name of the bindings library is libtclsqlite3.so on UNIX, and something like tclsqlite3_5_0.dll on Windows.
There is a commercial version of SQLite that allows databases to be password protected. Such version is not needed for the mailbot, as it implements its own encryption layer on top of the free version of sqlite using tcllib's aes and base64 packages.
If you have trouble loading the sqlite bindings binaries into your bot, and receive weird error messages like tclsqlite-3.5.1.so: undefined symbol: sqlite3StrICmp, then you should probably download the source code to sqlite, compile it yourself, and use the libtclsqlite3.so.0.8.6 binary instead (it should compile into the .libs directory in the sqlite source tree).

Installation of the TCL Script

This step describes how to install the actual mailbot TCL script into your eggdrop bot.

Unpack mailbot-1.01.tar.gz into eggdrop/scripts. This will create eggdrop/scripts/mailbot-1.01 that will contain the TCL files.

Edit the eggdrop configuration file for your bot: include the sqlite module and the script:

#
# Load the sqlite TCL bindings module.
# N.B. Read the 'Installation of Prerequisites' step above in detail,
#      if you encounter errors when executing this line.
#
load libtclsqlite3.so

#
# Include the tcllib prerequisites.
# If you have the Tcllib normally installed, you may replace
# these with 'package require' lines instead, like so:
#
#   package require aes
#   package require base64
#   package require crc
#
# Though, source lines work just as well :P
# Just be sure to adjust the paths to suit your system.
#
source tcllib1.10/aes/aes.tcl
source tcllib1.10/base64/base64.tcl
source tcllib1.10/crc/crc32.tcl

#
# Finally, include the mailbot script.
# N.B. The scripts/ subdirectory is relative to your location
#      of your eggdrop binary.
#
source scripts/mailbot-1.0/mailbot.tcl

Configuring Mailbot

The mailbot package comes with two TCL files: mailbot.tcl - the actual code, and mailbot-options.tcl - the configuration file for the script. It is included into mailbot.tcl by mailbot.tcl on line 13. It contains 2 variables that you should change - the path to the database file which will store all the messages, as well the top-level command that access the mailbot functionality. This is usually set to !mail or !news.
```
###############################################################################
# mailbot-options.tcl - options for mailbot.tcl
###############################################################################

#
# Path to the database file
#
variable db_path "/home/comrade/eggdrop/mail.db"

#
# Public access command name
#
variable pub_cmdname "!mail"
```
Copy blank.db to the database path that you specified above, and make the file writable.

This concludes the installation.

Working with Mailbot

This section deals with interacting with the mailbot script once it is up and running on top of an eggdrop bot.

Initializing the Database

Upon running the bot, the mailbot script needs to be initialized by a bot administrator (anyone with +m or +n flag on the bot). This is done by messaging the bot in private:

(in private query with MAILBOT)
<BotAdmin> !mail init 0 bigapple.
<MAILBOT> Database not initialized: checksums do not match. The correct checksum for bigapple is 243.
<MAILBOT> NOTE: Initializing the database with the incorrect password can inflict irreparable damages. Please double-check the password or the checksum for typos.

<BotAdmin> !mail init 243 bigapple.
<MAILBOT> Database initialized.

This step is necessary to keep the database password out of the configuration file. If the password would be hardcoded anywhere in the configuration or the script, anyone with shell access can find out the password. Note: this step has to be repeated every time the bot is rehashed or restarted.
The purpose of the checksum is to prevent typos.
If you would like to skip this step, and hardcode the database password into the configuration file, you may add the following line to the end of mailbot.tcl:

#
# Automatically initialize the database with the password 'bigapple'.
#

mail::initialize "bigapple"

Be aware of the security risks associated with doing so.

User Authentication and Authorization

The mailbot script uses the built-in eggdrop userbase to authenticate users. The user's handle on the bot is used as the user's name when posting messages.
A user's channel access is determined by the user's channel record on the bot. Any user with a +v flag on the channel is allowed to send/receive messages from that particular channel. However, private messages can be sent/received by the user without any particular channel access records.
Superusers are the users that are able to initialize the database. Any user with a +m or +n global flags on eggdrop is considered a superuser.

Sending and Reading Messages

To get help on sending, and reading messages, please invoke the help menu from the bot directly by typing !mail help (substitute !mail with your own command if you changed it).

Searching Messages

The mailbot script features extensive search capabilities with many ways to filter the results. The search feature can be accessed through the !mail search [filters] [keywords] command. Keyword matching is case-insensitive.
The possible filters are:

-before:YYYY-MM-DD to search only messages before a specific date.
-after:YYYY-MM-DD to search only messages after and including a specific date.
-ago:num_days to search only messages from up to num_days ago.
-from:user to search only messages sent by the user user.
-to:channel to search only messages sent to the channel.
-any to make the filter match any one of the keywords from the list. if not specified, all keywords must be matched.

Examples:

!news search -before:2007-11-01 -after:2007-10-01 -from:leonidas this is sparta
searches for all mail for the month of October 2007, sent by leonidas, and containing all of the keywords this, is and sparta (not necessarily in that order).
!news search -any color flavor
searches for all mail containing either the keyword color, or the keyword flavor.
!news search -to:#cooltalk database
searches for the mail sent to channel #cooltalk containing the keyword database.

Adjusting Time Zone Settings

You can adjust the local time zone with the !mail timezone <+/- minutes> command. The offsets are relative to the bot's local time (unfortunately, TCL does not provide UTC time, so the offsets are guesswork unless you know where the bot is). For example, if the bot displays times that are 1 hour ahead of my time, I would simply type !mail timezone -60 to make the adjustment. The offset is in granularity of minutes, which makes it compatible with Venezuela.

Notes On Security

Here is a brief note on security. By default, mailbot encrypts both names and messages using the same database password. The security of the database password is determined by the weakest link. If the attacker (one who wishes to crack the database password) can find out anything about the context of encrypted data, then it is much easier for him to guess the password. For example, if the attacker knows that certain users use the mailbot, then he can try to work out the password by guessing the plaintext of the encrypted users in the database. The search field for this guess is fairly small and the attack would probably be able to guess the password in the matter of minutes, with the right tools and automation.
The users who use the mailbot can be easily retrieved from the eggdrop userfile. Hence, if the attacker has access to the eggdrop userfile, it is best to turn off encryption of names in mailbot. This can be done by setting the variable option_encrypt_names around line 25 of mailbot.tcl to 0. This has the obvious disadvantage of exposing the usernames in their plaintext form in the database file, but theoretically can provide better security for the message contents.

Download

mailbot-1.02.tar.gz (8 KB)

Older versions:
mailbot-1.01.tar.gz (8 KB)
mailbot-1.0.tar.gz (8 KB)

The project is released under the BSD license.

Subversion

The subversion repository for the project can be accessed here: http://mailbot.svn.sourceforge.net/viewvc/mailbot/.

Changelog

The changelog can be also be accessed here: http://mailbot.svn.sourceforge.net/viewvc/mailbot/trunk/?view=log.

------------------------------------------------------------------------
r6 | comrade64 | 2007-11-07 20:29:05 -0500 (Wed, 07 Nov 2007) | 4 lines

version 1.02:
- fixed decryption bug when encrypted data started with a '-'
- fixed version number in help output

------------------------------------------------------------------------
r4 | comrade64 | 2007-11-01 01:31:59 -0400 (Thu, 01 Nov 2007) | 4 lines

version 1.01:
- fixed aes encryption oddity on some strings
- fixed bold irc string escaping on some strings

------------------------------------------------------------------------
r2 | comrade64 | 2007-11-01 01:29:32 -0400 (Thu, 01 Nov 2007) | 1 line

initial import of mailbot-1.0

References

Mailbot SF.net Project Page - mailbot at sourceforge.
Eggdrop - The official home of Eggdrop development and the Eggdev team.
SQLite - The official homepage of SQLite, the embedded database engine.
Tcllib - The core development home for the tcllib standardized Tcl library.