###############################################################################


                   [nopkit] - The Network Operator's Toolkit


###############################################################################


General
  nopkit is a set of tools that can be used to manipulate the local network. It
  is designed to run equally well on Windows and Linux and provides a traffic
  re-router, an ARP spoofer, a DNS spoofer and a utility for probing network 
  status. 

  Extensive use of the libpcap and libnet libraries provide packet capture
  and injection capabilities. 

  See the source code for details on implementation and use. You can also check-
  out the sample directory, where I'll try to put a few sample scripts. Also,
  use the -h option at the command line to output some usage info.


Licence
  Copyright (c) 2004 - 2005, Jesse Pool <jpool[@connect.carleton.ca]> 
  All rights reserved.
 
  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. Neither the names of the copyright owners nor the names of its
     contributors may be used to endorse or promote products derived from
     this software without specific prior written permission.
 
  THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  SUCH DAMAGE.


Linux vs. Windows
  Aside from the libpcap and libnet libraries, as much standard c is used as 
  possible in this set of tools. The idea was everything would port nicely.
  Obviously that's not always the case. 


Compiling
  For those of you in on the Win32 side of the house, I've provided a full
  solution with all the paths set up, etc. Just open nopkit/win32 and you
  should find everything you need. Of course you'll need to download libnet
  (http://www.packetfactory.net/libnet/) and WinPcap developer's pack
  (http://winpcap.polito.it/). I've also compliled the binaries for those who
  don't have access to VS 2003. (See the website for details.)

  For *nix people, there is a makefile in each of the source folders. The only
  thing you need to do is edit the paths to libnet and libpcap. Then run make.
  I used the paths provided on my machine while developing. (SuSE 9.1) 

  I've tested using libpcap version 0.8.1 and libnet versions 1.1.1 and 1.1.2.
  On the win32 side I used Winpcap version 3.0 in testing. In the case of the 
  pcap libraries, I didn't use anything special as far as I know, so it should
  work fine in older versions. However, you can't use libnet version 1.0.x. The
  API is different.


Using the Toolkit
  There are currently 4 different "tools" available in nopkit, with a few 
  others in the planning stages. Each has been written with the intent of 
  being very general. My hope is that each tool is useful on its own instead of
  making one big single purpose app. The down side to this is that you kind of
  need to know what you're doing to get the best use out of nopkit. 

  Run make from this directory and you should generate 4 binaries. (Ignore the
  comiple errors. I'll clean those up later.. :) What you get is xarp, the ARP
  poisoning unit, xroute, the packet forwarder, xdns, a DNS spoofing unit and a
  general discovery tool called xdisc.

  First of all, xarp is the heart of the system. You use this little program to
  modify the ARP cache of a remote machine. Again, it's a very general tool. It
  has a lot of options, but most of them give reasonable defaults. For example,
  the -n option will let you specify the MAC address of the target machine, but
  if you don't include this option xarp will figure it out for you (provided 
  your target actually exists on the network). One option that should be 
  mentioned is -l, local MAC. Using this option will mean that xarp will use
  whatever you specify as the local MAC address. This includes leaving the -m
  option blank. If you leave the -m option blank and specify the -l option then
  the source MAC address sent in the ARP reply packet will contain the MAC 
  specified by -l. Don't get it? Give it a try and you will, but in most cases
  you won't need to worry (unless you want to spoof your MAC). 

  As you probably know, many machines won't simply accept unrequested ARP reply
  packets. This is why the -e option is included. This'll send the right ICMP
  echo request to force the target to make an ARP request right before it sends 
  each ARP reply. Thus, avoiding that little piece of security.

  Once initialized xarp will continue looping, sending out ARP replies to the 
  specified target (as well as ICMP echo request if you used -e). You can
  dictate the amout of time that xarp waits between each send by using the -r 
  option. The only confusing thing is that under Windows the argument is in
  milliseconds and under Linux it's microseconds. That means for one second in
  Windows you can say "-r 1000" and under Linux you'd use "-r 1000000". The 
  Linux version allows you more percision, while the Windows version will let 
  you wait longer between each send. Since you'll need to refresh the table 
  every 30 seconds or so, it really doesn't make a difference. 

  The last thing I'll say about xarp is that targeting multiple hosts is not 
  fully supported (sorry!). But there are some things you can do. If you want to
  make an ARP reply broadcast to everyone on the LAN just use the option -n and
  give it an argument of ff:ff:ff:ff:ff:ff. Then set your target to 
  255.255.255.255. This may be enough to poison everyone on the LAN. If the
  users are running Linux, be sure to include the -e option. 

  Also very general, xroute is used if you don't want to set up forwarding on
  your system. It's nice because it's way easier to set up and take down, and
  pretty flexable too. The most important aspect of xroute is the filter, option
  -f. This specifies which packets should be handled. It's the standard libpcap
  filter, so you can get pretty creative. However, this is the part where you
  need to know what you're doing to make things a success. Take a look in the
  samples directory for some of the filters that i've used.

  Basiclly, xroute allows you to read in specified packets, based on the filter,
  and then change the Ethernet header to be whatever you want. Once you've re-
  written the layer 2 header, you can reinject the packet onto the LAN. You can
  even write the packets to a different interface, so that your machine can
  bridge two networks together. Also, if you want to save a tump of all the 
  packets that are forwarded for later viewing, just specify a file name with 
  the -l option. 

  There are 3 important options to xroute. In order to change the destination
  MAC address, use the -d option. To change the source MAC address use the -s
  option, If you want to change the Ethernet type field, use the -t option. 
  There are relavent defaults for each of these options, but if you want the 
  packet to remain completely unaltered, use the -x option. 

  The only confusing part about xroute is the -g option. This is meant to make 
  your life easy allowing you to just specify the local gateway and letting 
  xroute take care of the rest of the details. However, it doesn't make sense to
  use both -d and -g. Only one should be specified and if both options are 
  present -g is ignored. In a normal man-in-the-middle type of attack all you
  need to do is set the filter for the targets packets and then forward them to
  the gateway. Simple! (See the sample directory for an example.)

  The last piece of the puzzle is xdns. Its job is to listen to network traffic
  and wait for DNS packets. If the packet matches the specified domain name, 
  it'll send out a false DNS reply packet, fooling the requesting host into
  connecting to a false server.

  There isn't anything too tricky about using xdns. Just specift the domain
  you want to spoof and the false IP address. You can spoof the local MAC 
  address also. The -t option allows you to set a time-to-live on the DNS reply.
  That is, the host will cache this reply for the number of seconds specified.
  You shouldn't need to modify the port number or the filter, but you have
  access to them if you want too. If you specify the port and a filter, then the
  port will be ignored.

  The final tool included in this version is xdisc. It can be used to determine 
  some information about your local settings, like which network devices are 
  available and what the MAC addresses are. But, its best feature is the -d
  option. This'll scan the LAN and print the IP and MAC of all the hosts it
  finds. Alternatively, you can set it too quiet mode, -q, and it'll passively
  listen to network traffic, printing info on the hosts it sees. Very useful. ;)

  So nopkit gives you a few useful tools that help you manipulate the local 
  network. Hence the name, The Network Operator's Toolkit, letting you route 
  "calls" on the LAN just as if it was an old switchboard at your disposal. If
  you have trouble getting things to work as you expect them, i suggest using
  "-v -v" in your command line arguments. This'll give you a lot more informaion
  and may help solve the problem. Of course, once things are working you should
  remove it as not to slow things down.


Thank You
  I want to thank both the libnet and libpcap teams. As soon as you look
  at the source you'll realise that without their work this project would have 
  taken a whole heck of a lot longer. Also the Winpcap team made the execution
  and port of this program to Windows possible, so many thanks to you guys too.

  Of course I'd like to thank Carleton University and especially Prof. Trevor
  Pearce for letting me do this project. Hope you like it! Also Hubert Sugeng
  my partner in crime. It works. :)

  Lastly, I'd like to thank the Ethereal team. I use it every day and it's 
  helped me out more times then I can count. In this project, I used it more
  then the RFCs relating to DNS, ARP, etc. Thanks!


###############################################################################