Wiki Navigation

User Guide

Here you'll find how to install, configure, and administer honeyclients using the HoneyClient framework.
(Comments are provided for each step, as needed.)

If you would like to monitor changes to this page, feel free to subscribe for notifications.

Host System
Firewall VM
1. Download Firewall VM
2. Initialize Firewall VM
Honeyclient VM
Drone Service
Startup
1. With Drone Support (Default)
2. Without Drone Support (Not Default)
Upgrading
1. Honeyclient
  1. Host System
  2. Master VM
2. Drone
Notes
Troubleshooting

Host System

To begin, you'll need to setup and initialize your host system.

Install and Configure Linux

1. Install Linux on your host system. Make sure you pick a Linux distribution that is compatible with VMware Server. Make sure the host has at least 1.5 GB of RAM free. Also, make sure the host has adequate disk space, as it will contain at least one master Honeyclient VM (2-8GB) and may contain multiple, cloned Honeyclient VMs (500MB+, each).

2. Verify that Perl version 5.8.8 or higher (with ithreads support enabled) is installed on the host system. This can be verified by typing the following:

# perl -v

This is perl, v5.8.8 built for i486-linux-thread-multi
...

The thread-multi text indicates that perl was compiled with ithreads support. If your host system's perl implementation does not have ithreads support enabled, then you must reinstall perl with this support. Many Linux distributions offer pre-compiled binary versions of perl with ithreads support enabled. Or, you can enable it when manually compiling perl, during the ./Configure step, by answering yes to the following question:

Perl can be built to take advantage of threads on some systems.
To do so, Configure can be run with -Dusethreads.

Note that Perl built with threading support runs slightly slower
and uses more memory than plain Perl. The current implementation
is believed to be stable, but it is fairly new, and so should be
treated with caution.

If this doesn't make any sense to you, just accept the default 'n'.
Build a threading Perl?
[yes]

3. As root, create the following directories to store all VM data on the host system.

# mkdir /vm
# mkdir /vm/clones
# mkdir /vm/master
# mkdir /vm/snapshots

4. Verify that the host system has a syslog daemon installed. If the host system does not have syslog installed, install one according to your Linux distribution documentation.
(We installed syslog-ng, but you can also use the older sysklogd.)

5. Identify the primary system file that contains syslog messages and make sure this file is group and world readable.
(With syslog-ng or sysklogd, the primary syslog file is /var/log/messages.)

# chmod 644 /var/log/messages

Note: It is likely that your host system has a log file rotation script that runs to keep the syslog file from filling all disk space. Make sure that when log file rotation occurs, the newly rotated syslog file is also group and world readable.

6. Configure the syslog daemon to output all messages to the primary log file (/var/log/messages). Examples of how to do this are listed here: syslog-ng and sysklogd.

7. Verify that the host system has the following programs and libraries installed. They are required in order for the HoneyClient code to properly run:

gcc
make
glibc
expat
subversion (optional, for code upgrades)

Install VMware Server

1. Install VMware Server on the host system according to the VMware installation documentation. You will also need to obtain the free serial numbers by registering with VMware.
(We installed VMware Server using the tar installer by running the ./vmware-install.pl script as root. For convenience, we have provided below some of the questions the VMware Server installer will ask, along with our responses for our Gentoo Linux host system. Our responses are listed in square brackets [].)

# ./vmware-install.pl 
Creating a new installer database using the tar3 format.

Installing the content of the package.

In which directory do you want to install the binary files?
[/usr/bin]

What is the directory that contains the init directories (rc0.d/ to rc6.d/)?
[/etc]

What is the directory that contains the init scripts?
[/etc/init.d]

In which directory do you want to install the daemon files?
[/usr/sbin]

In which directory do you want to install the library files?
[/usr/lib/vmware]

The path "/usr/lib/vmware" does not exist currently. This program is
going to create it, including needed parent directories. Is this what you want?
[yes]

In which directory do you want to install the manual files?
[/usr/share/man]

In which directory do you want to install the documentation files?
[/usr/share/doc/vmware]

The path "/usr/share/doc/vmware" does not exist currently. This program is
going to create it, including needed parent directories. Is this what you want?
[yes]

The installation of VMware Server 1.0.4 build-56528 for Linux completed 
successfully. You can decide to remove this software from your system at any 
time by invoking the following command: "/usr/bin/vmware-uninstall.pl".

Before running VMware Server for the first time, you need to configure it by 
invoking the following command: "/usr/bin/vmware-config.pl". Do you want this 
program to invoke the command for you now? [yes] 

Making sure services for VMware Server are stopped.

Stopping VMware services:
   Virtual machine monitor                                             done

You must read and accept the End User License Agreement to continue.
Press enter to display it. 

<cut>

Do you accept? (yes/no) yes

Thank you.

Configuring fallback GTK+ 2.4 libraries.

In which directory do you want to install the mime type icons? 
[/usr/share/icons] 

What directory contains your desktop menu entry files? These files have a 
.desktop file extension. [/usr/share/applications] 

In which directory do you want to install the application's icon? 
[/usr/share/pixmaps] 

Trying to find a suitable vmmon module for your running kernel.

None of the pre-built vmmon modules for VMware Server is suitable for your 
running kernel.  Do you want this program to try to build the vmmon module for 
your system (you need to have a C compiler installed on your system)? [yes] 

Using compiler "/usr/bin/gcc". Use environment variable CC to override.

What is the location of the directory of C header files that match your running
kernel? [/lib/modules/2.6.22-14-generic/build/include] 

Extracting the sources of the vmmon module.

Building the vmmon module.

<cut>

Do you want networking for your virtual machines? (yes/no/help)
[yes]

Configuring a bridged network for vmnet0.

The following bridged networks have been defined:

. vmnet0 is bridged to eth0

All your ethernet interfaces are already bridged.

Do you want to be able to use NAT networking in your virtual machines? (yes/no)
[yes] 

Configuring a NAT network for vmnet8.

Do you want this program to probe for an unused private subnet? (yes/no/help) 
[no]

What will be the IP address of your host on the private 
network? [192.168.0.1]

What will be the netmask of your private network? [255.255.255.0]

The following NAT networks have been defined:

. vmnet8 is a NAT network on private subnet 192.168.0.0.

Do you wish to configure another NAT network? (yes/no) [no] 

Do you want to be able to use host-only networking in your virtual machines? 
[yes] 

Configuring a host-only network for vmnet1.

Do you want this program to probe for an unused private subnet? (yes/no/help) 
[no]

What will be the IP address of your host on the private 
network? [10.0.0.1]

What will be the netmask of your private network? [255.255.255.0]

The following host-only networks have been defined:

. vmnet1 is a host-only network on private subnet 10.0.0.0.

Do you wish to configure another host-only network? (yes/no) [no] 

Extracting the sources of the vmnet module.

Building the vmnet module.

<cut>

Please specify a port for remote console connections to use [902] 

Stopping internet superserver: xinetd.
Starting internet superserver: xinetd.
Configuring the VMware VmPerl Scripting API.

Building the VMware VmPerl Scripting API.

Using compiler "/usr/bin/gcc". Use environment variable CC to override.

Installing the VMware VmPerl Scripting API.

The installation of the VMware VmPerl Scripting API succeeded.

Generating SSL Server Certificate

In which directory do you want to keep your virtual machine files? 
[/vm]

Please enter your 20-character serial number.

Type XXXXX-XXXXX-XXXXX-XXXXX or 'Enter' to cancel:  [Enter Serial Number]

Starting VMware services:
   Virtual machine monitor                                             done
   Virtual ethernet                                                    done
   Bridged networking on /dev/vmnet0                                   done
   Host-only networking on /dev/vmnet1 (background)                    done
   Host-only networking on /dev/vmnet8 (background)                    done
   NAT service on /dev/vmnet8                                          done

The configuration of VMware Server 1.0.4 build-56528 for Linux for this running
kernel completed successfully.

Configure VMware Server

1. Verify the host system's virtualized network. The Honeyclient architecture expects the following virtualized networks to exist in the host system. These networks can be setup and configured by running the /usr/bin/vmware-config.pl command as root. You will have to go through a few of the previous installation steps before you see the following network configuration, and you will have to complete any of the remaining prompts after you see this output in order to properly restart vmware.

/dev/vmnet0 - Bridged to external interface (e.g., eth0)
/dev/vmnet1 - Host Only class-C network (10.0.0.1/24)
/dev/vmnet8 - NAT class-C network (192.168.0.1/24)

The following image describes this network architecture in further detail:

2. Edit the VMware Server host-only network DHCP daemon file (/etc/vmware/vmnet1/dhcpd/dhcpd.conf) as root and change the subnet block to read:

subnet 10.0.0.0 netmask 255.255.255.0 {
    range 10.0.0.128 10.0.0.253;
    option broadcast-address 10.0.0.255;
    option domain-name-servers 192.168.0.2;
    option domain-name "localdomain";
    option routers 10.0.0.254;
}

Note: Be sure to restart VMware Server (using /etc/init.d/vmware restart) after making these changes, in order for the new settings to take effect.
(For all VMs that connect to the host-only network and obtain a DHCP lease, all of their network traffic will be subsequently routed through the Firewall VM, which will have the IP of 10.0.0.254.)

3. Configure the syslog daemon on the host system to accept remote syslog messages over interface 10.0.0.1 using UDP port 514. Examples of how to do this are listed here, for syslog-ng and sysklogd.

Download the Honeyclient Package

1. Create a user account on the host system and change to the user's home directory (e.g., /home/user).

2. Download the Honeyclient package, either from the SVN repository or from the website.

From SVN:

svn co svn://svn.honeyclient.org/honeyclient/tags/rel/1.0.2 honeyclient

Download and extract the latest version from the downloads page.

This guide assumes the data has been downloaded/extracted to the /home/user/honeyclient directory.

Initialize CPAN

1. Before installing any HoneyClient packages, you have to initialize the cpan perl utility. As root, type cpan at the host system prompt. If cpan has never been initialized before, then it will proceed to ask a series of questions. If you have never configured CPAN before, please see this example to provide answers to these questions. Note: If you have configured CPAN before, or you have had trouble installing CPAN dependencies and are restarting the process, first visit the UserGuide/PerlGuidance page to perform some pre-processing.

If you are comfortable configuring CPAN, then only the following options need to differ from the defaults significantly. The example assumes your username is "user" and your copy of the Honeyclient source is in the directory /home/user/honeyclient.

Provide a custom build/cache directory:

CPAN build and cache directory? [/root/.cpan] /home/user/honeyclient/cpan

And to install the perl requirements from the local copy (which is recommended) you should not use any online mirrors, and instead type:
```
cpan> o conf urllist = file:///home/user/honeyclient/cpan
```
If you already have the perl Build module installed (as determined in UserGuide/PerlGuidance) then the command should instead be
```
cpan> o conf urllist file:///home/user/honeyclient/cpan
```

Note: Be sure to specify proxy servers in your CPAN configuration, if needed.

Install Perl Dependencies

1. Once CPAN is configured, you will need to install the perl module dependencies. We provide a Bundle to make the installation simpler; however, a couple modules should be forcibly installed so as to avoid possible problems. Execute the following command:

cpan> force install Scalar::Util
...
/usr/bin/make install  -- OK

(Optional explanation)

If you do not see the "/usr/bin/make install -- OK" line after this command, please report the full output that was generated.

2. Now, you can install the prerequisites by typing the commands listed below.

Note: At times, you may be prompted for input from some perl modules. However, prompts for missing dependencies will generally signify an error. To be clear, we have provided the following list of known perl prompts which can help differentiate between expected prompts (and the appropriate input, usually the default values) and prompts which are unexpected. If you encounter a prompt not listed on this page, please include it in a new ticket.

cpan> install Bundle::CPAN
...
cpan> install Bundle::HoneyClient::Util
...
/usr/bin/make install  -- OK

cpan> install Bundle::HoneyClient::Manager
...
/usr/bin/make install  -- OK

cpan> exit

If you do not see the "/usr/bin/make install -- OK" line after the last two commands, please report the full output that was generated.

TODO: Ideally, we would include something here about running the tests for HoneyClient::Util and HoneyClient::Manager. However, those unit tests are currently out-of-date, so we will not include testing instructions in this verison of the guide.

Configure HoneyClient::Manager

1. Edit the ~/honeyclient/etc/honeyclient.xml file.

TODO: If you decided to chose different /dev/vmnet1 and /dev/vmnet8 network configurations, other than the aforementioned defaults, then you will need to change various IP addresses and subnet settings listed in the ~/honeyclient/etc/honeyclient.xml. This mode is unsupported at this time; we will eventually provide further documentation on how to properly configure these settings.

Make sure the master_vm_config points to the full, absolute path to the master Honeyclient VM configuration file (as explained in the Honeyclient VM section).

<HoneyClient>
    <Manager>
        <VM>
            <master_vm_config description="The full absolute path to the VM configuration file on the host system that will be used by all subsequent cloned VMs.">
                /vm/master/master.vmx
            </master_vm_config>
        </VM>
    </Manager>
</HoneyClient>

If listed, make sure you edit the organization entry.

<HoneyClient>
    <organization description="The name of the organization that owns the host system.">
        Your Organization Name
    </organization>
</HoneyClient>

Firewall VM

Next, you'll want setup your Firewall VM, in order to provide your Honeyclient VMs with network connectivity.

TODO: Rather than document steps on how to setup and configure your own Firewall VM, we provide you with a working pre-built Firewall VM that already functions properly, using the default network configuration. This component will be documented further, eventually. Ticket #46 has been created to address this issue.

Download Firewall VM

1. Download and extract the latest Firewall VM archive (firewall-3.tar.gz) onto the host system as root.

# cd /vm
# wget http://honeyclient.mitre.org/firewall-3.tar.gz
# tar zxvf firewall-3.tar.gz

Once extracted, there should be a "firewall-3" subdirectory that contains the firewall VM data.

Initialize Firewall VM

1. As root on the host system, register the Firewall VM either by browsing to the file from withing VMware Console or by executing the following command:

# vmware-cmd -s register /vm/firewall-3/honeywall.vmx

2. Execute VMware Server Console and login to the host system as root.

3. Verify that a new VM named "Firewall VM [v3]" appears in the VMware Server Console inventory on the host system.

4. Power on the firewall VM.

5. Once booted, login to the firewall VM, using the login name of "roo" and password of "password".
(You can also ssh into the firewall VM from the host system by using roo@192.168.0.128.)

Note: As the normal user of "roo", you can also obtain root access to the system via the "su" command, using the root password of "password".

6. Verify that the HoneyClient::Manager::FW daemon is running, by performing the following command in a firewall VM shell:

$ ps ax | grep startFW | grep -v grep
2520 ?        S      0:01 /usr/bin/perl /hc/startFWListener.pl

You should see a perl process running, as shown in the example above.

Honeyclient VM

Next, you'll need to create a new master Honeyclient VM and properly initialize the master, before the manager can create and use clones of this VM.

Create Master Honeyclient VM

1. Create a new Windows master VM via the VMware Server Console, as directed in the VMware Server documentation. Specifically, be sure to do the following in the New Virtual Machine wizard:

Select a typical VM configuration.
Select a Windows OS.
Specify the VM name: "master"
Specify the VM location: "/vm/master"
Use network address translation (NAT) as a network connection.
Specify a disk size of at least 4 GB. (We chose 8 GB.)
- Do not allocate all disk space. (To improve disk space efficiency.)
- Split the disk into 2 GB files. (For easy backups to external media.)

2. Power on the master VM and install the desired variant of Microsoft Windows.

3. When creating the Administrator account, be sure to specify a corresponding password. (Otherwise, you will be unable to configure the OS for auto-login later.)

4. Once Windows is installed on the master VM, shutdown and power off the master VM. Next, edit the master's virtual machine settings in the console and make the following changes:

Select the Hardware tab.
In the Memory section, set the VM memory to be 384 MB. (Required.)
Remove the Floppy hardware device. (Speed improvement.)
Select the CD-ROM device and uncheck both the "Connected" and "Connect at power on" checkboxes. (Speed improvement.)
Select the Options tab.
In the Permissions section, uncheck the "Make this virtual machine private" checkbox. (Permissions setting.)
Save changes.

Configure Windows OS

1. Power on the master VM and boot up the OS. When logged in as a normal user for the first time, go to Control Panel and double-click on the Users Accounts section. "Change the way users log on or off" by disabling the "User the Welcome screen" checkbox. Click "Apply Options".

2. Log off and log back in as the Administrator account, using the password you used during the Windows install process.

3. Install VMware Tools. Once installed, click on the VMware Tools icon in the system tray of the VM's OS. Make sure you select the "Time synchronization between the virtual machine and the host operating system" checkbox in the Options tab.

4. Disable the Windows Update Service. Go to Control Panel and double-click on the Automatic Updates section. Make sure "Turn off Automatic Updates" is selected. Also, go to Control Panel and double-click on Administrative Tools, then double-click on Services. Right click on the Automatic Updates service and select Properties. Change the Startup Type from Automatic to Disabled. Click on the "Stop" button to stop the service, and then click "OK". (If you do not do this, the Windows Update service will generate false positives during the Honeyclient integrity check process.)

5. Start up Microsoft Internet Explorer (IE) and/or download, install, and start Mozilla Firefox (FF). Verify that the browser(s) start up without any additional user prompts. If any prompts appear, dismiss them, close, and restart IE/FF to verify no new prompts appear. Be sure to drive IE/FF to normal https-enabled websites, in order to acknowledge SSL-related popups and prevent IE/FF from displaying them further. Depending upon the version of IE/FF installed, you may have to configure IE/FF further, in order to disable these prompts (e.g., popup blocking). For example, in FF, be sure to go to about:config and change the browser.sessionstore.resume_from_crash setting to false, in order to disable the "Restore Previous Session" prompt. Lastly, be sure to disable any caching within the browser, in order to guarantee that the browser will render the most recent version of the content hosted at each URL.

6. Now we must remove potential false positives caused by Windows opening direct links using external applications (i.e., notepad). Open a new Windows Explorer window, and click on the Tools menu followed by Folder Options. Then select the File Types tab, and find the following entries, changing the Opens with reference to Internet Explorer:

CSS
LOG
BMP
DIB
EMF
GIF
JFIF
JPE
JPEG
JPG
PNG
SCT
TIF
TIFF
WMF

7. Next, you need to setup and configure the OS to auto-login as Administrator upon boot. The Microsoft Powertoy named TweakUI will help you set this. Download and install the TweakUI Microsoft Powertoy. For Windows XP SP0 and earlier, you may need to install an older version of TweakUI. Once installed, start the TweakUI application and go to the Logon section. Check the "Log on automatically at system startup" checkbox and provide the Administrator username and password accordingly. Save the changes and reboot the OS, to verify that the OS auto logs in as Administrator.

8. It is recommended that you shut down and power off the master VM, in order to save the entire contents of /vm/master to a backup location. Thus, if anything goes wrong with the subsequent steps, you can start from here, without having to go through the Windows installation process again.

Download, Install, and Configure Cygwin

In order for the HoneyClient perl code to execute inside the master VM, Cygwin needs to be installed. The code expects to use the Cygwin-based version of perl inside the master VM.
(Do NOT use ActiveState Perl; the code will not function properly with that version of perl.)

1. Download and install Cygwin. Along with the default packages, the following additional packages should be installed:

Devel
- gcc-core
- gcc-g++
- make
- patchutils
- subversion
Editors
- vim (or pick your favorite)
Net
- openssh
- ping
Perl
- perl
- perl-ExtUtils-Depends
- perl-ExtUtils-PkgConfig
- perl_manpages
Web
- wget

2. Once installed, start up the Cygwin shell for the first time (via the desktop shortcut or by running c:\cygwin\cygwin.bat). You'll probably need to run the following two commands within the shell, in order to initialize passwords and groups:

$ mkdir /etc
$ mkgroup -l > /etc/group
$ mkpasswd -l > /etc/passwd

3. In the Cygwin shell, set the timezone for the system (e.g., EST5EDT), using the following commands listed below:

$ echo "EST5EDT" > /etc/timezone

4. Close and restart the Cygwin shell, to verify all settings have been initialized.

5. In order for the HoneyClient::Agent code to execute automatically, you first need to configure the Cygwin shell to automatically start up upon automatic login. This can be accomplished by creating a Scheduled Task in Windows. Go to Control Panel, double-click on the Scheduled Tasks section, and double-click on the Add Scheduled Task icon to start the wizard. Browse for c:\cygwin\cygwin.bat as the program to run. Specify to start the program "When I log on", then specify the Administrator username and password. Finally, be sure to go into the scheduled task's properties and uncheck the "Stop the task if it runs for 72 hour(s) and 0 minute(s)" checkbox, in the Settings tab. Shutdown and reboot the master VM, in order to verify that the Cygwin shell starts up automatically.

Download the Honeyclient Package

1. Start a new Cygwin shell and change to the user's home directory (e.g., /home/Administrator).

2. Download the Honeyclient package, either from the SVN repository or from the website.

From SVN:

svn co svn://svn.honeyclient.org/honeyclient/tags/rel/1.0.2 honeyclient

Download and extract the latest version from the downloads page.

This guide assumes the data has been downloaded/extracted to the /home/Administrator/honeyclient directory.

Initialize CPAN

1. Before installing any HoneyClient packages, you have to initialize the cpan perl utility. Type cpan at the Cygwin shell prompt. The following example gives responses to the CPAN initialization questions.

If you are comfortable configuring CPAN, then only the following options need to differ from the defaults significantly. The example assumes your username is "Administrator" and your copy of the Honeyclient source is in the directory /home/Administrator/honeyclient.

Provide a custom build/cache directory:

CPAN build and cache directory? [/root/.cpan] /home/Administrator/honeyclient/cpan

And to install the perl requirements from the local copy (which is recommended) you should not use any online mirrors, and instead type:
```
cpan> o conf urllist file:///home/user/honeyclient/cpan
```

Note: Be sure to specify proxy servers in your CPAN configuration, if needed.

Install Perl Dependencies

1. Execute the following CPAN commands, but remember to check the known perl prompts if any unexpected prompts occur.

cpan> install Bundle::CPAN
...
CPAN is up to date.

cpan> reload cpan

$ cpan
cpan> install Bundle::HoneyClient::Util
...
/usr/bin/make install  -- OK

cpan> install Bundle::HoneyClient::Agent
...
/usr/bin/make install  -- OK

cpan> exit

If you do not see the "/usr/bin/make install -- OK" line after the last two commands, please report the full output that was generated.

TODO: Ideally, we would include something here about running the tests for HoneyClient::Util and HoneyClient::Agent. However, those unit tests are currently out-of-date, so we will not include testing instructions in this verison of the guide.

Install Capture

Starting with Honeyclient v1.0.1, the package now uses a modified version of the Capture-HPC code, in order to perform real-time integrity checks.

1. Inside the master VM, install the Microsoft Visual C++ 2005 Redistributable Package.

2. Run the modified CaptureBAT installer, by executing this file:

C:\cygwin\home\Administrator\honeyclient\thirdparty\capture-mod\CaptureBAT-Setup.nsi

3. Restart the master VM, after the installer completes.

4. Verify that Capture was installed correctly, by typing the following in a Cygwin shell:

~/honeyclient/thirdparty/capture-mod/CaptureBAT.exe

5. While this code is running, start a new process (e.g., notepad.exe), write a file to the disk, or make a innocuous change to the registry. Capture should output corresponding events to the shell window, as you perform each of these actions. If you see no output, please report the problem. Once you've verified that the code works properly, stop the Capture code by pressing CTRL-C or by pressing q and then <Return> in the Cygwin shell.

Configure HoneyClient::Agent

In order to properly start up the real-time integrity checker before the Agent code starts, we have provided a bin/bootstrap_agent.sh script which performs all the necessary tasks to execute the Agent code properly.

1. Verify the bin/bootstrap_agent.sh script executes properly inside the Cygwin shell, by typing the following:

$ ~/honeyclient/bin/bootstrap_agent.sh
Starting up Agent - (Hit CTRL-C multiple times to exit.)
...
URL: http://0.0.0.0:9000/HoneyClient/Agent

If everything is working perfectly, then the agent should be running and listening on TCP port 9000 inside the master VM — waiting for a connection from the manager. Press CTRL-C multiple times, to stop this daemon in the Cygwin shell.

Note: The default bin/bootstrap_agent.sh script pings a test server (pingu.honeyclient.org) and attempts to perform an SVN update. If you would prefer to have each VM not perform these operations by default, then edit the bin/bootstrap_agent.sh file and comment out those optional commands.

2. If the host system requires an upstream proxy server to access websites, then you should have set it in your browser preferences and/or internet options such that you can see that you can access web pages from within this master VM. Because we will also be accessing web content in perl, you should also make sure that you have set the "http_proxy" environment variable in the Cygwin shell (if required). Assuming your proxy server is "http://yourproxyaddress", then you should type the following command inside the Cygwin shell:

$ echo "export http_proxy=http://yourproxyaddress" >> ~/.bashrc

3. Next, add the bin/bootstrap_agent.sh script to your ~/.bashrc file, in order to have the Agent execute every time a Cygwin shell is opened. You can accomplish this by typing the following:

$ echo "~/honeyclient/bin/bootstrap_agent.sh" >> ~/.bashrc

4. Exit the Cygwin shell and start a new Cygwin shell. If configured properly, the Agent code should start up successfully.

5. Restart the master VM and verify that the OS reboots, logs in as Administrator, and successfully starts up the Agent code.

Finalize Master VM Settings

1. Once you've configured the master VM to automatically start the agent code upon boot, shutdown and power off the master VM. Next, edit the master's virtual machine settings in the console and make the following changes:

Select the Hardware tab.
In the Ethernet section, select the "Host-only" option. (Forces master VM to go through the firewall VM for network connectivity.)
Save changes.

2. With the master VM powered off, identify where the master VM directory and its main configuration file are located on the host system.
(In this example, we assume the directory is /vm/master and that the main configuration file is /vm/master/master.vmx.)

The manager code (specifically HoneyClient::Manager::VM) relies on the master VM to be at a specific hardware configuration level, in order for it to properly clone the master. In newer versions of VMware products, the vendor tends to change how VM data is stored, which compounds the cloning process (since different VMs at different hardware versions can not be cloned in the same fashion). Thus, we require you to check and set your master VM's hardware configuration level to a specific combination, since this particular configuration has been known to work reliably at this time.

Specifically, the following steps illustrate the process, using the aforementioned master VM example:

On the host system, edit the master VM's main configuration file (e.g., /vm/master/master.vmx).
Look for the following two lines. (Don't worry if the numbers are different.)
```
config.version = "8"
virtualHW.version = "4"
```

Change both lines to read:

config.version = "7"
virtualHW.version = "3"

Determine if the master VM's primary virtual harddisk is IDE or SCSI based.
If the master VM's primary harddisk is IDE-based, then you should see a line in the configuration like this:
```
ide0:0.fileName = "master.vmdk"
```
If the master VM's primary harddisk is SCSI-based, then you should see a line in the configuration like this:
```
scsi0:0.fileName = "master.vmdk"
```
For IDE-based master VM's, verify the following line exists:
```
ide0:0.mode = "persistent"
```
Note: If this line does NOT exist in the configuration, then you must add it as an additional line to the configuration. If the line exists but has a different value (e.g., undoable), then you need to change the value accordingly.
For SCSI-based master VM's, locate the following line:
```
scsi0:0.mode = "persistent"
```
Note: If this line does NOT exist in the configuration, then you must add it as an additional line to the configuration. If the line exists but has a different value (e.g., undoable), then you need to change the value accordingly.
Save the configuration changes.

3. Optional: Harden the master VM, as specified in the VM Hardening Guide.

4. Once these master VM settings are made, power the master VM back on, verify the OS still boots and automatically logs in as Administrator, as well as starts up the Agent code. Then, shutdown and power off the master VM. Look in the master VM configuration file, and verify that all the aforementioned changes to the configuration are still set properly. If VMware Server changed either of the config.version or virtualHW.version values back, then reset them back to the aforementioned defaults and save the changes.

5. Lastly, unregister the master VM (e.g., /vm/master/master.vmx) by performing the following steps on the host system:

# vmware-cmd -s unregister /vm/master/master.vmx
unregister(/vm/master/master.vmx) = 1

Drone Service

As of Honeyclient v1.0.1, we provide additional code that helps keep track of URL history, malware activity, and provides a method to coordinate Manager activity across multiple host systems. This code is known as the Drone service. It is a Ruby on Rails web service that need only be installed on a single system for multiple Managers to coordinate with.

1. To install, configure, and run the Drone service, please see the Drone User Guide.

Startup

With Drone Support (Default)

Once the host system, the firewall VM, and the master honeyclient VM have been setup, then you're ready to run the Honeyclient system from the host system. The following steps describe how to drive a single honeyclient to example websites with Drone support.

1. Make sure the Drone service is running, as specified in the Drone User Guide.

2. On the host system, edit the ~/honeyclient/etc/honeyclient.xml file.

Make sure this enable reference is set to 1 and that the url is set to the Drone web service (i.e., http://127.0.0.1:3000/hc_database/api if the Drone was installed on the host system).

<HoneyClient>
    <Manager>
        <Database>
            <enable description="Enables database operations. 1 enables, 0 disables." default="1">
                1
            </enable>
            <url description="The URL of the local Ruby web service, which interfaces with the local HoneyClient database.">
                http://127.0.0.1:3000/hc_database/api
            </url>
        </Database>
    </Manager>
</HoneyClient>

3. On the host system, verify that VMware Server is running on the host system. Start VMware Server, if it is not already running.

# /etc/init.d/vmware status
At least one instance of VMware Server is still running.

Bridged networking on /dev/vmnet0 is running
Host-only networking on /dev/vmnet1 is running
Host-only networking on /dev/vmnet8 is running
NAT networking on /dev/vmnet8 is running
Module vmmon loaded
Module vmnet loaded

4. On the host system, verify that the master honeyclient VM is shut down, powered off, and completely unregistered (i.e., VM does not appear in the VMware Server Console).

5. On the host system, power on the firewall VM and wait until this VM is fully booted.

6. On the host system, type:

cd ~/honeyclient
perl -Ilib bin/StartManager.pl

As the Manager starts, it will create a new clone VM that will have a random alphanumeric name of 26 characters in length. You can monitor the progress of this clone by connecting a VMware Server Console to the host system. Expect the clone VM to be disappear and reappear multiple times before finally booting.
The Manager will begin to poll for the existance of this new cloned VM. Expect the Manager to generate warnings, as it attempts to connect to the clone VM, while the clone is booting.
Once the clone is fully booted and has started the Agent daemon, then the Manager will contact the Drone database in order to obtain a new set of websites to visit.
Once a website has been queued in the Drone database, the Manager will contact the firewall to allow the clone access to the corresponding websites. Once the firewall is set, the Manager will then drive the Agent to these websites.
Once the Agent has visited a single website, the Agent will then perform an integrity check of the VM.
As the Agent runs and visits websites, the Manager will poll the Agent for status updates regularly.
If the Agent-based integrity check fails at any time, then the Manager will report the compromise, suspend the VM, and create a new honeyclient clone VM, which will continue to the next website to visit. Analysts are expected to view the compromise data by accessing the Drone interface with any browser, then resume suspended honeyclient clone VMs, in order to verify the compromises that have occurred. Additionally, an integrity report of what was compromised is currently written to the c:\cygwin\tmp\changes.txt file on the cloned honeyclient VM, as well as to the ~/honeyclient/fingerprint.dump file on the host system.
Furthermore, an archived copy of the clone VM is also saved to the /vm/snapshots directory in tar/gz format. That way, analysts have a backup copy of all suspended VMs, in case they need to reproduce malware activity.

TODO: If you need Firefox (FF) support, refer to ticket #62 on how to enable FF support.

7. To add new URLs for any host systems to visit, you have two supported methods:

Access the Drone web service:

http://<drone_ip_address>:3000/data/add_url

Manually feed URLs from the command line on the host system:

$ cd ~/honeyclient
$ vi bin/insert_queue_urls.pl
(Change the URLs to whatever you want.  The numbers indicate priority, where the higher the number equates to a higher priority.)
$ perl -Ilib bin/insert_queue_urls.pl

8. To terminate the Honeyclient system at any time, simply issue a single CTRL-C to the StartManager.pl perl process on the host system. Once interrupted, the Manager will suspend the active honeyclient clone and terminate its activity. The firewall code on the firewall VM will also reset; however, the firewall VM will remain booted and powered on. Lastly, the manager will generate a manager.dump file upon successful termination, to record the progress made by the Honeyclient system.

Without Drone Support (Not Default)

1. On the host system, edit the ~/honeyclient/etc/honeyclient.xml file.

Make sure this enable reference is set to 0.

<HoneyClient>
    <Manager>
        <Database>
            <enable description="Enables database operations. 1 enables, 0 disables." default="1">
                0
            </enable>
        </Database>
    </Manager>
</HoneyClient>

2. On the host system, verify that VMware Server is running on the host system. Start VMware Server, if it is not already running.

# /etc/init.d/vmware status
At least one instance of VMware Server is still running.

Bridged networking on /dev/vmnet0 is running
Host-only networking on /dev/vmnet1 is running
Host-only networking on /dev/vmnet8 is running
NAT networking on /dev/vmnet8 is running
Module vmmon loaded
Module vmnet loaded

3. On the host system, verify that the master honeyclient VM is shut down, powered off, and completely unregistered (i.e., VM does not appear in the VMware Server Console).

4. On the host system, power on the firewall VM and wait until this VM is fully booted.

5. On the host system, create a text file containing the list of (newline separated) URLs that you want honeyclients to browse. Call this file ~/honeyclient/urls.txt. For example, the file content can look like this:

http://www.google.com
http://www.cnn.com
http://www.slashdot.org

6. On the host system, type:

cd ~/honeyclient
perl -Ilib bin/StartManager.pl --url_list urls.txt

As the Manager starts, it will create a new clone VM that will have a random alphanumeric name of 26 characters in length. You can monitor the progress of this clone by connecting a VMware Server Console to the host system. Expect the clone VM to be disappear and reappear multiple times before finally booting.
The Manager will begin to poll for the existance of this new cloned VM. Expect the Manager to generate warnings, as it attempts to connect to the clone VM, while the clone is booting.
Once the clone is fully booted and has started the Agent daemon, then the Manager will contact the firewall to allow the clone access to the www.google.org website. Once the firewall is set, the Manager will then drive the Agent to this website.
Once the Agent has visited the specified website, the Agent will then perform an integrity check of the VM.
As the Agent runs and visits these websites, the Manager will poll the agent for status updates regularly.
If the Agent-based integrity check fails at any time, then the Manager will report the compromise, suspend the VM, and create a new honeyclient clone VM, which will continue to the next website to visit. Analysts are expected to resume suspended honeyclient clone VMs, in order to inspect the types of compromises that occur. Currently, an integrity report of what was compromised is currently written to the c:\cygwin\tmp\changes.txt file on the cloned honeyclient VM, as well as to the ~/honeyclient/fingerprint.dump file on the host system.
Furthermore, an archived copy of the clone VM is also saved to the /vm/snapshots directory in tar/gz format. That way, analysts have a backup copy of all suspended VMs, in case they need to reproduce malware activity.

TODO: If you need Firefox (FF) support, refer to ticket #62 on how to enable FF support.

7. To terminate the Honeyclient system at any time, simply issue a single CTRL-C to the StartManager.pl perl process on the host system. Once interrupted, the Manager will suspend the active honeyclient clone and terminate its activity. The firewall code on the firewall VM will also reset; however, the firewall VM will remain booted and powered on. Lastly, the manager will generate a manager.dump file upon successful termination, to record the progress made by the Honeyclient system.

Upgrading

Honeyclient

To upgrade the Honeyclient code, you'll need to update the code base on the host system and inside the master VM. As new stable versions of the code are released, we will provide you with additional upgrade instructions that may be specific from version to version.

Host System

To upgrade the entire code base to the latest version in trunk, type the following on the host system:

$ cd ~/honeyclient
$ svn update

Note: Review any changes you have made to the ~/honeyclient/etc/honeyclient.xml configuration file, to verify that all your settings have been preserved.

Master VM

Warning: Changing any information within your master VM will cause any existing cloned VMs to become corrupted. If this is an issue, then make a copy of your current master VM and apply these changes to the copy.

In order to switch the master VM back to persistent mode, you'll need to finalize the master VM settings, but switch the network to "NAT" and leave the master VM registered. Once this is done, power on the master VM and terminate any automatically running Honeyclient processes, once the Administrator automatically logs in.

Then, to upgrade the entire code base to the latest version in trunk, type the following in a Cygwin shell:

$ cd ~/honeyclient
$ svn update

Note: Review any changes you have made to the ~/honeyclient/etc/honeyclient.xml configuration file, to verify that all your settings have been preserved.

Or, to download the latest integrity exclusion lists but keep a stable version of the honeyclient code, type the following in a Cygwin shell:

$ cd ~/honeyclient/thirdparty/capture-mod
$ svn update

Shutdown and power off the master VM and finalize the master VM settings again (for the last time).

Drone

To upgrade the entire code base to the latest version in trunk, shut down any currently running drone web server and type the following on the drone system:

$ cd ~/drone
$ svn update
$ RAILS_ENV=production rake db:migrate

Notes

The following is a list of known, direct dependencies that the HoneyClient code has to external libraries.

HoneyClient::Util Dependencies

threads (needs to be upgraded)
threads::shared (needs to be upgraded)
File::Find::Rule
File::Find
Clone
Test::Pod
DateTime
HTML::Tagset
HTML::Parser
Class::MethodMaker
Test::Simple
Sub::Uplevel
Log::Log4perl
Sys::Syslog
Log::Dispatch::Syslog
MIME::Tools
LWP::UserAgent
SOAP::Lite
SOAP::Transport::HTTP
XML::Tidy
Module::Build
ExtUtils::MakeMaker

HoneyClient::Agent Dependencies

Algorithm::Diff
Data::Compare
Data::Diff
Data::Structure::Util
Data::Validate::URI
DateTime::HiRes
Digest::MD5
Digest::SHA
File::Temp
File::Type
Filesys::CygwinPaths
HTML::HeadParser
HTML::LinkExtor
HTTP::Request::Common
LWP::UserAgent
Log::Log4perl
Parse::Yapp::Driver
Search::Binary
Term::ProgressBar
Test::Exception
URI
URI::URL
Win32
Win32::Job
Win32::Exe
Term::ReadKey

HoneyClient::Manager Dependencies

Note: All VMware::VmPerl::* libraries can not be installed via CPAN. These libraries are automatically added to the host system, when VMware Server is installed.

DateTime::HiRes
DateTime::Format::ISO8601
File::Copy::Recursive
Log::Log4perl
Net::DNS::Resolver
VMware::VmPerl
VMware::VmPerl::ConnectParams
VMware::VmPerl::Question
VMware::VmPerl::Server
VMware::VmPerl::VM
Relations::Abstract
Relations::Query
DBI
DBD::mysql
Data::Validate::URI
Sys::Hostname::Long
Sys::HostIP
YAML::XS
XML::RPC
IPTables::IPv4
Proc::ProcessTable
Data::Structure::Util
Filesys::DfPortable
Pod::Usage
Text::DHCPLeases
DateTime::Format::Natural

Troubleshooting

Please see our issue list and FAQ, for all known issues. If you discover a particular problem that has not been previously documented, please open a new ticket.

Download in other formats:

Plain Text

Wiki Navigation

TracNav menu

Definitions

Terms

Components

FAQ

User Guide

Developer Guide

Methodologies

User Guide

Host System

Install and Configure Linux

Install VMware Server

Configure VMware Server

Download the Honeyclient Package

Initialize CPAN

Install Perl Dependencies

Configure HoneyClient::Manager

Firewall VM

Download Firewall VM

Initialize Firewall VM

Honeyclient VM

Create Master Honeyclient VM

Configure Windows OS

Download, Install, and Configure Cygwin

Download the Honeyclient Package

Initialize CPAN

Install Perl Dependencies

Install Capture

Configure HoneyClient::Agent

Finalize Master VM Settings

Drone Service

Startup

With Drone Support (Default)

Without Drone Support (Not Default)

Upgrading

Honeyclient

Host System

Master VM

Drone

Notes

HoneyClient::Util Dependencies

HoneyClient::Agent Dependencies

HoneyClient::Manager Dependencies

Troubleshooting

Download in other formats: