echolot 0.1.0                                                      HOWTO


1  Introduction
  1.1  Short Description
  1.2  Disclaimer
  1.3  Authors
  1.4  Contribution

2  Installation
  2.1  Platforms
  2.2  What is needed?
  2.3  Go go go!

3  First Steps
  3.1  Longer Description
  3.2  Detecting Intruders
  3.3  Finding Servers Again
  3.4  MAC Spoofing
  3.5  IP Spoofing
  3.6  Daemonizing

4  Scripting

5  FAQ



1  Introduction
1.1  Short Description

Every network interface controller (NIC) has a world-wide unique MAC-
address. If computers are connected over a local area network, they
will exchange those MAC-addresses to identify each other.
echolot collects this MACs, tries to resolve a name for each host
and stores them in a database. Now, you can easily find already known
computers, you can find intruders in your companies network and no one
can hide...


1.2  Disclaimer

copyright (c) 2002 by Benjamin Schweizer <gopher@h07.org>


Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in
     the documentation and/or other materials provided with the
     distribution.
  3. The names of the authors may not be used to endorse or promote
     products derived from this software without specific prior
     written permission.
				    
THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
				    

1.3  Authors

See AUTHORS file in main directory.


1.4  Contribution

Send patches, donations, caffeine, beer, pizza, pictures (if female) to

  Benjamin Schweizer <gopher at h07 dot org>
  http://www.redsheep.de/


2  Installation
2.1  Platforms

echolot runs on many platforms, as it uses automake and is fully posix
complain. Supported platforms are ia32, Alpha, PowerPC and so on. See
PLATFORMS file in main directory for details.


2.2  What is needed?

You need to have the developement version of the libpcap (including
header files). It is mostly called "libpcap-devel" and is part of all
major distributions. I know that it is included within SuSE Linux,
Debian GNU/Linux and FreeBSD.
You can get the latest release at the tcpdump group's website:
  http://www.tcpdump.org/release/


2.3  Go go go!

(install libpcap-devel)
run ./configure
run ./make
run ./make install

copy ./scripts to /usr/local/bin or somewhere else
check the paths in the scripts for propper work.
check permissions for /var/db/echolot.mac


3  First Steps

3.1  Longer Description

Here in detail. Before any IP connection is established, the computers
will exchange their MAC addresses by the Address Resolution Protocoll
(ARP). These ARP packets contain the MAC address of the sender, its IP
address and some more information. They are broadcasted to any computer
on the lan, even thru switches (but not thru gateways).
echolot sniffers these packets on a given interface and tries to resolve
a domain name (netbios, dns etc., see Scripting section below). This
information is stored in a database which is compatible with "iptraf".
Now you can detect already known hosts, like popular ftps on lan parties,
you can detect foreign hosts on your network, possible intruders to your
companies lan and you can prevent IP and MAC spoofing - or kick someones
ass therefor.
echolot announces, if faked ARP packets are sent and it announces if the
IP address of a client changes. This gives you the capability to say
host abc had IP xyz at some date. You can exactly see who used an IP at
some time.


3.2  Detecting Intruders

You will have to generate a database, including all of your trusted
computers. Run therefor echolot

  echolot -a -i eth0 -I "my-computers" -d "~/trusted.mac"
 
echolot will watch on interface eth0 for all activities and will use
"my-computers" as base-name. All data is stored to "~/trusted.mac".
After some minutes, most of your computers should be in the database,
now you can run echolot 

  echolot -i eth0 -I "my-computers" -d "~/trusted.mac"

and all new hosts will be reported, but not stored. You will see, if
there is activity from any new hosts on your network. It is also a good
idea to run echolot as a daemon, see this below.


3.3  Finding Servers Again

Just run echolot in collection mode (-a/--add)

  echolot -a -i eth0 -D "my-computers" -d "~/trusted.mac" (fixme)

It will report any computers on your lan and add new ones to your
database. If a hosts looks fine, you just have to remember its name
or modify the correspondending entry in the database.


3.4  MAC Spoofing

echolot reports if a computer gives a different MAC address in the ARP
packet than its ethernet frame tells. It is also a good idea to run
echolot as a daemon, see this below. Beware that there are network
adapters out there that can really change their MAC address.


3.5  IP Spoofing

If someone claims a different IP address on your lan, echolot will
report this. If echolot is run in daemon mode, it well log all
information to syslog and you can see which host had a IP at a
special time.
Just imagine there was a attack to your servers. You know the date
and you know the IP address, but you dont know who had this one.
Have a look at echolots syslog output and your know which host was
used...


3.6  Daemonizing

You can daemonize echolot with the "-d/--daemonize" parameter. If
echolot is daemonized, it will log all information to syslog. This is
useful to detect spoofed IP's and to kick someone's ass after a attack
from inside of localnet...


4  Scripting

Since release 0.0.3 echolot supports a scripting feature. There were
problems with part of the samba code and I received more and more wishes
how the name resolution should be done. With the scripting feature
everyone can define scripts on his own.

Per default echolot uses the default-string as a hosts name. It can be
overtyped by the "-I/--idendity" parameter. In addition, echolot can
call external scripts to resolve IP addresses.

  echolot -a -i eth0 -I "my-computers" -s "/usr/local/bin/default.pl"

Here we tell echolot to add new hosts to the database (which is default
/var/db/echolot.mac), use the interface eth0 and overtype "default" by
"my-computers". It calls "/usr/local/bin/default.pl" with the IP as 1st
parameter and "my-computers" as 2nd parameter. The script's return value
is used as host description, unless it fails.

There are scripts for domain name server resolution (domain.pl), netbios
resolution (netbios.pl) and a date script. I prefer to combine all of
them (default.pl).

Feel free to mail own scripts to gopher@h07.org.


5  FAQ

q: is there a faq?
a: not yet.
