November 16th, 2009 Leave a comment Go to comments

IMSpector is an Instant Messenger proxy with monitoring, blocking and content-filtering capabilities. Currently it supports MSN, Jabber/XMPP, AIM, ICQ, Yahoo, IRC and Gadu-Gadu to different degrees. MSN is the principle protocol, as it’s the most popular these days, at least in the UK where I’m based. The supported platforms are at present Linux and BSD when using the pf firewall, but porting to other UNIXs should be trivial. It is able to log to plain files, as well as several types of SQL database including MySQL, SQLite and PostreSQL.

IMSpector is normally deployed on the network’s router, but other options are available.

This software is licenced under the GPL v2, with an additional exception to allow linking with OpenSSL.  The original author and copyright holder is Lawrence Manning.

The program is currently somewhere between alpha and beta quality, but the following features have been implemented and at least work to some degree:

  • Written in C++, with a minimal set of dependiancies. Nice and small code footprint – 7000 lines thus far. Plugin based.
  • Supports the following IM protocols via “protocol plugins”:
    • MSN – Logging of messages and file transfers.
    • Jabber/XMPP – Logging of messages and file transfers. If told do so, IMSpector will proxy the TLS/SSL handshake, via the so called man-in-the-middle attack method, and present the client with it’s own certificate, create on demand, instead of the servers. Therefore Google’s Gtalk (and other encrypted Jabber sessions) can be monitored.
    • ICQ/AIM – Supports the “new” protocol, ie. prehistoric ICQ is not supported. AIM over SSL is supported, via the same man-in-the-middle interception method as described above.
    • Yahoo – Logs chats and filetransfers. Also supports webcam events. Nice and easy protocol to examine.
    • IRC – Kind of “play thing”. Logs channel and private messages. Currently proxying this protocol through IMSpector will break DCC SENDs.
    • Gadu-Gudu – A protocol popular in Poland, this plugin currently only supports the logging of text messages.
  • 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 Configuration section for more info. There is also a minimal file logging plugin which logs only the filtered messages.
    • MySQL – Can connect to a DB and dump the chats into a table. Not compiled by default.
    • SQLite – Can log to a local SQLite DB file. Requires sqlite3. Not compiled by default.
    • PostgreSql – Can connect to a DB and dump chats into a table. Not compiled by default.
    • Debug – A trivial example plugin which logs to the syslog, which when in debug mde, will end up on STDERR.
  • Can filter in various ways via “filtering plugins”:
    • Content manipulation. Replace bad words with a user defined character. All protocols supported by IMSpector can be filtered in this way.
    • Can block messages and other events based on an ACL. A database-backed filter (which uses SQLite) is able to automatically add remote users to the whitelist when local users send them messages.
    • Can also blanket block file transfers (all protocols beside Gadu-Gadu) and webcam events (Yahoo only at present).
    • Off-load the filtering and censoring decision to an external program via a UNIX socket and a simple API.
  • Can inject messages into chats for the purpose of notifying IM users that their chats are being monitored. Every protocol except ICQ/AIM is supported.
  • All the usual deamon things. Drop privs, a simple config file etc.

Logging my chats? You are evil!

Possibly. You may be wondering why people would want to log IM conversations on the network. Well, yes clearly there is an avenue for abuse with this program. Spouses can use it to spy on each other. Parents can use it to spy on their teenagers. Bosses can spy on their staff. The list is endless. However, there are legitimate reasons why people would want to log IM chats, so this tool has been written. At this point it should be pointed out that as IMSpector is a proxy and not just a traffic-snooper; other things beyond simple logging are possible, such as AV scanning of file transfers. See the Todo list for more information. As of 0.4, IMSpector can both block messages based on the parties making the chats, and it can also block file-transfers, keeping bad files out of your systems.

In addition, some people may be of the opinion that if they cannot monitor use, they must block it. But blocking something can lead to conversations simply being made by other channels. Logging means the user’s freedom to use IM is maintained, while giving the parents, teachers, etc, the knowledge that if they need to look at the chat logs for whatever reason, they can. So in some situations, IMSpector actually stimulates IM use.

Another use of this program is so an IM user can log his chats at a central location. If she uses multiple machines at multiple locations, IMSpector makes it easy to log all chats by proxying through it using a frontside proxy such as squid.

If you are really interested in your privacy then you should be using some kind of end-to-end encryption on your IM sessions. See the links elsewhere on this page for some IM encryption software.

Warnings and Limitations

This software should be considered beta quality at best. It has not been audited by anyone, including myself. That said, I have had it running on my machines for a couple of weeks and it now seems reliable – hence I am releasing it to the wild to see if there is any interest.

Note that some things are missing, noteably MSN over HTTP support. This means that if you wish to log people using MSN, you should probably also block HTTP traffic from getting to the MSN servers. How you do this depends on lots of factors, so you will have to work that out yourself. There may well be other ways to get around IMSpector chat logging. In addition, IMSpector may make a mess of logging group chats, which some IM protocols support.

  1. r.roeleveld
    January 27th, 2009 at 15:01 | #1

    I would like IMSpector installed on my proxy server which is not the router in my network. Is this possible and how would I configure MSN? At the moment I’m trying this out with Smoothwall and have MSN configured to use HTTP Proxy on port 800, however no messages are being logged.

    Kind regards..

  2. lawrence
    January 27th, 2009 at 17:16 | #2

    The official Microsoft MSN client, when configured to use a HTTP proxy, connects to the MSN servers using HTTP GET requests. There’s are not understood by IMSpector as it only understands the “real” MSN protocol on port 1863, not the inefficient GET-based protocol.

    Other clients, eg. pidgin and Adium more sensibly use the CONNECT method when they connect through a HTTP proxy, and those clients can be used with IMSpector’s built in HTTP proxy port.

    There may be other methods. A SOCKS server could be put inline with the IMSpector box (or even on the same machine) and the connection forwarded through IMSpector using iptables rules similar to those described at the bottom of the Install page. In this mode the client will generate real MSN packets, but through the SOCKS server.


  3. raviela
    February 17th, 2009 at 01:53 | #3


    Excuse my bad english.

    I try to use imspector on smoothwall.
    but when MSN do petition on imspector, i have this error:

    imspector Error: Don’t know how to handle connection to login.live.com:443

    How i can resolve?.


  4. February 17th, 2009 at 21:35 | #4

    What version of SmoothWall? Perhaps you should send your query directly to them. It sounds like you’re accessing the IMSpector through a proxy?

  5. raviela
    February 18th, 2009 at 01:45 | #5

    My version is SmoothWall Express 3.0-polar-i386.

    and it’s exactly. I have squid proxy, on port 3128.
    and redirect to 16667. on debug mode, imspector show me the activities on the protocol.

    then, disconnect in :

    imspector Error: Don’t know how to handle connection to login.live.com:443

    this is by the proxy?

    if I want use not proxy, only with port 1863. how i can do it?

  6. February 18th, 2009 at 07:41 | #6

    Simple: don’t configure the MSN client with proxy, but have it connect directly through the SmoothWall. The MSN client will then use port 1863.

  7. raviela
    February 18th, 2009 at 17:02 | #7

    Ok. I try to use directly, by socks, on port 1863, redirect to 16667.
    with pidgin and live msn. in debug mode, i have this:

    imspector Error: Don’t know how to handle connection to

    what I do it wrong?

    Muchas gracias.

  8. February 24th, 2009 at 21:54 | #8

    It sounds like you are connecting directly to IMSpector. You might need a -t nat -A OUTPUT redirect, as explained on the installation page. If your socks proxy and IMSpector are running on the same machine, you will need a -j REDIRECT rule in OUTPUT to direct the outgoing traffic from SOCKS into IMSpector.

  9. dieu
    March 11th, 2009 at 18:31 | #9

    @ lawrence
    Maybe you could configure squid to proxy HTTPS conections that involved to MSN (ips or .msn.com domain) to https proxy port of imspector. Just Wondering.

  10. mini-casper
    July 14th, 2009 at 04:39 | #10


    Excuse my bad english.

    There is a problem in displaying icq logs in imspector.cgi both in UTF-8 and WIN-1251 formats. Is it possible to make imspector recode everything in one format (e.g. UTF-8-) at once?


  11. July 14th, 2009 at 14:49 | #11

    This problem should be fixed in IMSpector 0.8. Are you using the latest version?

  12. mini-casper
    July 15th, 2009 at 00:45 | #12

    I used imspector version dated 2009.07.14. The site default setting is UTF-8. the browser setting is also UTF-8. Here is what we have:

  13. July 15th, 2009 at 09:14 | #13

    Could you email me the contents of the log file? Or else have a look yourself to see if those lines are the UTF-8 encoded. Basically we need to figure out if the problem is with the logviewer CGI or with the log files IMSpector is making.

  14. mini-casper
    July 16th, 2009 at 04:06 | #14

    In the log file the lines are both UTF-8 and WIN-1251 encoded. I think the problem is in the IMSpector.

  15. weldan
    July 19th, 2009 at 17:38 | #15

    I’ve created .deb package of imspector which can be found at http://mweldan.net/mambang/debian/imspector/ . thanks

  16. km
    August 13th, 2009 at 06:59 | #16


    I have a problem with IMSpector 0.9.
    When I running the program in debug mode:

    imspector -d
    imspector: Protocol Plugin name: ICQ-AIM IMSpector protocol plugin
    imspector: Logging Plugin name: Debug IMSpector logging plugin
    imspector: Non-HTTP port listening on
    imspector: Logging Plugin name: File IMSpector logging plugin
    imspector: Non-HTTP connection from:
    imspector: Redirect address, PF (/dev/pf) open failed: No such file or directory
    imspector: Check permissions on /dev/pf. IMSpector needs read/write privileges.
    imspector: Client is connecting to:
    imspector: Error: Don’t know how to handle connection to
    imspector: Finished with child:

    I don’t have pf. I use ipfw.
    How fix? What rules need for ipfw? Working IMspector with ipfw?

  17. W1R0X
    August 31st, 2009 at 07:57 | #17

    Another use of this program is so an IM user can log his chats at a central location. If she uses multiple machines at multiple locations, IMSpector makes it easy to log all chats by proxying through it using a frontside proxy such as squid.

    Can you tell how can I use this feature on my server. Because it is definitely usefull for me. But in the internet there are only servers that requiring payment and I’m not sure that my privacy will be safe.

    You mean that I can connect throuth my proxy.. but my mobile phone im client can’t do it. If there possibility to connect directly to server throuth IMSpector?

  18. August 31st, 2009 at 12:25 | #18

    The way to do central logging is by putting a HTTP or SOCKS proxy infront of IMSpector. So the client connects to (say) SOCKS proxy and then the SOCKS proxy connects through IMSpector, allowing you to log all messages centrally. The limitation of this is that the client has to be ale to act as a SOCKS client, and it seems unlikely that a mobile-phone based client could.

  19. sosmicro
    October 20th, 2009 at 16:06 | #19

    hi. i have imspector installed on smoothwall 3sp1. proxy non-transp port 3128, and FFC instaled….I log every msn chats, but no sucess to log gtalk (gmail chat). give the way to do this (log gtalk)…

  20. October 20th, 2009 at 18:18 | #20

    Did you install the certificate? You need to export the SSL certificate and then import it into each client. This is because gtalk uses SSL and you must run the IM proxy in SSL man in the middle mode.

  21. mammadshah
    November 4th, 2009 at 02:43 | #21

    can i log Skype communication (chat ) ??

  22. studebakercromwell
    November 14th, 2009 at 14:33 | #22

    Genius product. Thanks for making it!

    Works great, but I’ve noticed that it doesn’t seem to grab AIM messages from the new client (7.0 on Windows, I think it’s 2.0 on Mac). Do you know anything about this?

    I’ve looked at the packets with tcpdump, briefly. On Mac there is a lot of noise but the buddy name and text of the message is there when dumping as ASCII. On Windows the buddy name appears but the message appears to be noise (simple encryption?).

    Anyway, just wondering if you’ve seen this. I don’t know much, but maybe I can help.


  23. November 16th, 2009 at 11:53 | #23

    Skype is a proprietary protocol that uses end-to-end encryption. So in short, you cannot log Skype. If IMSpector could log Skype I would be very rich….

  24. November 16th, 2009 at 11:54 | #24

    Unfortuantely AIM 7 is a completely different protocol, and it uses some encryption. IMSpector doesn’t support it yet, and it looks like alot of effort to decode it. If you want to help then feel free to drop me a mail: lawrence at aslak dot net.

  25. jakal
    November 18th, 2009 at 06:10 | #25

    привет, у меня есть пропатченная версия IMSpector, которая автоматически транслирует кириллические кодировки в utf8

  26. jakal
    November 18th, 2009 at 06:14 | #26

    >Is it possible to make imspector recode everything in one format (e.g. >UTF-8-) at once?
    It is possible, i have version of IMSpector, which translate all cyrillic encodings to utf8 :)

  27. jakal
    November 18th, 2009 at 06:18 | #27

    lawrence, tell me please – is there any frontend to mysql database of IMSpector? thanks

  28. gkarasoy
    November 23rd, 2009 at 10:19 | #28


    Im try to use SmoothWall (SmoothWall Express 3.0-polar-i386 /update5-i386)
    IMSpector is good. But today IMSpector not working, Today im Checked Smoothwall/System Logs/IM Proxy logs see this logs.

    12:01:48 imspector Protocol Plugin name: Gadu-Gadu IMSpector protocol plugin
    12:01:48 imspector Protocol Plugin name: ICQ-AIM IMSpector protocol plugin

    How i can resolve this problem ?

    12:02:49 imspector Error: Unable to log an event (1) via File IMSpector logging plugin

    Sorry :) My English is bad but
    IMSpector is perfect :)


  29. November 23rd, 2009 at 17:42 | #29

    The only cause I can think of for this is a full disk. Is your /var/log partition full? Also, check that the dir /var/log/imspector exists. If not, make it:

    mkdir /var/log/imspector
    chown imspector:imspector /var/log/imspector

    Hope that helps….

  30. November 23rd, 2009 at 17:45 | #30

    I thnk some people have made a frontend for viewing IMSpector MySQL tables, but nothing has been given to me to include in the package. It would be great if someone could write one and send it to me so I can include it… Perl, PHP, python.. all are fine with me so long as it works. :)

  31. jakal
    November 24th, 2009 at 06:38 | #31

    It would be really great…

  32. mini-casper
    November 30th, 2009 at 02:55 | #32

    Буду очень признателен если поделишься своей пропатченной версией или патчем :) можно ссылку можно на мыло [email protected]

  33. cvdm
    December 4th, 2009 at 03:15 | #33

    I have a squid/dansguardian proxy server (on ubuntu 8.04). Its not network gateway just a proxy. Clients have http proxy settings in IE connections settings and connect to 8080 port of dansguardian and cannot be changed in live messenger to use different port (I gave it a good search). Is there any way i can make this work?

  34. Yuhan
    December 8th, 2009 at 10:51 | #34

    lawrence hi!
    i use imspector on my proxy for collect AIM/ICQ messages! but my users with official version ICQ programm not insert in history. Imspector not see official ICQ programm.
    Miranda and QIP its ok.

  35. December 8th, 2009 at 15:06 | #35


    I have pfSense 1.2.2 dev and full updates are configured. I install and
    configured only imspector and Squid.

    I set Client gateway to pfsense’s lan ip adress and imspector successfully logs msn but when I set proxy adress to clients internet Explorer and remove the gateway (I must use another gateway for routing) and port 3128 imspector stops logging.How can I configure imspector to work with Squid.

    My imspector.conf and pictures;

    Thanks for your Relation.

  36. SiNNeR
    December 26th, 2009 at 14:10 | #36

    I want use IMSpector with Socks5 server(i want save jimm messages). But when i try connect to socks server, it use all RAM. And imspector says: “imspector: Non-HTTP connection from:
    imspector: ICQ-AIM: uin: Unknown, unknown family: 0017 subtype: 0006
    imspector: Client is connecting to:
    imspector: Finished with child: ” many times. Client trying to connect, but fail. What i do wrong?

  37. SiNNeR
    December 26th, 2009 at 14:11 | #37

    Using IMSpector 0.9 and imspector-20091226

  38. sanderss
    December 28th, 2009 at 09:37 | #38

    Hello i have problem with gg plugin it dosent work with new version of client is any posibility to upgrage this protocol ??

  39. Strafer
    January 15th, 2010 at 12:27 | #39

    Users connect to ICQ to port 443 via a proxy server squid (port 5190 is not allowed). Squid listens on port 3128. In iptables added the following line
    -A OUTPUT-m tcp -p tcp –dport 443 -m owner -uid-owner 23 -j REDIRECT –to-ports 16667
    To work requires launched imspector or error connections in ICQ clients.
    When in imspector.conf comment “https_protocol = on” no connect, else all connected work, but logging is not conducted.
    I start imspector-d and I get the following message(https_protocol = on)

    imspector: Non-HTTP connection from: x.x.x.x:57392
    imspector: Client is connecting to:
    imspector: HTTPS: Got: 61
    imspector: HTTPS: Got: 341
    imspector: Finished with child: x.x.x.x:57392

    Excuse my bad English

  40. January 15th, 2010 at 19:40 | #40

    IMSpector understands the “real” IM protocol, not the IM protocol in HTTP format, which is what the client will be sending if it is going through Squid. Why is port 5190 blocked?

  41. January 15th, 2010 at 19:40 | #41

    Yes, this is a known problem. I am waiting to get some captures of the packets so I can fix IMSpector. Are you able to help?

  42. Strafer
    January 18th, 2010 at 06:32 | #42

    Because it was done for safety, since port 443 is a secure connection. And now we have the opposite:). I have unblocked port 5190 and it was working. But nevertheless I would like to work for 443.

  43. Strafer
    January 18th, 2010 at 12:06 | #43

    But, only pidgin and icq clients. If client QIP
    imspector: ICQ-AIM IMSpector protocol plugin: Warning, unknown message string type: 46
    imspector: ICQ-AIM: Error: Unable to parse snac packet, icq.14229.85

  44. January 18th, 2010 at 17:30 | #44

    @strafer – unfortuantely that traffic on port 443 is not the same traffic as on port 5190, it will be IM requests in HTTP GET requests, which IMSpector does not understand because it knows nothing about HTTP….

    Security is more then blocking ports. :)

  45. January 18th, 2010 at 17:31 | #45

    @Strafer – Not heard of that client. You’ll need to send me some packet captures. If you want to help, send me a email and I’ll tell you how to do some packet captures.

  46. tk65er
    March 24th, 2010 at 17:37 | #46

    Um, is there any chance of adding facebook chat capturing??

  47. Pete
    March 26th, 2010 at 09:10 | #47

    Good day,

    Love the program, works superbly. I do have one feature request: can you add Facebook Chat to Imspector?



  48. May 13th, 2010 at 17:24 | #48

    @ Pete
    I think we should begin reading a good implementation

    this code is clear engouht

  49. cassioseffrin
    May 14th, 2010 at 12:35 | #49


    I’m looking for a free software to block files in msn protocol. I want to allow only the text chat.

    The imspector is a great project, until now the best free code for manager the MSN that I found, but even when I set the in imspector.conf the parameter block_files=on the files can be transfered.

    I made some research to block the file transfer in msn protocol. Here I found some information that describe how MSN work to prevent the file transfer block:

    1. For two buddies, if one of them is connected to internet directly, direct connection will be established to transfer files. This is the quickest way. There has three type of direct connections with dynamic ports which is negotiated by two sides.

    1.1) Direct TCP connection.

    1.2) Direct TCP connection use TLS encryption.

    1.3) Direct UDP transmission.

    2. If direct connection can not be established, msn servers can act as a relay server to transfer files. The file transfer packets will be among with normal msn messages.

    As you can see from above, there is no way to block msn file transfer simply by blocking some ports in the firewall. The firewall should be smart enough to recognize msn file transfer direct connections, and it shall be able to pick up file transfer packets from normal msn messages.

    There is some way to block any files? Maybe I can help with any task in this project if this is possible.

    Best Regards,

    Cássio Seffrin

  50. maxleonca
    June 9th, 2010 at 17:30 | #50

    I wonder if you can help me out here, I’m trying to build IMSPECTOR on NetBSD, and as you mention on the INSTALL instructions I checked the Makefile. The question might be a bit dumb but you just mention OpenBSD and FreeBSD and while I comment out the lines on the make file I have no luck building it.
    Any suggestions?

    Thanks so much

Comment pages
1 2 2
  1. No trackbacks yet.
You must be logged in to post a comment.