HoneyRJ User Manual

Eric Peter, epeter@wustl.edu Todd Schiller, tschiller@acm.org (Under guidance of Prof. Raj Jain)

Table of Contents:

1 Introduction

This application, HoneyRJ, is an implementation of a low-interaction honeypot. A low-interaction honeypot serves a number of limited functionality protocols with the intent of capturing the source of traffic coming to the honeypot. A honeypot is located on an IP address that is used solely for the purpose of the honeypot and not for any legitimate services; any connections to the software are presumed to be malicious and are logged for later review. HoneyRJ was designed to be extremely simple and easily extendable.

This first release can emulate both FTP and IRC servers. HoneyRJ logs all interactions, allowing users to identify potential attack vectors. This user manual shows how to set up and run HoneyRJ on your computer.

Back to Table of Contents

2 System Requirements

In order to run HoneyRJ, the end user must have the following minimum software requirements:

HoneyRJ also has to following minimum hardware requirements:

Back to Table of Contents

3 Application Setup

The following section outlines the process of software configuration and installation. HoneyRJ is unique in that all configuration is done in the source code and therefore must be done at compile time.

3.1 Configuration

HoneyRJ has four configurable options. If the defaults are acceptable to you, you are encouraged to use the provided binary and not re-compile the application.

If you wish to configure these options, please import the provided Eclipse project into Eclipse following the instructions available in the Eclipse documentation and then follow these steps.

  1. Open the file src\honeyrj\HoneyRJ.java
  2. To adjust the connection timeout, find the following line and change the default value to your desired value in milliseconds.
  3. To adjust the logging direction, find the following line and change the default value to your desired logging directory (trailing slash is required). Due to the special nature of the \ character in Java, you must represent a \ with a \\.
  4. To set whether HoneyRJ writes all log messages to the console, find the following line and change the value to true. If you wish to keep the default configuration of not writing to the console, keep the value as false.
  5. To adjust the waiting period between connections, find the following line and change the default value to your desired value in milliseconds. We recommend keeping this a reasonable number (under 10 seconds) or clients will expierence large timeouts attempting to connect.

Once you have made the desired changes, follow the instructions available in the Eclipse documentation to generate a runnable JAR file.

3.2 Installation

To install HoneyRJ, place the created JAR file (or the provided HoneyRJ.jar file) in the desired installation directory.

Back to Table of Contents

4 Application Overview

The following section outlines the steps to launch HoneyRJ and provides a brief overview of the the application GUI, in addition to defining terminology specific to HoneyRJ. After reading this section, you should have a good understanding of what features HoneyRJ provides.

4.1 Running HoneyRJ

If you have reconfigured the application as described above, please replace any reference to the provided file HoneyRJ.jar with your exported JAR file.

To launch the application, double click HoneyRJ.jar. The application will launch and you will see a window similar to figure 1.

Figure 1. HoneyRJ main application window upon initial startup
HoneyRJ main application view upon initial startup

4.2 User Interface Overview

There are two main parts of the application - the top pane and the module pane. The top pane contains a legend and buttons that affect all installed modules. Below the top pane, is the module pane, which contains a representation of each module that is a part of the application.

In the top pane, you see four legend icons and three buttons. The legend icons are a key to the colors that represent the four states of a module.

The three buttons are used as follows:

The module pane contains a section for each module loaded into the application. Each module contains three buttons that have the same functionality as those in the top header, but they only affect that module. Each module lists the common name of its protocol and the port on which it runs. Finally, each module displays the number of currently connected clients.

4.2.1 What is a Module?

A module represents one protocol running within HoneyRJ. A module provides the implementation of a protocol to allow HoneyRJ to communicate with clients as if it were a server running that protocol. A module has four states: stopped, paused, started and error. HoneyRJ can run one or more modules simultaneously.

Back to Table of Contents

5 Application Workflow

The following section describes the usage of HoneyRJ in several common tasks. You must have the application configured and running to use this section. As mentioned in the prerequisites, please ensure you do not have any firewalls running that would prevent clients from connecting to your machine. After reading this section, you should have an understanding of how to use the features HoneyRJ provides.

5.1 Starting/Stopping/Pausing Modules

To start all the modules in HoneyRJ, click the Start All button in the top pane. You will see each module turn from red to green, indicating the modules are now listening for connections.

If you only wish to start a subset of modules, click the Start button contained within each desired module's section. The module will turn from red to green, indicating that it is now listening for connections.

To verify that HoneyRJ is listening for connections, perform the following steps.

  1. Go to the Windows Start menu and choose Run
  2. In the Run dialogue, type telnet localhost <PORT> where <PORT> is replaced by the running module's port number and press Enter. For example, to connect the FTP protocol, type telnet localhost 21
  3. You will now see a Telnet session open, similar to what is shown in figure 2, where you can interact with the protocol. If the window opens and immediately closes, refer to the troubleshooting section for steps to ensure the module is properly started.
  4. In the HoneyRJ module pane, you should see "Hackers connected: 1" in the module to which you connected, similar to figure 3.
  5. Close the Telnet application window, you should see hackers connected change to 0
Figure 2. Telnet session showing interaction with HoneyRJ's FTP protocol
Telnet session showing interaction with HoneyRJ's FTP protocol
Figure 3. HoneyRJ application viewing showing one connection to the FTP protocol
HoneyRJ application viewing showing one connection to the FTP protocol

The steps for stopping modules are identical to the steps for starting a module. Replace any reference to start with stop.

The steps for pausing modules are identical to the steps for starting a module. Replace any reference to start with pause.

5.2 Viewing Log Files

HoneyRJ logs every connection into an individual file. When HoneyRJ launches, it creates a directory named with a timestamp in the configured logging directory (by default the directory is c:\tmp\). For example, the log files created while writing this documentation were stored in C:\tmp\rj_1238883728078_log\.

Each connection to HoneyRJ creates a new text file within this directory, named by the protocol name, followed by a timestamp and given the extension log. An example of a log file name for the FTP protocol is FTP_1238884135628.log. Log files are updated in real time, that is, whenever a packet is sent or received, it is appended to the log file. If you wish to monitor the logs files in real time, we suggest an application similar to Tail for Win32 [Tail4Win]

5.2.1 Log File Format

A log file consists of the following header lines, which describe the time the connection started, followed by a description of the logging format.

******Started at: Sat Apr 04 16:28:55 CST 2009********

After the header lines, details of each sent or received packet is logged. The following information is stored about each packet, in the order that appears below.

Each packet sent or received is logged on a separate line. An example of a line representing a sent packet is listed below:

Sat Apr 04 16:28:55 CST 2009,,,220 Service ready for new user.

Immediately following the packet information are the footer lines, which describe how and when the connection terminated. The examples used below are from a FTP connection.

For a connection that closed due to a connection timeout, the following lines appear.

*****Protocol FTP TIMED OUT talking to / using local port 21, connection closed.****
*****Stopped at: Sat Apr 04 16:30:58 CST 2009*******

If the connection closed normally, the following lines appear instead:

*Protocol FTP is finished talking to / using local port 21****
*****Stopped at: Sat Apr 04 16:46:29 CST 2009*******

5.3 Recovering from an Error State

If a module cannot start listening on the port specified by its protocol, it will be in the error state. The error state is visually indicated by the module's section turning to orange. See figure 4 for an example of the FTP module in the error state. An error happens when HoneyRJ cannot bind to the module's specified port. There are two reasons why the error state could happen:

Figure 4. HoneyRJ application indicating the FTP protocol could not listen on port 21
HoneyRJ application indicating the FTP protocol could not listen on port 21

5.4 Closing HoneyRJ

To close the application, click the X button in the top right corner. All active connections will be closed.

5.5 Troubleshooting

If the application fails to start, ensure that your configured logging directory exists and is writeable. The application will attempt to create a directory within the configured logging directory and will exit upon failure.

Back to Table of Contents