TracNav menu

Definitions

The Honeyclient architecture consists of the following terms and components:

  1. Network Terms
    1. Honeyclient VM
    2. Internal Network
    3. Firewall VM
    4. DMZ Network
    5. Host System
    6. Remote Resource
  2. Software Components
    1. HoneyClient::Agent
      1. HoneyClient::Agent::Driver
      2. HoneyClient::Agent::Driver::Browser
      3. HoneyClient::Agent::Driver::Browser::IE
      4. HoneyClient::Agent::Driver::Browser::FF
      5. HoneyClient::Agent::Integrity
        1. Registry
        2. File System
    2. HoneyClient::Manager
      1. HoneyClient::Manager::FW
      2. HoneyClient::Manager::VM
    3. HoneyClient::Util
      1. HoneyClient::Util::Config
      2. HoneyClient::Util::SOAP

Network Terms

The Architecture Definitions Diagram on the right illustrates each of the following network terms.

Architecture Definitions

Honeyclient VM

The Honeyclient VM (herein referred to as simply a "honeyclient") is a virtual machine (VM), designed to instrument (or drive) a locally running, target application to one or more remote resources. The purpose of this operation is to verify if the fetched content from each remote resource is malicious in nature, such that the honeyclient becomes compromised as a result of target application processing any of the content.

In this architecture, normal honeyclients are a:

  • VMware virtual machine
  • running a variant of the Microsoft Windows operating system
  • configured to automatically login as system administrator upon boot
  • and upon login, automatically execute the HoneyClient::Agent daemon inside a Cygwin environment

Note: Since Microsoft Windows is a commercial operating system, users are expected to create their own honeyclient, as directed in the user guide.

Internal Network

The Internal Network is a virtual, VMware host-only network designed to relay traffic between all honeyclients and the firewall.

Note: Users are expected to create this internal network upon configuring the host, as directed in the user guide.

Firewall VM

The Firewall VM (herein referred to as simply a "firewall") is a virtual machine (VM), designed to route and filter honeyclient traffic between the internal network and the DMZ network. As a honeyclient is driven to a remote resource, the firewall is configured to permit that honeyclient to access the minimum set of resources required to process all fetched content from the remote resource.

For example, if the host system were to drive a honeyclient to the http://www.cnn.com page, the firewall would allow the honeyclient to contact all web servers that mapped to www.cnn.com (including any additional servers that may host external inline content, such as externally linked advertisements from http://www.doubleclick.net) over TCP port 80. Once the firewall grants the honeyclient access, the honeyclient is then signaled to drive to www.cnn.com.

In this architecture, a firewall is a:

Note: Since variants of the Honeywall CDROM Roo distribution can be distributed freely, a pre-configured version of the Firewall VM is provided (as listed in the user guide). This allows users to quickly setup and configure this component — rather than installing and configuring a comparable VM from scratch.

Note: The HoneyClient::Manager::FW daemon can run on any Linux distribution running kernel version 2.4 or higher, as the daemon not does currently leverage any special features/functionality within the Roo distribution (other than iptables). However, expect this to change eventually, as the HoneyClient::Manager::FW daemon starts to use these distribution-specific capabilities.

DMZ Network

The DMZ Network is a virtual, VMware NAT-based network designed to relay traffic between the firewall and the internet.

Note: Users are expected to create this DMZ network upon configuring the host, as directed in the user guide.

Host System

The Host System (herein referred to as simply the "host") is a Linux-based physical server that manages the honeyclients. It also routes traffic between the honeyclients on the DMZ network and the Internet to allow them to access remote resources.

In this architecture, the host is a:

Note: Users are expected to create their own host, as directed in the user guide.

Note: The HoneyClient::Manager client can run on any Linux OS capable of running VMware Server.

Remote Resource

A Remote Resource (herein referred to as simply a "resource") is any networked server that is capable of delivering content to the honeyclient using known protocols over the Internet. For example, valid resources can be web servers, mail servers, and FTP servers.

Note: Currently, honeyclients only support target resources capable of making content available via the HTTP protocol. However, the driver architecture is extensible, so as more drivers are implemented other applications and protocols will be supported.

Component Definitions

Software Components

Fundamentally, the Honeyclient architecture is a client/server model implemented in Perl. The communications mechanism used is SOAP::Lite, which was chosen for its flexibility in supporting a wide range of protocols.

The Component Diagram on the right illustrates where each of the following components are located in the architecture. For further information, please see the Data Flow Diagram, which illustrates how each component communicates in this architecture.

HoneyClient::Agent

The Agent component is a Perl-based SOAP server, running as a daemon within the Cygwin environment on the honeyclient VM. Once the honeyclient OS boots and automatically logs in with Administrator privileges, this daemon is configured to startup by default.

The SOAP server services requests from the Manager, which include:

  • HoneyClient::Agent->run()
    • Instruments the target application via a specific driver implementation
  • HoneyClient::Agent->getState()
    • Reports the latest Driver state
  • HoneyClient::Agent->updateState()
  • HoneyClient::Agent->getStatus()
    • Reports statistical information about the current Driver state
  • HoneyClient::Agent->shutdown()
    • Shuts down the Agent

HoneyClient::Agent::Driver

The Driver component is a Perl-based interface (API) that defines and enforces common SOAP methods that every (derived) Driver object must implement. The intent of this package is to be the Perl equivalent to a Java Interface.

Each Driver implementation must define a corresponding work unit. This is the smallest repetitive action performed by the target application, where each action may cause the target application to process one or more resources (e.g., view one page, download one file, receive one e-mail).

Perl objects that implement the Driver interface, are solely designed to service local requests from the Agent, which include:

  • HoneyClient::Agent::Driver->new()
    • Creates a new object (complete with initial state) and initializes the target application for instrumentation
  • HoneyClient::Agent::Driver->drive()
    • Drives the target application for one work unit
  • HoneyClient::Agent::Driver->isFinished()
    • Signals when the Driver has exhausted all possible resources to process and requires additional input from the Manager (via the Agent) in order to proceed
  • HoneyClient::Agent::Driver->next()
    • Reports the next set of resources that the Driver will contact upon the next drive() call
      (This used to ultimately signal the firewall to allow the honeyclient to access the next set of resources, in order to properly allow the Driver to process the next work unit.)
  • HoneyClient::Agent::Driver->status()
    • Reports status information about the Driver's work unit progress so far

The architecture currently provides two Driver implementations that instrument the following target applications:

TODO: The rest of this page is currently a work-in-progress and is subject to change frequently. If you would like to monitor changes to this page, feel free to subscribe for notifications.

HoneyClient::Agent::Driver::Browser

HoneyClient::Agent::Driver::Browser::IE

  • Maintaining driver state, including keeping track of:
    • Resources the driver has processed
    • Resources the driver was unable to process (and has subsequently ignored)
    • Resources the driver has yet to visit

Note: The HoneyClient::Agent::Driver::Browser::IE package currently does not support the ability to properly render external inline content on any website.
This is a currently open issue, documented as ticket #27.

HoneyClient::Agent::Driver::Browser::FF

HoneyClient::Agent::Integrity

The Integrity component is a centralized interface for the Agent to easily access all integrity-checking capabilities.

An Integrity object offers the following public methods to the Agent:

  • HoneyClient::Agent::Integrity->new()
    • creates a new Integrity object and baselines the honeyclient OS, using all available child HoneyClient::Agent::Integrity::* packages
  • HoneyClient::Agent::Integrity->check()
    • checks the honeyclient OS against the previously recorded baseline, using all available child HoneyClient::Agent::Integrity::* packages, and reports a list of changes found within the honeyclient OS, if any were found
Registry

By default, the following registry hives in the Windows OS are checked: 

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

By default, all keys and values in these registry hives are analyzed — except for keys and values in the following regex paths: 

    $key_dirnames_to_ignore = [ 
        '^HKEY_CURRENT_USER\\\SessionInformation.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Internet Explorer\\\Main$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Internet Explorer\\\Security\\\AntiPhishing.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Internet Explorer\\\TypedURLs$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\MenuOrder\\\Favorites\\\Links.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\MountPoints2\\\CPC\\\Volume.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\UserAssist\\\.+\\\Count.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Ext\\\Stats\\\.+\\\iexplore.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Internet Settings\\\Connections.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Internet Settings\\\5.0\\\Cache.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\ShellNoRoam\\\BagMRU.*$',
        '^HKEY_CURRENT_USER\\\Software\\\Microsoft\\\Windows\\\ShellNoRoam\\\MUICache.*$',
        '^HKEY_CURRENT_USER\\\Volatile Environment$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Cryptography\\\RNG$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Windows\\\CurrentVersion\\\BITS$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Windows\\\CurrentVersion\\\Group Policy\\\State\\\Machine\\\Extension-List\\\.*$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Windows\\\CurrentVersion\\\WindowsUpdate\\\.*$',
        '^HKEY_LOCAL_MACHINE\\\SOFTWARE\\\Microsoft\\\Windows\\\CurrentVersion\\\WindowsUpdate\\\Auto Update.*$', 
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\.+\\\Parameters\\\Tcpip.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\Dhcp\\\Parameters.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\Eventlog\\\Application\\\ESENT.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\SharedAccess\\\Epoch.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\ControlSet.+\\\Services\\\Tcpip\\\Parameters\\\Interfaces\\\.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\CurrentControlSet\\\Services\\\Dhcp\\\Parameters.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\CurrentControlSet\\\Services\\\Eventlog\\\Application\\\ESENT.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\CurrentControlSet\\\Services\\\Tcpip\\\Parameters\\\Interfaces\\\.*$',
        '^HKEY_LOCAL_MACHINE\\\SYSTEM\\\CurrentControlSet\\\Services\\\.+\\\Parameters\\\Tcpip.*$',
        '^HKEY_USERS\\\.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\UserAssist\\\.+\\\Count.*$', 
        '^HKEY_USERS\\\.+\\\Software\\\Microsoft\\\Windows\\\ShellNoRoam\\\BagMRU.*$',
        '^HKEY_USERS\\\.+\\\UNICODE Program Groups.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Internet Explorer\\\Main$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Internet Explorer\\\Security\\\AntiPhishing.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Internet Explorer\\\TypedURLs$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\MenuOrder\\\Favorites\\\Links.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Explorer\\\MountPoints2\\\CPC\\\Volume.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Ext\\\Stats\\\.+\\\iexplore.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Internet Settings\\\Connections.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\CurrentVersion\\\Internet Settings\\\5.0\\\Cache.*$',
        '^HKEY_USERS\\\S.+\\\Software\\\Microsoft\\\Windows\\\ShellNoRoam\\\MUICache.*$',
    ];
File System

By default, all files and directories in the Windows OS file system are checked — except for files and directories in the following Cygwin-based regex paths: 

/cygdrive/c/cygwin/tmp/changes.txt
/cygdrive/c/cygwin/tmp/cleanfile.txt
/cygdrive/c/cygwin/home/Administrator/
/cygdrive/c/Documents and Settings/Administrator/Desktop/honeyclient
/cygdrive/c/WINDOWS/Prefetch/
/cygdrive/c/WINDOWS/WindowsUpdate.log
/cygdrive/c/WINDOWS/Debug/UserMode/userenv.log
/cygdrive/c/WINDOWS/SoftwareDistribution/DataStore/
/cygdrive/c/WINDOWS/SchedLgU.Txt
/cygdrive/c/WINDOWS/SoftwareDistribution/ReportingEvents.log
/cygdrive/c/WINDOWS/system32/config/SysEvent.Evt
/cygdrive/c/WINDOWS/system32/wbem/
/cygdrive/c/WINDOWS/PCHEALTH/HELPCTR/DataColl/
/cygdrive/c/Documents and Settings/All Users/Application Data/Microsoft/Network/Downloader/
/cygdrive/c/Documents and Settings/Administrator/Application Data/Mozilla/Firefox/Profiles/
/cygdrive/c/Documents and Settings/Administrator/Local Settings/Application Data/Mozilla/Firefox/Profiles/
/cygdrive/c/Documents and Settings/Administrator/Application Data/Talkback/MozillaOrg/Firefox15/Win32/2006050817/permdata.box
/cygdrive/c/Documents and Settings/Administrator/Cookies/index.dat
/cygdrive/c/Documents and Settings/Administrator/Local Settings/History/History.IE5/
/cygdrive/c/Documents and Settings/Administrator/Local Settings/Temporary Internet Files/Content.IE5
/cygdrive/c/Documents and Settings/Administrator/Recent/
/cygdrive/c/Program Files/Mozilla Firefox/updates/
/cygdrive/c/Program Files/Mozilla Firefox/active-update.xml
/cygdrive/c/Program Files/Mozilla Firefox/updates.xml
/cygdrive/c/WINDOWS/SoftwareDistribution/WuRedir/

HoneyClient::Manager

HoneyClient::Manager::FW

HoneyClient::Manager::VM

HoneyClient::Util

HoneyClient::Util::Config

HoneyClient::Util::SOAP

Note: Currently, all SOAP communication occurs using the HTTP protocol. By default, this protocol provides little security in terms of confidentiality and integrity. This is a known issue and has been documented as ticket #28 already. Eventually, the system will use certificate-based HTTPS mutual authentication instead.

Attachments