Etherbat performs Ethernet topology discovery between 3 hosts: the machine running Etherbat and two other devices.
— these are example questions answered by Etherbat.
Etherbat could be described as layer 2 equivalent of traceroute.
No manageable switches nor extra software on remote hosts is required.
Attacker: "Where is that internal database server located?"
Admin: "I know there is an internal attack executing right now, but where it originates from?"
Admin: "I want to have detailed map of the network, but I don't want to track every cable physically. The boss doesn't want to buy manageable switches."
Auditor: "Let's check if the network documentation describes real network structure."
Note: The map of the network could be created by repeatedly executing Etherbat with different host combinations and joining gathered results. Etherbat won't do this automatically.
Warning! Etherbat was tested only on wired network. It won't work on wireless. Also, it could give incorrect results:
Etherbat uses MAC spoofing to create invalid paths in the network, probes how it changed by injecting specially crafted ARP requests and checks for replies or absence of them. Afterwards it makes the network return to normal state.
For more detailed explanation please read the documentation.
Etherbat is written in interpreted language, but needs to launch external processes for frame injection and sniffing. Those are C programs which needs to be compiled.
Etherbat releases can be downloaded from Launchpad project page.
There is also the Bazaar repository. To get the latest version of Etherbat type:
$ bzr branch http://bazaar.launchpad.net/~launchpad-cryptonix/etherbat/trunk
UPDATE: Launchpad project page no longer exists.
To download Etherbat tarball click here.
Etherbat source code is released under the terms of GPLv2 license.
You are advised to check Etherbat tarball integrity against my gpg key, which can be downloaded from here. If the tarball and signature are in the current working directory, issue:
$ gpg --verify etherbat-*.tar.gz.asc
After positive verification, you can extract Etherbat source distribution with:
$ tar zxf etherbat-*.tar.gz
Then enter newly created directory and optionally alter instalation path at the beginning of Makefile. If you want to link Libnet and Libpcap libraries to be linked dynamically (you should do this if your distribution ships shared versions of these libraries like Debian does) execute:
$ make
Otherwise, you need to specify libpcap.a and/or libnet.a files to link statically with. For example if both are placed in /usr/lib/ you should type:
$ make PCAP_STATIC=/usr/lib/libpcap.a LIBNET_STATIC=/usr/lib/libnet.a
After successful compilation, if you are using sudo issue:
$ sudo make install
or if you are using su:
$ su -c "make install"
Note that the installation is required for program to run correctly. You can uninstall it with:
$ sudo make uninstall
or if you are using su:
$ su -c "make uninstall"
Etherbat requires two IP addresses as arguments. It will display how local machine and hosts with those addresses are connected in form of ASCII diagram. Here is example output (for those of you typing ^fscreenshot in Firefox ;-) )
# etherbat 10.0.0.1 10.0.0.2 0: 10.0.0.10 (00:12:1b:d8:a9:86) 1: 10.0.0.1 (00:0f:18:ce:5f:29) 2: 10.0.0.2 (00:26:b4:c5:8c:12) 1 2 0 \ / | *-~-*
Use -h to see list of possible options.
To understand what does all of this ASCII art mean and how to use some options read tests description.
I gave a talk on Etherbat on Confidence 2007 — you will find the presentation in the papers section of my website.
Also there is tests documentation with every step explained in details (tests.* in tarball).
I've planned to write whitepaper about Ethernet topology discovery, but some time after I had finished Etherbat 1.0.0 I've found this document. It describes similiar technique invented by three Microsoft guys (Richard Black, Austin Donnelly and Cedric Fournet) and presented in 2004 on IEEE conference. Reading it will give you almost everything needed to understand how Etherbat works.
Recently I've found this technique was implemented in Windows Vista as Link Layer Topology Discovery (LLTD) and used in Network Map feature.
When I was writing Etherbat I was unaware of Microsoft researchers work. General idea of LLTD and the technique used by Etherbat is the same, but there are some differences.
The main difference is that LLTD is far more complex (as it's distibuted system) and has more features, ie. it provides extensions for QoS tests, integrates anti-DoS functions. And last but not least — every host being located could provide his own icon to appear on the map (I wonder when LLTD themes will show on the Internet ;-)
| LLTD | Etherbat | Notes |
| LLTD maps entire network. | Etherbat discovers topology between 3 hosts. | It is possible to create application which invokes Etherbat repeatedly for different host combinations and joins results somehow to build the map. Also see TODO. |
| LLTD requires all hosts to have responders installed to be placed on the map. | Etherbat doesn't need any extra software on remote hosts. | LLTD authors consider support for devices without responders (see section 5, paragraph "Uncooperative hosts" of mentioned paper), but as far as I know it's not implemented (yet?). |
| LLTD enumerator (the tool coordinating topology discovery) is available for Windows Vista only. | Etherbat works on Linux and should work on *BSD systems without modifications (but wasn't tested). Porting to other platforms should be straightforward as majority of code is written in Ruby. | |
| LLTD enumerator source code is not available. | Etherbat code is released under GPL license. | LLTD responder source code is available to download. |
| LLTD uses special MAC address family which doesn't collide with MAC addresses used in the network — normal traffic is not affected. | Etherbat impersonates host being tested, so it may temporarily cause traffic destined to this host to be lost. | |
| LLTD operation is not disturbed by other host transmissions. | Etherbat is sensitive to traffic generated by hosts being tested. | |
| LLTD correctly detect hubs and wireless stuff; topology detected is generally more accurate. Authors presented formal proof of algorithm correctness and completeness. | Etherbat doesn't support hubs and wireless. |
Can I use Etherbat to map remote network which is somewhere in the Internet?
Etherbat is a layer 2 tool, uses MAC spoofing and ARP protocol. This kind of stuff won't be forwarded by routers.
The only possibility is too use some kind of Ethernet over IP tunneling (note: when the tunnel is not 100% transparent it may impact result).
What is there are hubs (Ethernet repeaters) in the network?
Depending on hub placement Etherbat will work good, refuse to work or work badly and display incorrect results.
Etherbat doesn't display all switches.
If there are multiple switches in the line between hosts under test they are displayed as 0, 1 or more switches. See symbols description at the end of tests description.
This software was written by me, Paweł Pokrywka. You can find my email address as well as my gpg key at:
https://www.cryptonix.org/about.html