HoneydScan - by Eric Thomas @ Sandia National Laboratories

This set of scripts was written in order to test how accuratly Honeyd
is able to emulate the TCP/IP stack of other operating systems. The tests
were based solely upon the results of NMAP scans with the -O and --osscan_guess
option. This is because honeyd uses the NMAP fingerprint file for most of its
stack emulation.

Files
-----------------------------
Main scripts:
honeyd.config.pl - A script that creates a honeyd configuration file
  (associated with the -f option of Honeyd) based upon a file called
  nmap-os-fingerprints.

performscan.pl - A script that performs the NMAP tests. The program runs
  the NMAP program, then parses the output of the program to determine how
  well Honeyd emulated the OS.

evaluatescan.pl - A script that summarizes the output of performscan.pl
  by tabulating the number of correct and incorrect guesses.

Support scripts:
compare.sh - A script that compares the results of two evaluated scans. This
  was written to be used while a scan is running to compare how the current
  test is evaluating compared to a previous test at the same point.

getos.pl - A script that will use the honeyd configuration file (generated by
  honeyd.config.pl) and the nmap-os-fingerprints file to determine what OS
  is bound to an IP address, and optionally display the associated NMAP
  fingerprint.

Other files:
README - This file, duh!

nmap-os-fingerprints - The fingerprints file that comes with NMAP 3.27.

honeyd.config - A sample file generated by the honeyd.config.pl script using
  the supplied nmap-os-fingerprints file.

Organization
-----------------------------
This test is meant to be run on two computers. One computer is to run Honeyd,
and the other runs the test.

Along with Arpd and any other required programs, Honeyd is to be run by a
command similar to:

  honeyd -f honeyd.config -p nmap-os-fingerprints [...xprobe stuff]

The honeyd.config file should have been generated by using the honeyd.config.pl
script. Since the honeyd.config.pl script uses the nmap-os-fingerprints file,
it is best to use the same nmap-os-fingerprints file for the script and for
honeyd. It is most preferrable to use the fingerprint file from the latest
version of NMAP because it will probably have more fingerprints.

The honeyd.config file is setup as follows:
  - Each OS in the fingerprints files is associated with exactly one template
  - Each template has exactly one IP address bound to it
  - The IP addresses:
    - Class B (mask 255.255.0.0). The prefix is specified by the $ip_prefix
      variable in honeyd.config.pl (currently 10.2).
    - The 3rd and 4th octets in the IP address have a range of 1 to 254.
  - The nmap-os-fingerprints file is specified by the $fp_file variable in
    honeyd.config.pl (currently nmap-os-fingerprints).
  - For each template, the only open port is port 80 (uses the scripts.web.sh
    script), and the default tcp action is reset.
  - The resulting configuration file is saved to a file specified in the
    $out_file variable in honeyd.config.pl (currently honeyd.config).

As an example, the first IP address is associated with the first OS listed
in the fingerprints file. The second IP address is associated with the second
OS, and so on.

The test, then, performs an NMAP scan against each of the IP addresses that
the config file binds to a template. The test is performed by performscan.pl.
The performscan.pl script:
  - Takes over 2 hours to run in its current implemenation (linear).
  - Determines the number of IP addresses to test and stores the names of
    all of the OSes from the fingerprint file. The fingerprint file is
    specified in the $fp_file variable in performscan.pl (currently
    nmap-os-fingerprints).
  - All output is appended to the scan.txt file in the current directory.
  - For each OS,
    - Determines the IP address that OS should be associated with.
    - Performs the nmap scan, capturing the output. The program performs a
      stealth SYN scan, meaning root user privileges are required. Also, the
      nmap command is assumed to be in the PATH.
    - Only ports 80 (open) and 2000 (closed) are scanned to minimize scan time.
    - The output of the scan is parsed to determine if NMAP:
      - Is 100% sure of the OS
      - Is reasonably sure of the OS (one of a few listed that are match 100%)
      - Is unsure but provided its best guess
      - Determined that no OS matched
      - Determined that too many OSes matched
    - The results are matched against what the OS should be as emulated by 
      honeyd (assumes the same nmap-os-fingerprints file was used to create
      the honeyd.config file).
      - If NMAP was 100% sure and was correct, the following line is output:
           +NMAP is sure <IP address> is <OS>
      - If NMAP was 100% sure and was incorrect, the following line is output:
           -NMAP is sure <IP address> is <OS>
      - If NMAP was 100% sure but guessed multiple OSes, the following line is
        output:
           ~NMAP is sure <IP address> is <OS>
      - If NMAP guessed (thanks to --osscan_guess) correctly, the output is:
           +NMAP guesses <IP address> is <OS>
      - If NMAP guessed incorrectly, the output is:
           -NMAP guessed <IP address> is <OS>
      - If NMAP found too many matches the output is:
           -NMAP found too many matches for <IP address> - <OS>
      - If NMAP found no matches the output is:
           -NMAP found no match for <IP address> which is <OS>
  - These output lines are parsed by the evaluatescan.pl script to give a
    summary of results.
  - The date and time are added before and after the scan to keep track of
    how long the test took.

Use evaluatescan.pl to parse the test output to give a summary of results. The
program takes one optional argument, the name of the performscan.pl output
file (default: scan.txt).

Review of how to use the scripts
-----------------------------
Situation:
  Host A - The computer to scan from
  Host B - The computer running honeyd

Step Host A                                Host B
-----------------------------------------------------------------------------
1    Set the variables in performscan.pl   Set the variables in honeyd.config.pl
2                                          Run honeyd.config.pl
3                                          Run honeyd with resulting config file
                                             and same fingerprint file
4    Run performscan.pl
5    Monitor progress with compare.sh,
       if desired
6    When the test is done, use
     evaluatescan.pl to get test stats
