. Disclaimer and WARNING

WifiScanner is not a newbie proof tools ! If you want to use it, 
"put out your finger from your pockets" and use your brain :-)

WifiScanner work ONLY on Linux ! Not Windows ! So ... :-)

Warning, if your system freeze or is out of office after you use WifiScanner, 
do not blame me, blame only you :-)

. What is the signification of WifiScanner ?

  Wi reless
  F  ind     &
  I  dentify
  S  canner

. Why WifiScanner?

 There are a lot of packages around which are used for
 wardriving. The common link among all all those tools is that they
 have Lucent cards since they have an auto homing mode.

 At the same time AirSnort needs a prism card to work.
 Why two cards? 
 While digging into prismdump and airsnort sources, I understood
 that one card would be enough, hence the prism stumbler.

 WifiScanner changes periodically the channel and tries to find any
 received frame on every channel, and displays them.

 This program was inspired from wlanctl from linux-wlan and prismstumbler
 from Jan Fernquist <Jan.B.Fernquist@telia.com>

 This scanner uses less cpu than its father and do a direct call to the
 driver rather than an exec of wlanctl.


. What I need to make it work

 It works only with Linux (sorry for the *BSD :)

 * You need driver for Wireless Card ;-)
 * Curses
 * A terminal with a minimum of 132 columns and 50 rows.
 * A Wi-Fi card :-) (PrismII, Orinoco, Cisco, Atheros card and more)

On Debian you need some packages :
glib-dev
libglib2.0-dev
zlib1g-dev
libncurses-dev

Now the PCAP lib is integrated, I take the libpcap modified for Kismet, it's
more simple :-)

. Tests and Runs

 For testing purposes, you can start WifiScanner manually.
 Root privileges are needed in order to make the sniffer work and run.

 # src/wifiscanner 
WifiScanner v1.0.0pre1 (c) 2002 Herv Schauer Consultants (jerome.poggi@hsc-labs.com).com)
Use of interface:wlan0
I sleep 71ms before change channel
I try to scan 14 channels per second
Beginning scan of the 802.11b networks...
Use CTRL-C to stop sniffing

[...]
The program run and you see it :-)

Now you want to exit, so press CTRL-C or Q
[...]
Now a summary of the detection :
--------------------------------
Station (00:06:25:70:B3:A4)  -  BSSID=00:06:25:70:B3:A4  -  SSID is not broadcasted
  Signal is between 15 and 49 and Data rate is 2Mb/s
  Max speed available is 11Mb/s
  Channel 6 with Wep
  1 beacon every 100 ms is sent
  This is an AP
-------------

 Spectral repartition :
-----------------------

    01 02 03 04 05 06 07 08 09 10 11 12 13     14
 50 -- -- -- -- -- -- ** -- -- -- -- -- --     -- 
 48 -- -- -- -- -- ** ** ** -- -- -- -- --     -- 
 46 -- -- -- -- -- ** ** ** -- -- -- -- --     -- 
 45 -- -- -- -- -- ** ** ** ** -- -- -- --     -- 
 43 -- -- -- -- -- ** ** ** ** -- -- -- --     -- 
 42 -- -- -- -- -- ** ** ** ** -- -- -- --     -- 
 40 -- -- -- -- ** ** ** ** ** -- -- -- --     -- 
 39 -- -- -- -- ** ** ** ** ** -- -- -- --     -- 
 37 -- -- -- -- ** ** ** ** ** ** -- -- --     -- 
 35 -- -- -- -- ** ** ** ** ** ** -- -- --     -- 
 34 -- -- -- ** ** ** ** ** ** ** -- -- --     -- 
 32 -- -- -- ** ** ** ** ** ** ** -- -- --     -- 
 31 -- -- -- ** ** ** ** ** ** ** -- -- --     -- 
 29 -- -- -- ** ** ** ** ** ** ** -- -- --     -- 
 28 -- -- -- ** ** ** ** ** ** ** -- -- --     -- 
 26 -- -- -- ** ** ** ** ** ** ** -- -- --     -- 
 25 -- -- -- ** ** ** ** ** ** ** -- -- --     -- 
 23 -- -- -- ** ** ** ** ** ** ** ** -- --     -- 
 21 -- -- -- ** ** ** ** ** ** ** ** -- --     -- 
 20 -- -- -- ** ** ** ** ** ** ** ** -- --     -- 
 18 -- -- -- ** ** ** ** ** ** ** ** -- --     -- 
 17 -- -- -- ** ** ** ** ** ** ** ** -- --     -- 
 15 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
 14 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
 12 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
 10 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
  9 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
  7 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
  6 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
  4 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
  3 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
  1 -- -- ** ** ** ** ** ** ** ** ** -- --     -- 
    01 02 03 04 05 06 07 08 09 10 11 12 13     14



 To stop the sniffer, you just need to press Ctrl-C

 I added some functionalities :
  - The capability to listen only in one Channel
  - The capability to save all displayed data
  - The capability to save all traffic data to a pcap format, so you can
    do an off-line analysis.
  - Make a file in .dot format of GraphViz (http://www.graphviz.org/)
      just type 
        $dot -Tps < FILENAME.dot >FILENAME.ps
      where FILENAME.dot is the file created by WifiScanner

 For more information see the Changelog, the inline help or the man.

. Help and Syntax

It can be called with no parameter or with the following options

 --help          -h           - This help page
 --version       -v           - Write Version and quit
 --verbose       -V level     - For verbose, level 2 is for debugging
 --card-driver   -C           - Wireless card driver :
                                'prism', 'cisco' 'cisco_wifi (eth+wifi)' 'orinoco' 'atheros', 'prism54g', 
                                'ipw2200', 'ipw2100', 'airjack', or 'hostap'
 --iface         -i device    - Name of the interface (default wlan0)
                              - for cisco_wifi driver, give the two interfaces like eth1,wifi0
                                 --output-file   -F filename  - Save output to a file as well as stdout
 --device-file   -D filename  - Create a file of detected devices, in a .dot format
 --hop           -H number    - Number of hops do for rotating channel (default 5)
 --channel       -S channel   - Only listen on a specific Channel (1-14)
 --computer-date -d           - Write date in machine readable format
 --ids           -I           - Activate the IDS functions
 --max-packets   -M number    - Max packets to capture before exit
                                (0 = unlimited)
 --hide-packets  -N abcd      - Do not display Ack, Beacon, Control, Data
 --hop-delay     -t number    - Number of ms before channel change (default=200)
 --disable-check -c           - Do not chek curses screen size
 --pcap-file     -W filename  - Save sniffed data to a file in PCAP format

Please send Bug report to : jerome.poggi@hsc-labs.com

You can use the level 2 of verbosity of this scanner to dump all
packets in hex format, so you have an equivalent to "tcpdump lnvvv".
But I must warning you, it's a very quick dump :-)

Debug level 3 is too much message for the common people, so ...

. How to read Data

for example we use these packets :
1018427099,"",0,___,STA,51,0,00:40:96:17:4F:CC,00:04:E2:48:68:43,00:10:5A:48:68:43,11Mb/s,STA Activity,To DS
1018427099,"Airport",11,Wep,AP,78,0,FF:FF:FF:FF:FF:FF,00:04:E2:48:68:43,00:04:E2:48:68:43,1Mb/s,AP Base (dedicated)

Column 1 : Time since 1 January 1970 (or readable date if -d option is set)
Column 2 : ESSID
Column 3 : Channel. When is 0, it means that it's unknown
Column 4 : STA or AP : Client Station or Access Point
Column 5 : Strength of Signal
Column 6 : Strength of noise (if it known)
Column 7 : Packet Destination Address (FF:FF:FF:FF:FF:FF is broadcast)
Column 8 : Packet Source Address
Column 9 : BSSID
Column 10: Data Rate (1, 2, 5.5 or 11Mbit/s)
Column 11: Type of client
            Client                       : it's a client (in usual management or control data)
            AP Base                      : it's an AP
            AP Base (STA in master mode) : It's a card in Master mode
            AP Base (dedicated)          : It's a dedicated AP
            Ad-Hoc STA                   : It's an Ad-Hoc client
            STA Activity                 : It's a client emitting some Data
if you find another info, like ???7, please write to me.

Column 12: Type of radio transmission
	    Radio only
	    Data To DS
	    Data From DS
	    Data AP to AP
if you find another info, like ???4, please write to me.

Column 13: Name of packet type
Take a look at TypeOfPacketToString function in src/conversion.c :-)


. How to read data in curses interface

The screen is organized like this :

+-------------------------+
| Title Windows           |
+---------------+---------+
|               | Summary |
| Panel Window  | Window  |
|               |         |
+---------------+---------+
|                         |
|    Real time Window     |
|                         |
+-------------------------+

Panel Windows is where you can see all STA and AP like this :
>AP  00:40:96:13:94:F6 "tsunamiiii"                    XY|=====================______________|_ (153,255)

> it signifies that a packet is received
AP or STA : is ... :)
MAC address of detected device
X Channel in Hexa
Y w= with WEP, W with WPA, T for WPA enterprise with TKIP, C for WPA2 enterprise with CCMP, 
  p for WPA PSK (TKIP), P for WPA2 PSK (CCMP), ...
SSID
Histogram of signal quality (==== for now and |_____| for the maximum)
Signal quality in digital form (actual value, maximum value)


Summary windows :
AP : number of AP detected
STA : number of STA detected
BEACON : number of beacons received
SSID : number of different SSID
Channel : number of channel with active data detected
Invalid : number of invalid packets
Crypted : number of crypted data packets
Weak : number of data packets with weak IV
Last IV : the last catched IV
Packets : number of packets

After it's a graph of scanned channel


Realtime Windows
all data see in realtime :-)


. IDS module

Q - How it Work ?
A - It try to analyze Timestamp, if two timestamps are too different,
this mean that a forged packet is probably found. Why ? because
TimeStamp are generated by the hardware of all devices and it's not
forgeable, in opposite of MAC @.
    It try to analyze also the beacon interval. Why ? because I change the
beacon interval of my AP and if two beacon interval are found, this mean
that somebody try to do a MitM attack (try to configure some strange
beacon interval and take a look :-)))
    Finally it try to analyze variation of Sequence Number.

Take a look at http://home.jwu.edu/jwright/papers/wlan-mac-spoof.pdf


Q - Why it exist ?
A - because of the existence of some scanner jammer, DOS jammer, Man in
the middle attack and more ...



Keyboard Interactivity
----------------------

  '-'               Channel down ( leave channel hopping mode )
  '+'               Channel up   ( leave channel hopping ) 
  'cxxc'            Listen to channel xx : eg: c06c for channel 6
  'n[abcdp]'	    Do not display Ack, Beacon, Control, Data, Probe packets
  's'		    Change channel slowly
  'f'               Change channel faster
  'd'		    Change channel at default speed
  'j+' and 'j-'     Change the channel hop
  'v+' and 'v-'     Change the verbosity (warning don't play to much with it 
                     on loaded network ;-)
  'Q'               Exit, stop, quit, goback home, bamos a la playa ...

... More to come and available when you hit h for help


. Licence and Copyright

 This program is under GPL v2 and is copyright 2003-2005 Herv Schauer Consultants
 
 Jerome Poggi <Jerome.Poggi@hsc-labs.com>

. GPG Signature

All tarball are sign with my GPG key, you can find all file and signature at
http://www.hsc.fr/ressources/outils/wifiscanner/download/

My public key fingerprint is :
C34A C116 1AA2 84AD 2592  1F98 FBB0 84A0 34AF BB17

My public key is available :
 - in PGP keyservers
 - at http://www.hsc.fr/~poggi/jerome.poggi.asc

. Greetings

Olivier Fauchon for cooding
Guillaume Lehembre for photos
Ivan Vassileff for testing

/* $Id: README 154 2006-09-12 15:48:19Z poggij $ */

