============================================================================
                                ettercap 0.4.0                    2001-04-09
============================================================================

    Even if blessed with a feeble intelligence they are cruel and smart...


       @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@ @@@@@@@
       @@        @@@     @@@   @@      @@   @@ @@      @@   @@ @@   @@
       @@@@@@    @@@     @@@   @@@@@@  @@@@@@  @@      @@@@@@@ @@@@@@
       @@        @@@     @@@   @@      @@  @@  @@      @@   @@ @@
       @@@@@@@   @@@     @@@   @@@@@@@ @@  @@@ @@@@@@@ @@   @@ @@


                     Multi purpose sniffer/interceptor



         Required Libraries:              none ;)  (optionally ncurses 4.2)

         Optional Libraries:              openssl  (if you want ssh support)

         Installation:                    configure
                                          make
                                          make install

                         (optional)       make plug-ins
                                          make plug-ins_install

============================================================================
                                    INTRO
============================================================================

Kiddie:   A friend of mine told me that it is possible to sniff on a LAN...
          so I bought a switch ;)

NaGoR:    mmhhh....

Kiddie:   Now my LAN is SECURE ! you can't sniff my packets... ah ah ah

NaGoR:    are you sure ? look at ettercap doing its work...

Kiddie:   Oh my god... it sniffs all my traffic !!
          I will use only ciphered connection on my LAN, so ettercap can't
          sniff them ! ah ah ah

NaGoR:    mmhhh....

Kiddie:   Now I'm using SSH.  My LAN is SECURE !

NaGoR:    are you sure ? look at ettercap doing its work...

Kiddie:   shit !!  grrrr...


 "a false sense of security, is worst than insecurity"   -- Steve Gibson

 ehi folks... wake up !  the net is NOT secure !!

 ettercap demostrates that now is the time to encourage research on internet
 protocols to make them more secure.


============================================================================
                                   LICENSE
============================================================================

   GNU GENERAL PUBLIC LICENSE.

   see COPYING for details...


============================================================================
                                   AUTHORS
============================================================================

   Alberto Ornaghi (ALoR) <alor@users.sourceforge.net>

   Marco Valleri (NaGA) <crwm@freemail.it>


============================================================================
                              TABLE OF CONTENTS
============================================================================


   1. DISCLAIMER............................................sez.  1

   2. INSTALLATION..........................................sez.  2

   3. HOW TO USE IT.........................................sez.  3

      3.1   ncurses interface
      3.2   command line

   4. TROUBLESHOOTING.......................................sez   4

   5. TECHNICAL PAPER.......................................sez   5

      5.1   The host list
      5.2   IP based sniffing
      5.3   MAC based sniffing
      5.4   ARP based sniffing
         5.4.1    arp poisoning
         5.4.2    characters injection
         5.4.3    active protocol dissection
         5.4.4    SSH1 man-in-the-middle        NEW !!

   6. PLUG-INS..............................................sez.  6

   7. USELESS INFORMATION...................................sez.  7


============================================================================
1>                               DISCLAIMER
============================================================================


 This software is provided "as is" and without any expressed or implied
 warranties, including, without limitation, the implied warranties of
 merchantability and fitness for any particular purpose.


============================================================================
2>                              INSTALLATION
============================================================================

 The easiest way to compile ettercap is in the form:

    ./configure

    make

    make install

 Now you should be able to run ettercap (it installs as default in /usr/local
 /bin if you don't have it in your path try /usr/local/bin/ettercap)
 There are a lot of useful options in configure: try using --help.

 If you'd like to suid ettercap, enabling thus other users, and not only
 root, to use the program, use --enable-suid before applying suid to ettercap
 with chmod, otherwise it would drop the applied suid.

 If you have problems with plug-ins, disable them by using --disable-plugins.

 If you have installed OpenSSL in a different DIR use --with-openssl=DIR
 If you get an error linking OpenSSL with ettercap, try recompiling OpenSSL
 with "Config shared && make && make install" (on my box it worked ;) )

 If you still have difficulties, send an e-mail message one of the authors
 (alor@users.sourceforge.net or crwm@freemail.it).
 The sourceforge home-site of ettercap could also contain useful information,
 latest bug fixes and updated versions (ettercap.sourceforge.net).

 Bug reports are welcome. Please report problems in the configure/make
 process by including a copy of config.status, config.cache and config.log,
 as well as the pertinent compiler diagnostics. If you have problems in the
 program, please configure with --enable-debug and send also a copy of
 ettercap_debug.log and a short description of your configuration (eg. kernel
 options) when reporting a segfault or other strange behaviors.


============================================================================
3>                              HOW TO USE IT
============================================================================

 There are two main interfaces available, both for text-mode, one in plain
 b/w character interface, and another with ncurses windowish colorful and
 pleasure-full character mode!

3.1 NCURSES INTERFACE

 Let's start showing you the latter one:
 If ettercap is invoked without options (see later on, for the command line
 options) it will run the ncurses interface (a short delay to scan your LAN
 could be noticed =).
 The main window is divided in 3 subsections: top, middle and bottom.
 In the top window there is the connection diagram, displaying the two
 machines to sniff or to connect and operate to.
 Below you will see the list of known hosts in the current LAN (with hub or
 switch) that you can reach: select a couple to sniff them.
 The two identical columns let you choose the said couple: select with the
 arrow keys an entry representing an ip of an active machine ([enter] will
 do this job =) on the left.
 Then switch to the second column on the right with [tab], and move as usual
 to select the second ip. This will represent the traffic route you would
 like to sniff (and eventually connect/poison).
 Obviously you cannot select the same source and destination, but you are in
 any case not forced to select your IP.
 In the bottom window, there is a sort of status bar, giving you additional
 information about currently selected objects, current status and eventually
 other important hints.
 There are also a lot of other nifty options that are selectable at this point,
 first of all the 'p' plug-in feature (these are separate features, externally
 programmed in this project, with a vast cover of applications, not displayable
 here: there is a special README-PLUGIN for this).
 Or the ability to inspect with the 'c' key, if there is an other "evil" proggy
 in your LAN running, and thus alerting you of possible data interception.
 But remember that throughout all the stages of the program you can always
 press 'h' for help, and a nice help window will show up and list you the
 currently available keys!

 These should be anyway self-explanatory help windows, so probably there is
 no need in reading this sections here, but.. in case.
 You'll notice that the top window will update while selecting source and
 destination ip, and finally show the current status scheme if you connect or
 sniff (respectively pressing 'a' and 's' or 'm')
 IP Based sniffing filters connections looking in the IP header for matching IPs.
 This is the old style, classic method performed by most programs.
 MAC Based sniffing filters connections looking in ETH header for matching MACs.
 This is useful if you want to sniff connections from your local host and a
 remote host through your gateway (simply selecting your host and your gw
 as source and destination).
 Finally there is the connect option, as said, that lets you, if your
 computer results connected to a switched LAN, poison the ARP cache
 permitting you to sniff the traffic on your local net as if you where on
 a network with an hub.
 With this option you can specify one or two host. If you select only one
 host you'll enter the PublicARP mode and you will overtake the selected IP
 with yours.
 If you specify both hosts you will enter the ARPBased Mode that allows you
 to view all the bidirectional traffic between the two hosts.

 In any case, now you enter the second stage: the central main window now will
 list active connections between the two sources IPs, if there are.
 So eventually open connections show up, and you can select them as usual,
 allowing you to enter the third stage: the real sniff! =)
 In the meanwhile you can anyway look at the status of the connections (active,
 closed, etc) and see what type of traffic/port is used (ftp, ssh, web, etc).
 It is also possible to kill an active connection of any type.
 If the application protocol is supported by ettercap you can see, in the
 bottom window, some useful information about the highlighted connection,
 such as USER and PASSWORD used for interactive sessions.
 If you used ARPBased mode you can also start ACTIVE PROTOCOL DISSECTION,
 that allows you to view particular ciphered protocols like ssh.

 Now assume you selected an active connection: two sub-windows appear in the
 main one. They show you source packets passing through your computer before
 reaching destination, you sniff traffic without that they notice it! There are
 different visualization options here: the type of stream can be hex ('x' key)
 or ascii ('a' key) that is specifically decoded for supported
 protocols; some decoders needs the ACTIVE PROTOCOL DISSECTION to be available.
 You can also specify to suspend the stream of data
 (only prevents their visualization, in reality they go forward in background)
 as a sort of scroll-lock (press 's' key), for better data-analysis.

 Finally, there is also a very cool feature: inject.

 With the 'i' key you can also inject some chars in the traffic, choosing the
 direction, being able to add commands to the stream (i.e. you could sniff
 a telnet session and also being able to transmit some commands to the machine
 connected to. Like "ls" or whatever you want, and they have absolutely
 effect as if originated by the source! The same way you could generate fake
 output on the originating machine, not responding to the real output).
 NEW : Injector now supports escape sequences. you can make multiline injection.
 NOTE: remember to terminate your injection with \n\r if you want to inject
 command to the server.

 There is also an option to log all this beautiful data streams to file, just
 press 'l', then read it down or pass it trough an automated script-filter with
 calm.

 As you will notice, using the tool in visual mode will be simpler when trying
 it on run than by reading this instructions.. help is also a good resource to
 count on while operating.

3.2 COMMAND LINE

 Well here there are two classical commands that will respond you with an
 answer, being the command list reference: launching ettercap with the --help
 switch and invoking our man page (man ettercap ;).
 ->Some features are available only from visual interface.

 Starting in non interactive mode (-N) there are also available some features
 bound to the interactive mode: you can activate a little help line and change
 visualization mode on the fly (between hex and ascii for example)
 In the same way it is possible to set up a lot of options form the command
 line and see them in interactive mode already set and started.

 Now there is also the possibility to shorten command usage, by specifying
 one or more hosts to sniff (if you are in silent mode, also one or none is
 possible by setting -z option: like sniffit that sniffs from everywhere =)

 Ex:

  ettercap -Nsz  (sniff data from every ip)

  ettercap -NCsz  (collect only users and passwords from every ip)

  ettercap -NCsz ghibli meltemi (collect only from "ghibli" to "meltemi")

 NB: if you had started in interactive mode (without -N) it would have been
     necessary to specify 'r' to refresh the ip host list if you returned
     with 'q' to the first interface, since no list has been generated at
     the beginning due to the -z option.
     ex: ettercap -zs ghibli meltemi          or
         ettercap -zm 00:A0:24:4C:00:F9 00:A0:24:36:00:C2

 Ok, that's all..

 Have fun and await the next versions, including ssh handling, you could do
 some happy jokes to your friends, especially if they are the ones who believe
 that ssh is an absolutely not-sniffable and cryptographically unbreakable
 thing, better on if they also believe in switches doing their job! =)


============================================================================
4>                             TROUBLESHOOTING
============================================================================

 There are really a lot of things that could happen to you as of installing
 this proggy. Thus don't blame us in case of accidents or hours spent trying
 to compile etc.. In this state, till we reach a *very* stable version there
 will be no troubleshooting section, which would be to large and infeasible
 to write down and do the necessary spread out betatests.
 But we'll do our best, try to compile in lots of machines, port it as much
 as possible, and clean up everything. For now the main aspect was to write
 down base ideas and see them work. When the main skeleton is completed
 there will be a lot of fine tune.

 The best thing to do if you need support or help in compiling is to mail us!

 Then we will write down a sort of FAQ and a problem resolve list or todos
 here in this section.
 In raw we'd like to know you that there are problems in particular when
 installing the rpm binary version of ettercap, including ncurses, which
 can easily be miss-detected: try simply to add --nodeps to the rpm line.


============================================================================
5>                             TECHNICAL PAPER
============================================================================


5.1   THE HOST LIST

 When ettercap starts it makes the list of the hosts that are in the lan.
 Sending one ARP REQUEST for each ip in the lan (looking at the current ip
 and netmask), it is possible to get the ARP REPLYs and than make the
 list of the host that are responding in this lan. With this method even
 windowish hosts, reply to the call-for-reply (they don't reply on broadcast-
 ping).
 Be very careful if the netmask is a class B (255.255.0.0) because ettercap
 will send 255*255 = 65025 arp requests, it takes more than a minute !! (the
 delay between two requests is 1 millisecond)


5.2   IP BASED SNIFFING

 This is the "old style" sniffing mode.
 It puts the network interface in promisc mode and then sniffs all packets
 matching the ip filter.
 If you are using the ncurses interface, the ip filter is made up of: ip
 source, port source, ip dest, port dest; in both the directions of the
 connection.
 Instead if using the command line, you can make a personalized ip filter.
 You can specify only the source, only the dest or both. each with or without
 an associated port.

   Examples:

     ettercap -N -s ghibli
     ettercap -N -s ghibli:23

  the first will sniff all the connections to the host "ghibli"
  the second only those which are on the port 23

     ettercap -N -s ghibli meltemi
     ettercap -N -s ghibli:23  meltemi

  the first will sniff all the connections between "ghibli" and "meltemi"
  the second only those which are on ghibli:23 coming from "meltemi"


5.3   MAC BASED SNIFFING

 It puts the network interface in promisc mode and then sniffs all the
 packets that match the mac filter.
 The mac filter is made up giving the IPs of the two hosts. Ettercap will
 scan the host list and associates the correct mac address to the filter.
 In this way specifying the gateway's ip and an host's ip, you will get
 all the connections between the host and the Internet.

   Examples:

   assuming that "meltemi" is the gateway to internet.

     ettercap -N -m ghibli meltemi

   this will return all the connections that "ghibli" makes to remote hosts.


5.4   ARP BASED SNIFFING

 This method doesn't put the interface in promiscuous mode. It isn't
 necessary because the packets will be sent to us! :) The switch will
 forward the packets to us, so we have a good method for sniffing in
 switched LANs.
 Let's view how this is possible:
 when you select this method, ettercap will poison the arp cache of the
 two hosts, identifying itself as the other host respectively (see the
 next section for this).
 Once the arp caches are poisoned, the two hosts start the connection, but
 their packets will be sent to us, and we will record them and, next, forward
 them to the right side of the connection. So the connection is transparent
 to the victims, not arguing that they are sniffed. The only method to
 discover that there is a man-in-the-middle in your connection, is to watch
 at the arp cache and check if there are two hosts with the same mac address!
 That is how we do, to discover if there are others poisoning the arp cache
 in our LAN, thus being warned, that our traffic is under control! =)

     HOST 1  - - - - - - - - - - - - - - - - - - - -> HOST 2
   (poisoned)                                      (poisoned)
       |                                               ^
       |                                               |
        ------------> ATTACKER HOST  ------------------
                      ( ettercap )

 Legenda:
             - - - ->   the logic connection
             ------->   the real one

 Ok, cool! Though, how can I poison the arp cache ?


5.4.1    ARP POISONING

 The arp protocol has an intrinsic insecurity. In order to reduce the
 traffic on the cable, it will insert an entry in the arp cache even if it
 hadn't request it. In other words, EVERY arp reply that goes on the wire
 will be inserted in the arp table.
 So, we take advantage of this "feature", sending fake arp replys to the two
 hosts we will sniff. In this reply we will tell that the mac address of the
 second host is the one hard-coded on OUR ethernet card. This host will now
 send packets that should go to the first host, to us, because he carries
 our mac address.
 The same process is done for the first host, in inverse manner, so we have
 a perfect man-in-the-middle connection between the two hosts, legally
 receiving their packets!!

   Example:

     HOST 1:  mac: 01:01:01:01:01:01         ATTACKER HOST:
               ip: 192.168.0.1                    mac: 03:03:03:03:03:03
                                                   ip: 192.168.0.3

     HOST 2:  mac: 02:02:02:02:02:02
               ip: 192.168.0.2


   we send arp replys to:

            HOST 1 telling that 192.168.0.2 is on 03:03:03:03:03:03
            HOST 2 telling that 192.168.0.1 is on 03:03:03:03:03:03

   now they are poisoned !! they will send their packets to us !
   then we receive packets from:

            HOST 1 we will forward to 02:02:02:02:02:02
            HOST 2 we will forward to 01:01:01:01:01:01

   simply, isn't it ?


5.4.2    CHARACTERS INJECTION

 We have stated that the packets are for us...
 And the packets will not be received by destination until we forward them.
 But what happens if we change them?
 Yes, they reach destination with our modifications.
 We can modify, add, delete the content of these packets, by simply
 recalculate the checksum and substitute them on the traffic.
 But we can do also more: we can insert packets in the connection.
 We forge our packets with the right sequence and acknowledgement number and
 send them to the desired host. When the next packets will pass through us we
 simply subtract or add the sequence number with the amount of data we have
 injected till the connection is alive, preventing the connection to be
 rejected (this until we close ettercap, who maintains sequence numbers
 correct, after program exit, the connection must be RESETTED or all future
 traffic would be rejected, blocking the source workstation network).


5.4.3 ACTIVE PROTOCOL DISSECTION (for ARPBASED mode)

 To view in strongly-ciphered streams you need to act straight on the stream.
 For example you need to change key-packets (man-in-the-middle technique).
 In particular cases this will result in a fault of the protocol, so pay
 attention using this feature.
 The used method changes from protocol to protocol and is more difficult to
 explain than to code it.
 So I'm sorry but you have to examine the source code if you really want
 to know how it works.


5.4.4 SSH1 MAN-IN-THE-MIDDLE

 When the connection starts (remember that we are the master-of-packets, all
 packets go through ettercap) we substitute the server public key with one
 generated on the fly and save it in a list so we can remember that this
 server has been poisoned before.
 Then the client send the packet containing the session key ciphered with
 our key, so we are able to decipher it and sniff the real 3DES session key.
 Now we encrypt the packet with the correct server public key and forward it
 to the SSH demon.
 The connection is established normally, but we have the session key !!
 Now we can decrypt all the traffic and sit down watching the stream !
 The connection will remain active even if we exit from ettercap, because
 ettercap doesn't proxy it (like dsniff), after the exchange of the keys,
 ettercap is only a spectator... ;)


============================================================================
6>                                 PLUG-INs
============================================================================


 see README.PLUGINS


============================================================================
7>                            USELESS INFORMATION
============================================================================


Project started on :       2000-11-25

Last stable release :      0.4.0          Our software never has bugs.
                                          It just develops random features.

Published on :             2001-04-09
                                    whenever a code runs it's just obsolete


Editor :                   vi, vim, gvim, mcedit, UltraEdit


greetings to :             The IEEE 802.3  standard  :)
                           ISO/OSI organization
                           Andrew S.Tanenbaum
                           Berkeley University

                           the SiLAB (university lab)
                           JJ corner's PUB

ALoR greetings:            VMWare staff ;)
                           elle (she knows for what...)


NaGA greetings:            Heineken Inc.
                           My MP3 player
                           N-Team
                           MegaBug


fucks to :                 tutte le tipe che se la menano ;)
                           mcedit (it sucks!)


Motto :                    Specialization is for insects, a human being
                           should be able to do anything!

Who we are :               If you think you know us... YOU DON'T.
                           If you don't know us... YOU WILL.

Shakespeare :              question = ( to ) ? be : !be;

0xABADC0DE==============================================================EC-2K