CS557 (Fall 2017) Project #1

Home Page | Syllabus | Class Schedule

Table of Contents

1 Project outline

Network scanning is a method for identifying live hosts on a network or active services on a host. Scanners are routinely used by malicious people for reconnaissance before an attempt is made to compromise machines. In general, there are two types of network scanning:

  • Horizontal scan: A horizontal scan is described as scan against a group of IP addresses over a single port. In other words, a scanner may be looking for all active web servers in a subnet, so it scans all IP addresses on port 80.
  • Vertical scan: A vertical scan is described as a single IP address being scanned for multiple live ports. For example, a scanner may scan all ports on a host looking for active services.

Scanners may be engaged in either type of scan. Indeed, it is very likely that a scanner will be engaged in both types at the same time.

In this project, you will implement a simple, yet robust scanner detector. You need to think about what behavior your detector will look for and how scanners might try to evade it. For example, no descent scanner will scan all IP addresses sequentially (but if it does, you should be able to detect it). Your scanner will need to leverage libpcap, which will be introduced in the following.

2 libpcap

libpcap is a software library ("pcap" stands for "packet capture") for collection and analysis of raw network packets. It can either intercept packets as they are being sent/received on a machine's network interface, or read packets offline from a packet trace file which was previously captured. A fine introductiont to libpcap programming in C can be found at http://www.tcpdump.org/pcap.html. Note that you may need to find additional manuals/resources on your own in order to complete the assignment.

Libpcap is directly usable from C/C++ programs (simply include the appropriate files and link against the libpcap library during compilation). Libpcap also come with bindings for various programming languages. In Python, libcap functionality can be accessed using the pypcap and dpkt modules.

2.1 Using pypcap on lab machines

Using the pypcap Python module on lab machines requires the PYTHONPATH environment variable to be initialized as follows:

export PYTHONPATH="$PYTHONPATH:/usr/local/pypcap/lib64/python2.7/site-packages/"

3 Requirements

Your tool should be able to read a pcap file (or live capture) and find out suspicious network scanning activities. It needs to analyze TCP, UDP, and ICMP flows looking for scanners. It should support the following options:

scandetect [-r filename] [-i interface] [-t time] [-o time_offset] [-S secs] [-h HNum] [-p PNum] [-V]

Running the tool with no options should produce a usage message.

The tool should read the trace file specified by [-r filename] (or live capture using the specified interface), and print out the detected scanners, the number of hosts and/or ports scanned by each scanner, and the type of scanning. -t specifies the time your detector will run, either in the live capture or the input file. The -o option is valid only when reading from a file and specifies the offset into the file your detector will start reading. The [-i interface] option specifies the interface name to do the live capture. When the interface option -i is applied, the offset option -o is ignored and the time option -t option specifies the running time of your tool. The [-S secs] option specifies the timeout interval S for a flow (S is 60s in default). If a flow is longer than S, it may be treated as two or more flows.

The [-h HNum] and [-p PNum] are the number of hosts and the number of ports that a host must scan to be considered scanning respectively. Pick reasonable defaults for both of these and justify your selection. For example, host pinged 65 different hosts using ICMP. If your threshold was 64 then this would be classified as a scanner. Your detector should look for scanners on all hosts and ports.

For each run, your detector should print the summary. The summary contains Scanner, #HostsScanned, #PortsScanned. #HostsScanned and #PortsScanned are the number of distinct hosts and ports that are scanned. Note that ports for UDP and TCP are distinct, for example, TCP port 53 and UDP port 53 are two differnt ports. Here is a sample output to show the Scanner summary:


[-V] is the verbosity option. When specified, your detector must print the scanning records in detail and then the summary. Each record must contain Scanner, Proto, HostScanned and PortsScanned. HostScanned is the actual hosts, and PortsScanned is the ports per host. Below is a sample output:


You may test your tool using nmap scanner, a popular tool to perform port scans. Here is an example of nmap usage:


4 Submitting your work

You are free to develop your homework as you see fit, using either C, C++ or Python 2. However, your work must successfully compile (if you are using C/C++) and run (if you are using C, C++ or Python) on CS lab machines. The machines have libpcap (for C/C++ implementations) and dpkt/pypcap preinstalled. If you wish to use additional tools/libraries you must integrate them with your codebase (i.e. we will not perform any modification or addition to the machines in order to evaluate your program, so your program must be self-contained).

This is an individual project. You are welcome to discuss issues and programming tips with your classmates, but you are not allowed to team up with anyone.

What to turn in (and how)

To turn in, put the following in a tar.gz file and name it as follows: p1_557.<your_name>.tar. Then submit it in Canvas by the deadline (the upload page is available on the course Canvas page under the Assignments tab; the assignment you need to use for uploading is named First class project). When expanded, the .tar.gz file should create a directory called p1_557.your_name and the following files should be there (you may have more if you need to):

  • Makefile: typing "make all" should make the executable. Typing "make clean" should clean up all object and executable files. You do not need to have this file if you are using Python.
  • scandetect.c[cc][py]: the source code.
  • A README file: describe what this program is and what it does. Tell me of any bugs or known issues. Also tell me of any web resources you used. Use of code found online and not mentioned in the README file will be treated as plagiarism.

5 Grading

  • No credit will be given to a program that fails to compile or start on CS lab machines
  • 5% The program does not crashes on startup
  • 5% README included and contains enough information to run program.
  • 10% usage message produced if no options provided, input flags accepted in any order and sanity-checked.
  • 10% printing the records as user specified (using -h and -p).
  • 10% only flows in the specified time considered.
  • 40% printing records correctly.
    • 25% for [-V] option;
    • 15% for summary.
  • 10% live capture works.
  • 10% unrecognized traffic(ex:ARP packets) does not crash the program.

This project description may change at the discretion of the instructor.

Author: Lorenzo De Carli

Created: 2017-10-11 Wed 14:04