##########################################
AIM Sniff Copyright (C) 2002 Shawn Grimes
##########################################

**********************************************
Disclaimer: I provide this software as a public service to experienced
systems administrators who wish to protect their users from harassment while 
using instant messaging and to demonstrate the need for encryption in instant 
messenging programs.
**********************************************

1. License Information
2. Program Description
3. Important Information About This Release
4. How To Get Help
5. !!Special Requests of You!!
6. Sample Config File
7. Description of Config File Options 
8. Dependencies
9. Installation Procedure
10. Credits
11. FAQ

##########
1. License Information
##########
This program is free software; you can redistribute it and/or modify it under 
the terms of the GNU General Public License as published by the Free Software 
Foundation; version 2 of the License.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with 
this program; if not, write to the: 
	Free Software Foundation, Inc.
	59 Temple Place, Suite 330
	Boston, MA 02111-1307 USA

##########
2.  Program Description
##########
AIM Sniff is a utility for monitoring and archiving AOL Instant Messenger 
messages across a network.  You can either do a live dump (actively sniff the 
network) or read a PCAP file and parse the file for IM messages.  You also have
the option of dumping the information to a MySQL database or STDOUT. 

Another part of AIM Sniff is WAS (Web AIM Sniff) that is available as a separate 
download.  This is a web page front end to view and generate reports of captured 
AIM conversations.  This is expected to include the ability to see all conversations 
from an IP address, AIM handle, NT Username, conversations between certain time periods.  
It will allow administrators to see how often users are chatting to monitor for 
abuse.  You can also use AIM Sniff to monitor for cases of harassment or warez trading.

SWITCHES:

-C=filename <-Get AIM Sniff options from a config file
-r=filename <-Read a PCAP file instead of doing a live capture
-O=filename <-Output to a file
-HF=filename <-This will copy the list of captured name/IPs associations to a file for later use. **NEW**
-c=integer <-The number of packets to read before quitting
-d=dev <-The device to capture packets from
-f='filter string' <-String to filter on enclosed in single quotes
(DEFAULT: 'tcp and port 5190') -- Should only have to be specified if you think AIM is running on a different port
-p <-Place the device into promiscuous mode
-to=integer <-Read timeout in ms
--SMB <-Turn SMB lookups 'on' to get NT domain usernames with AIM logins, Off by default
--nodb <-Do not dump to a DB, only dump to STDOUT
--quiet <-Do not print anything but errors to STDOUT 
-D <-Run as a daemon
--getHandles <-Do not do anything with PCAP but populate the fromHandle field in the logs table (Can be used with -C above)
--dumpHandles <--Dumps the hash containing AIM Handles and IP Addresses before beginning to sniff


##########
3. Important Information About This Release
##########
	There are several very important changes to this release that need to be addressed.
T. Nelson has done quite a bit of work to ensure that this is the most stable release of AS
to date.  First, there are now processes to ensure that AS does not get stuck in an 
infinite loop for too long and eat up your CPU w/out doing anything.  We've implemented 
checks and child processes that can be restarted if they get stuck.  There are new config 
file options so be sure to read section 5 below.  There are also more dependencies needed 
now, so watch out for that.  Previous versions of the handles file (prior to 0.9) are not 
compatible with this version.
	Additionally, included in this release for the first time are two supporting files.
rc.aimsniff and install.pl.  The first is courtesy of T. Nelson and something you can use start 
and stop AS like a service.  The install.pl is a script that will hopefully help you install AS.  
	This will be the LAST time that AS is released as one giant single file.  The next 
release (1.0 finally!!!, woohoo!!! ok, it's out of my system now) will be completely 
revamped with modularized code for faster development.  It will include a boat load of AIM 
Sniff specific modules and hopefully I'll have the MSN code worked out (no promises though).
	

##########
4. How To Get Help
##########
Here are some important steps in order to get your questions answered in the most
efficient and effective way:
PLEASE FOLLOW THESE EASY STEPS:
First scan the README and make sure you didn't miss anything
Second, scan the FAQ section at the http://www.aimsniff.com forums 
	(it's only like 3 entries to read)
Third, Do a search on the forums
Fourth and most importantly, If you use windows, don't even bother 
	asking me any questions. I don't use windows so I can't help 
	you anyway.  Try the forums, there is a section just for you 
	where gnomeboy as agreed to lend a hand.
Fifth, if you have done all of the above and still can't find an 
	answer, go ahead and email me or IM me.  I will be very nice
	so long as you have followed steps 1-4


##########
5. !!Special Requests of You!!
##########
	I have a small request of those of you who actually get AS running.  I'd like to
know who my user base is.  This won't get published or anything like that (unless you 
specifically ask me too) but it's for my own personal knowledge.  Knowing who uses it will
encourage me to continue development.  Just shoot me an email to shawn@aimsniff.com with
your name, whether you use AS for personal or work, where you work (if you use it for work)
and a small comment about it ("it's too hard to setup" or "this program has made my life
so much easier").  Thanks.

	I'm currently having a slogan contest.  I need a slogan to go with my logo.  You
can submit your ideas on the aimsniff.com forum or email them to me directly.  The winner
will receive a free AIM Sniff T-Shirt with their slogan on it.  

	If you'd like to purchase some AIM Sniff gear, http://shop.aimsniff.com.


##########
6.  Sample Config File
##########
#dumpHandles=1
dumpfile=/home/aimsniff/aim.dump
outputFile=./aim.messages
handlefile=./handlesfile
#packetCount=10
dev=eth0
filter='tcp and port 5190'
promisc=1
timeout=1000
SMB=1
daemon=1
nodb=1
quiet=1
debug=0
host=mysql.server.com
user=aimuser
password=password
database=aimsniff
useSyslog=1
parentPollTimeout=10
childCPUMaxPct=80

##########
7. Description of Config File Options
##########
Any line starting with a '#' is ignored and considered a comment.

dumpHandles=1 or 0 will dump the current hash of ip address and their respective AIM handles to your selected
	output format before it begins to sniff
dumpfile=pcap_formatted_file will read the file for aim conversations instead of doing a live capture
outputFile=path_to_file will log all aim messages to that file
handlefile=path_to_file will store ip addresses and their respective AIM handles to that file for later use 
	***NOTE:  Previous versions of this file are not compatible with this version
packetCount=10 How many packets to capture before quitting
dev=interface_name the name of the interface you want to start sniffing on
filter='pcap formatted filter string' a filter you want to apply to the packet sniffing, 
	if you have AIM traffic on ports other than tcp 5190 try filter='tcp'
promisc=1 or 0 capture packets in promiscuous mode (if you don't know what that means, you probably shouldn't be using AS)
timeout=1000 shouldn't have to change this, it's the timeout period before AS will go on to the next packet
SMB=1 or 0 this option tells AS whether or not to do SMB lookups on ip addresses in order to get the AIM users NT username, 
	must have smbclient installed for this to work
daemon=1 or 0 run AS in daemon mode, duh
nodb=1 or 0 if you aren't going to use a DB, you'll need to set this to 1 (you'll still have to have DBI installed, sorry)
quiet=1 or 0 if this is set to 0, it will print messages to STDOUT
debug=0 pretty self explanatory, you'll get some of my debug messages w/ this
host=mysql.server.com your mysql database server
user=username your mysql database user
password=password your mysql database user password
database=aimsniff your mysql database name
useSyslog=1 or 0 whether or not you want to print some error messages and such to syslog
parentPollTimeout=10
childCPUMaxPct=80 Amount of cpu AS can use before it restarts itself


##########
8.  Dependencies
##########
Requires Samba to perform SMB lookup features.

Requires the following perl modules:
Net::Pcap;
NetPacket::Ethernet qw(:strip);
NetPacket::IP qw(:strip);
NetPacket::TCP;
NetPacket::UDP;
DBI;
Unicode::String qw(utf8 latin1 utf16);
Proc::Daemon;
Proc::Simple;
FileHandle;
Unix::Syslog;
GDBM_File;



##########
9.  Installation Procedure
##########
First, install the above dependencies and run './aimSniff.pl --nodb' to make sure 
you have all the necessary dependencies.

If you plan to use the database dump feature, you'll have to load the table.struct 
file into mysql.  To do this run the following commands:
mysqladmin create aimsniff
mysql aimsniff < table.struct

This will create a database named "aimsniff" with all the right tables.
Now you can create a user that has rights to this database by running mysql and
issuing:
'GRANT ALL ON aimsniff.* TO username@hostname IDENTIFIED BY 'password';'
For more info on granting access to a user see the MySQL documentation.

After all this, you should modify the aimSniff.pl file to reflect your database 
information or edit the config file.  

You can run './aimSniff.pl -h' to see a list of switches and options.


The web front end is now distributed separately as Web Aim Sniff (WAS).  It is 
written in php and designed to be used with the database options.  See the AS 
website to download the new frontend.

Enjoy and happy sniffing.


##########
10.  Credits
##########
	The code is getting cleaned up a lot so it's hard to remember who contributed what so I'm just going to list
people that have lended a hand here:
T. Nelson - Developer
David Beijersbergen van Henegouwen - Logo and aimsniff.com designer
Nick Collingham - WAS Designer
David S.
Gnomeboy - Windows Support
BLP20B - Doc Manager
Mark Anacker - Several helpful code submissions

Special thanks to http://epconline.net for hosting the AIM Sniff website.

A special note of thanks to T. Nelson who has helped considerably to clean up my code and 
aid the current developments.

Additional thanks go to Gnomeboy for helping out those poor windows users.


##########
11.  FAQ
##########
1.  Does it work on Windows?
		The program was designed for network security specialist who have a deep understanding of network 
		topology and the inner workings of internet protocols. Any network security specialist who is worth 
		his weight uses unix in some variety or flavor. Furthermore, by not writing it for windows users I 
		keep it out of the hands of the non-serious and inexperienced users who just want to spy on 
		co-workers/spouses. The program is open source, if someone wants to write a port for it to Windows, 
		they can, but I WILL NOT. 
		
		If you want to try and get it working on windows you can start with David S's reccommendations (see 
		below). If you don't know how to do that stuff, you probably should not be using this. The software is 
		meant for network security professionals. 
			
		Courtesy of David S.:
		I found after installing the perl modules and adding the below line to your code that your programs 
		works like a charm (So Far) on a Windows XP box with 1 ethernet card. 
		
		Installs for Win32 System: 
		---------------------------------------------------- 
		#WinPcap & DLLs http://winpcap.polito.it/install/bin/WinPcap_3_0.exe 
		
		#Win32 version of Net::Pcap & Utils 
		ppm install http://www.bribes.org/perl/ppm/Net-Pcap.ppd 
		
		#Win32 version of MySql Production 4.0.13 http://www.mysql.com/downloads/mysql-4.0.html 
		
		#AIMSniff-0.8 http://sourceforge.net/project/showfiles.php?group_id=61413 
		----------------------------------------------------------- 
		
		## MYCODE Use Net::Pcap to lookupdev and set device to $dev 
		## In my case, I only have one NIC on a Windows XP Machine 
		## Also removed the Proc::Daemon 
		
		#use Proc::Daemon; 
		$dev=Net::Pcap::lookupdev(\$err); 
		## ----------------------------------------------------------# 
		## Your Code continues 
		dev='eth0' if(!defined($dev));
		
2.  When I run it, I get "Can't locate..."?
		Alright, to install perl modules... 

		From the terminal windows (aka command line): 
		perl -MCPAN -e shell 
		install MD5 
		install Bundle::CPAN 
		
		^^^The above commands will update your CPAN program, this program is used to install most of the 
		perl modules (emphasis on most). 
		
		After that is updated and while still inside of CPAN you'll want to run the following commands to 
		install the necessary perl modules: 
		install Proc::Daemon 
		install FileHandle 
		install NetPacket::Ethernet 
		install Unicode::String 
		install Bundle::DBD::mysql 
		
		Net::Pcap is a problem child for cpan for some reason, to install Net::Pcap, exit out of 
		CPAN ('quit') and download the Net::Pcap module: 
		wget http://search.cpan.org/CPAN/authors/id/T/TI/TIMPOTTER/Net-Pcap-0.04.tar.gz 
		tar -xzvf Net-Pcap-0.04.tar.gz 
		cd ./Net-Pcap-0.04 
		perl Makefile.pl 
		make && make install

3.  Does AIM Sniff work on switched networks?
		Yes, you can either setup a monitoring port on your switch, or you can use something like 
		ettercap to do arp poisoning (see ettercap docs for more info, 
		http://freshmeat.net/redir/ettercap/2432/url_homepage/ettercap.sourceforge.net), or you can setup 
		AIM Sniff on an Internet gateway box.
		 
4.  Why am I seeing duplicate messages?
		The reason you will sometimes see duplicate messages is because users are talking to other users on 
		your network. AIM Sniff picks up the message as it leaves your network, goes to the AOL network and 
		gets redirected back to the destination handle on your network as well. AIM Sniff picks the message 
		up as the message leaves and comes back.
		
5.  Why is there no To/From?
		This is a problem with the AIM protocol. In outgoing messages, only the From field is included and in 
		incoming messages only the to field is included. 

		AS has two ways of defeating this, the first is only applicable if you are dumping to a db. If you run 
		AS as: 
		./aimSniff.pl -c=./aimsniff.config --getHandles 
		It will look in the handles table and store a handle for each IP address. Then it will go through the 
		logs table and populate the to/from field with the last known handle of that IP. 
		
		The second way is only available in 0.8b. 0.8b stores a hash of IP->Handles that it detects logins of 
		and applys this hash to the appropriate field in the message before it writes it to the screen/db. This 
		method only works if AS has detected a login for that IP since it's been running. This list is flushed 
		everytime AS restarts though. I've pondered writing this list to a file but huge innacuracies could 
		occur. For instance, if you have a box that multiple users use, if you pick up AIM handle JOHN logon 
		using ip 192.168.1.2 and then shut AS down for a few minutes, and JANE logs on during the down time on 
		that machine, when you start AS back up, it could look like JOHN is sending the messages when really 
		its JANE.
				 
