IMSpector 0.3 review

by on

IMSpector project is an Instant Messenger transparent proxy with logging capabilities

License: GPL (GNU General Public License)
File size: 29K
Developer: Lawrence Manning
0 stars award from

IMSpector project is an Instant Messenger transparent proxy with logging capabilities. Currently it supports MSN, AIM and ICQ to different degrees. MSN is the principle protocol, as it is these days the most popular.

The only supported platform is at present Linux, but porting to different UNIXs should be trivial (the only platform-specific code is the routine which determines the original destination address).

Here are some key features of "IMSpector":
Written in C++, with a minimal set of dependiancies. Nice and small code footprint - 2100 lines thus far. Plugin based.
Supports the following IM protocols via "protocol plugins":
MSN - Logging of incoming and outgoing messages.
ICQ/AIM - Supports the "new" protocol, ie. prehistoric ICQ is not supported. Currently has problems logging the local ID of messages, but it will always log the clients IP address, as it does for all protocols.
Yahoo - In development. Appears to be a fairly simple protocol so do not see any difficulties. Currently this is a "null" protocol for simple tracing and packet dumping.
Can log to various places via "logging plugins":
Files - The conversations are written to a file within a path resembling {protocol}/{local id}/{remote id}/{year}-{month}-{day}. See the NOTES section for more info.
MySQL - Can connect to a DB and dump the chats into a table. See the NOTES section for a list of "gotcha" on this. Not compiled by default.
Debug - A trivial example plugin which logs to the syslog, which when in debug mde, will end up on STDERR.
All the usual deamon things. Drop privs, a simple config file etc.


IMSpector must be run on the routing machine in the network. This would typically be the Linux box shoved in the corner doing NATing onto an Internet connection. System requirements are minimal, although with a large number of local users IMSpector will fork many copies of itself (a typical MSN connection can consist of a dozen or more worker processes.

Download the code, and untar. Currently there is no configure script, so you must configure the Makefile by hand (if needed) and run make. There are no dependancies beyond a working C++ compiler, unless you are planning to use the MySQL logging plugin. In this event you will also need the MySQL client libraries. Please note that v3 of MySQL will probably not work.

The Makefile, trivial that it is, contains one variable, PREFIX that you can set to the target dir of the install. The default is /usr, which is probably ok for most people.

Note that if you chagne the PREFIX value (say to /usr/local) you will need to adjust the plugin_dir config option to tell IMSpector where to look for plugins.

sudo make install

IMSpector is capable of setuid-ing to a non root user (indeed it has no requirement to run as root, or even be started as the root user), but the install target does not currently attempt to make a special user. Thus the default config will run as the whatever use started the program. This kind of "tidying up" is on the TODO.

This will install the files as follows:

/usr/sbin/imspector - the imspector binary.
/usr/lib/ - a shared library that the main program and plugins share.
/usr/lib/imspector/* - the protocol plugins.
/usr/lib/imspector/* - the logging plugins.
/etc/imspector.conf - an example config file, good enough for quick playing.

Note that the plugins are loaded at runtime and can use config file entries. The plugins loaded will be logged to syslog.

After compiling and installing IMSpector, the following iptables rules are required to transparently proxy the various IM ports:

MSN: iptables -t nat -A PREROUTING -p tcp
--destination-port 1863 -j REDIRECT --to-ports 16667
ICQ/AIM: iptables -t nat -A PREROUTING -p tcp
--destination-port 5190 -j REDIRECT --to-ports 16667
These commands will obviously have to be run in your startup script.
For an inital test, run the program in debug mode:
imspector -d

Login to MSN and you should see some debug output. Finally, send someone a message and it should be logged both on the console and into a logfile within the logging directory. Rerun the program without the -d switch to force it into the background.

What's New in This Release:
This release greatly improves AIM/ICQ support by properly logging the local IDs.
A content filter that can remove naughty words was also added.
IMSpector now runs on BSD (using pf).
Many other small fixes and improvements were made.

IMSpector 0.3 keywords