Recurity Labs' PortBunny - README
=================================

PortBunny is a Port-Scanner designed to perform classic TCP-SYN
port-scans of large networks in as little time as possible. Its
development is focused on providing clean and sophisticated
timing-code rather than feature-richness.
The port-scan is performed in 2 steps: First the scanner tries to find
packets, which the target responds to ("triggers"). Second, the actual
port-scan is performed. During the scan, the triggers, which were
found in the first scanning-phase, are used to determine the optimal
speed at which the target may be scanned.


Installation
============

Requirements:
Make sure the following components are installed:

(1) Linux-kernel-headers for the kernel in use.
(2) GNU C Compiler and GNU Make.
(3) Python Version 2.4 or above if you want to use the
command-line-interface.


To build PortBunny, do the following:

(1) Make sure you are logged in as root.
(2) Unpack portbunny-VERSION.tar.gz by typing "tar xfz portbunny-VERSION.tar.gz"
(3) Enter PortBunny's directory by typing "cd portbunny-VERSION"
(4) Compile the module by typing "make"
(5) Install PortBunny by typing "make install".

Usage
=====

Basic usage is easy:

# portbunny HOST

to scan HOST which may either be a single IP-address, a range of
IP-addresses (in CIDR-notation) or a domain-name.

Please DO NOT load the module or create the device-file manually, the
UI will take care of this automatically. If you want to talk to
/dev/portbunny directly and not make use of the UI, do the following:

# modprobe portbunny

To scan multiple hosts, simply list them:

# portbunny HOST1 HOST2 ... HOSTn

By default, PortBunny will scan the same ports as NMAP does. This
means ports 1-1024 and ports above 1024 which are listed in the
services file (located in /usr/local/share/portbunny/services
after successful installation).


If you want to scan a different set of ports, use the -p flag:

For example

# portbunny HOST -p 1-65535

will scan all ports.

The -p flag also accepts single ports. For example, if you want to
scan only ports 22, 80 and 23 and 100 to 150 type:

# portbunny HOSTNAME -p 22,80,23,100-150

To perform a host-discovery, use the -d flag. For example

# portbunny 192.168.1.0/24 -d

will tell you which of the hosts in 192.168.1.0/24 were detectable by
PortBunny. Keep in mind that currently arp-pings are not supported so
in local-area-networks PortBunny sometimes discovers less hosts than
NMAP.

For more options, type

# portbunny --help

Once a scan is in progress (after host-discovery has been performed)
you can obtain information about the scan and change some of its
parameters using the following keys:

a: Abort the current group
+: Increase the number of jobs used in the next group.
- : Decrease the number of jobs used in the next group.
l : List active jobs
Any other key: View progress-report

By default, the number of jobs per group will be 1 which means that
one host is scanned at a time.


Triggers
========

The following triggers (ordered by quality) have been implemented:

TCP_SYN-$PORT:
	Sends a TCP packet to $PORT with the SYN-flag set.
	Awaits a TCP-packet with ACK- and RST- or SYN- and ACK- flags set.
	
TCP_ACK-$PORT:
	Sends a TCP packet to $PORT with the ACK-flag set.
	Awaits a TCP-packet with the RST-flag set.


ICMP_ER-0:
	Sends an ICMP-Echo-Request (ping).
	Awaits an ICMP-Echo-Reply.

ICMP_TS-0:
	Sends an ICMP-Timestamp-Request.
	Awaits an ICMP-Timestamp-Reply.

ICMP_ADDR-0:
	Sends an ICMP-AddressMask-Request.
	Awaits an ICMP-AddressMask-Reply.

UDP-$PORT:
	Sends a UDP-datagram to $PORT.
	Awaits an ICMP-destination-unreachable with code "Port-unreachable".
	Note: ICMP-destination-unreachables are frequently rate-limited.


IP_PROT-$PROTOCOL:
	Sends an IP-packet with the protocol-field set to $PROTOCOL.
	Awaits an ICMP-destination-unreachable with code "Protocol-unreachable".
	Note: ICMP-destination-unreachables are frequently rate-limited.
	

Hacking
=======

If you want to start hacking on the kernel-module, install doxygen and
generate the html-documentation from the source-code by typing:

# doxygen ./Doxyfile.in

in PortBunny's root-directory.

If you are interested in writing a user-interface, take a look at
UI/interface.py written which is an object-oriented python-interface
to PortBunny. A complete list of supported commands can also be found
in the Documentation generated by doxygen.

If you have any questions concerning the source-code, please write me
an e-mail directly.

We're also looking for people who would like to spend their free time
helping with the code, so feel free to contact me about that as well.


Bugs
====

If you can reproduce a bug, please perform the scan with the -l option
and send us the generated log-file "scan_log.txt".

Contact
=======

Fabian Yamaguchi <fabs@recurity-labs.com>